|Catalog Schema||Catalog Converters||Reference|
|JSON Schema||XML to JSON Converter|
(How do I use this?)
|XML Schema||JSON to XML Converter|
(How do I use this?)
The OSCAL catalog model was designed to represent security and privacy controls in standardized, machine-readable formats. The OSCAL catalog model standardizes the representation of control definitions from different sources (e.g., SP 800-53, ISO/IEC 27002, COBIT 5) allowing control information to be easily searched, imported, and exported by applications using a common format.
The OSCAL catalog model was designed to represent security and privacy controls; however, it may be possible to apply OSCAL to other applications related to safety, health, or other purposes. These other applications have not been explored so far.
Authors and Consumers
Catalogs are authored by an organization that defines or governs a set of controls, such as NIST with Special Publication (SP) 800-53.
Organizations may also author a catalog when they need to define a control not found in an existing control catalog.
As the catalog forms the foundation of OSCAL, the authors and consumers of all other OSCAL artifacts are catalog consumers.
An OSCAL catalog is organized as follows, which is based on the standard OSCAL document structure:
- Metadata: Metadata syntax is identical and required in all OSCAL models. It includes information such as the file's title, publication version, publication date, and OSCAL version. Metadata is also used to define roles, parties (people, teams and organizations), and locations.
- Parameter: Any parameter applicable to more than one control requirement statement in the catalog may be defined here.
- Control: Each control may contain control-specific parameters, control requirement statements, control objectives, assessment methods, references, and subordinate controls.
- Group: Related controls may be grouped. Parameters related to this group may be defined here.
- Back Matter: Back matter syntax is identical in all OSCAL models. It is used for attachments, citations, and embedded content such as graphics.
OSCAL catalogs define a complete set of controls. The primary use of the model is representing an entire collection of controls from an organization from which control baselines are created. The catalog model is also used to represent the tailored baseline resulting from a processed (resolved) profile.
In both uses, a catalog defines:
- An ability to group related controls at the discretion of the catalog author; and
- An ability to define individual controls, including:
- control parameters: a mechanism for the dynamic assignment of values in a control.
- control definition: a statement of the functionality or capability required to implement the control.
- control guidance: additional control implementation guidance, intended to supplement the control definition.
- control objectives: clearly stated objectives that should be achieved by a proper implementation of the control definition.
- assessment methods: prescribed actions for ensuring the control has been implemented consistent with its definition and achieving its objectives.
- related controls: identification of other controls in the catalog related to the control.
- references: supporting references related to the control.
See examples of OSCAL catalogs.
Important Note to Developers
Every time the content of an OSCAL file changes, the following must also change:
- A new UUID value must be generated and assigned to the root element's
last-modifiedfield in metadata must be assigned with the date and time at the moment the file is saved with the modified content.
These are two mechanisms by which tools can quickly "know" if a file has changed since it was last encountered. This document level UUID is the only UUID in OSCAL associated with version control.
When converting between formats, such as XML to JSON, these values should remain the same. This enables tools to know the content within the two formats is equivalent.
The NIST SP 800-53 revision 4 and 5 control catalogs are provided as catalog model examples in the OSCAL content GitHub repository. These examples are provided in OSCAL XML, JSON, and YAML formats.
NIST SP 800-53 Revision 4 Annotated Example
Here is a non-normative, partial illustration showing how control AC-1 from NIST SP 800-53 rev 4 can be rendered in OSCAL Catalog XML format with a
<control> element. A short walk-through follows.
The following is a non-normative, partial illustration showing how control AC-1 from NIST SP 800-53 Revision 4 can be rendered in OSCAL Catalog XML format with a
First we start with the following control text from SP 800-53.
AC-1 ACCESS CONTROL POLICY AND PROCEDURES
Control: The organization:
a. Develops, documents, and disseminates to [Assignment: organization-defined personnel or roles]:
- An access control policy that addresses purpose, scope, roles, responsibilities, management commitment, coordination among organizational entities, and compliance; and
- Procedures to facilitate the implementation of the access control policy and associated access controls; and
b. Reviews and updates the current:
- Access control policy [Assignment: organization-defined frequency]; and
- Access control procedures [Assignment: organization-defined frequency].
Supplemental Guidance: This control addresses the establishment of policy and procedures for the effective implementation of selected security controls and control enhancements in the AC family. Policy and procedures reflect applicable federal laws, Executive Orders, directives, regulations, policies, standards, and guidance. Security program policies and procedures at the organization level may make the need for system-specific policies and procedures unnecessary. The policy can be included as part of the general information security policy for organizations or conversely, can be represented by multiple policies reflecting the complex nature of certain organizations. The procedures can be established for the security program in general and for particular information systems, if needed. The organizational risk management strategy is a key factor in establishing policy and procedures.
Related control: PM-9.
Control Enhancements: None.
References: NIST Special Publications 800-12, 800-100.
This control has a number of high-level data elements, including a security control identifier ("AC-1"), a title ("ACCESS CONTROL POLICY AND PROCEDURES"), the control itself, supplemental guidance, control enhancements, and references. In contrast, the next control is from ISO 27002 on access control policy. It is also detailed in a different way, with an identifier ("9.1.1"), a title ("Access control policy"), control text, lengthy implementation guidance, and other information (additional advice on access control policy).
This control text is expressed in OSCAL as follows:
- The control class is "SP800-53". This serves as an indicator to a downstream processor of how it can expect this control to be structured.
- The control ID is "ac.1". All
idvalues are unique within the document and serve for addressing and linking. In the case of controls and subcontrols, the lexical form of the
idis designed to be consistent with its formal name or label, which is also encoded within the control (in this case, "AC-1"). A discrepancy between these values indicates degradation in the data.
<param>elements define parameter values for the control that permit (and may require) setting in context. Typically, a catalog will expose parameters where profiling applications are expected either to provide values themselves (appropriate to each profile) or to permit setting at higher levels of implementation. These values are available for assignment wherever indicated in the language of the control, using corresponding
<prop>elements specify properties appropriate to this control. Here only a
labelproperty is given, for the control's canonical label. For other catalogs, other properties may assign values to controls according to any system of labels or associations.
<part>elements indicate larger articulated structures. Here the part provides the statement for the control (as shown by its class). In SP 800-53, control statements give the text (formal prose definition and description) of the control. As the example shows, statements can also be articulated into subparts, with each discrete piece of the statement handled separately and assigned its own identifier.
<insert>elements reference parameters (
param-idreferencing parameter IDs) to bring in user-defined values.
The following snippet from the example above contains supplemental guidance given with the control (line breaks added for readability).
Note that unlike the control statement, which has a structure whose parts are labeled and addressable, the supplemental guidance is a simple paragraph. Where catalogs do not provide structure, OSCAL does not impose any.
Finally, the control description gives references for the control:
These can be resolved to elements elsewhere in the catalog, as for example here (a citation from this catalog to another NIST publication):
<ref id="ref050"> <citation href="http://csrc.nist.gov/publications/PubsSPs.html#800-12">NIST Special Publication 800-12</citation> </ref>
The following tutorial is provided related to the catalog model.
- Creating a Control Catalog: Covers overs creating a basic OSCAL control catalog.