The OSCAL Project has releases Milestone 3, Milestone 2 and Milestone 1, given here in reverse order of release date.
--
The models are described using OSCAL Metaschema terminology. Depending on the OSCAL representation you prefer (for example, XML or JSON), the object in question may be represented as a labeled property or unlabeled array member (in JSON) or as an element or attribute (XML). Similarly, in either case it may be an object with or without a nominal data value associated (such as at leaf nodes of the nominal information network), or alternatively a composite of other objects.
Refer to docs on Metaschema language and mappings into data objects, especially Terminology and Mapping.
Users of object notations should take note that individual objects described in the Metaschema model may, when serialized as JSON, take the form of array members without keys, the semantic key (a grouping key) being assigned to the group of like objects. So a 'prop' object defined in the Metaschema appears in the JSON as a member of an object 'properties'.
In the log below, [M3} indicates the Milestone 3 definitions, while [M2] indicates Milestone 2 definitions.
Assembly models are noted with DTD (RNC) notation indicating cardinality: suffix '' indicates zero-or-more, '+' is one-or-more, '?' is zero-or-one (i.e., optional), no indicator is used for one-only (required). So (a, b, b) and (a, b, c) are valid to pattern expression (a, b+, c), but (a, c) is not.
Changes in this release have been focused on the following major areas:
- Making naming in XML and JSON/YAML more consistent.
- Ensuring that all data types and cardinalities are appropriate.
- Refactoring to cleanup models, making them: 1) more consistent with the other OSCAL models, 2) making them more simple when possible, and 3) providing room for future addition of new features.
- many elements in XML, and properties in JSON and YAML, have been renamed to make the naming more consistent between elements names in XML and property names in JSON and YAML. Now JSON properties that contain an array of objects use a plural form of the XML element name. The one exception is "prop" in XML vs "properties" in JSON and YAML. This decision was made to make the XML use of "prop" more concise, since "prop" elements are used a good deal in OSCAL XML formats.
In {top-level-element}/metadata:
- renamed "revision-history" to "revisions"
- renamed "doc-id" to "document-id"
In {top-level-element}/metadata/document-id:
- renamed "type" to "scheme"
In {top-level-element}/metadata/link:
- Defined allowed values for the "rel" property
In {top-level-element}/metadata/location:
- renamed "email" to "email-address"
- renamed "phone" to "telephone-number"
In {top-level-element}/metadata/location/prop:
- Defined allowed values for the "name" attribute. Using the "type" as the name attribute value, you can now specify that a location is a "data-center" location and also use the "class" attribute to qualify the data center location as "primary" or "alternate".
In {top-level-element}/metadata/party:
- renamed "party-name" to "name"
- renamed "email" to "email-address"
- renamed "phone" to "telephone-number"
- changed sequencing of where "address" appears
- made use of address and location-uuid mutually exclusive, since either a static address or a reference to location provides similar functionality. The "location-type" attribute has been removed. This should data should now be described on the referenced "location" element using a prop element with a name of "type".
In {top-level-element}/metadata/party/prop:
- Defined allowed values for the "name" attribute. This can be used to provide a "mail-stop", "office", or "job-title".
In {top-level-element}/metadata/party/external-id:
- renamed "type" to "scheme"
In {top-level-element}/metadata/role:
- renamed "desc" to "description"
In {top-level-element}/back-matter/resource:
- renamed "desc" to "description"
- renamed "doc-id" to "document-id"
In {top-level-element}/back-matter/resource/prop:
- defined allowed values "type", "version", and "published" for the "name" property.
In {top-level-element}/metadata/resource/document-id:
- renamed "type" to "scheme"
In {top-level-element}/back-matter/resource/rlink:
- changed type from "uri" to "uri-reference"
Changes to all "prop" elements:
- changed the data type of "ns" to "uri"
- renamed "id" to "uuid" and changed type to "uuid"
Changes to all "annotation" elements:
- changed the data type of "ns" to "uri"
- renamed "id" to "uuid" and changed type to "uuid"
In {top-level-object}/metadata:
- renamed "revision-history" to "revisions"
- renamed "properties" to "props"
In {top-level-object}/metadata/revisions:
- renamed "properties" to "props"
In {top-level-object}/metadata/document-ids:
- renamed "type" to "scheme" and changed to data type from "string" to "uri"
In {top-level-object}/metadata/links:
- Defined allowed values for the "rel" property
In {top-level-object}/metadata/locations
- renamed "URLs" to "urls"
- renamed "properties" to "props"
In {top-level-object}/metadata/locations/props:
- Defined allowed values for the "name" property. Using the "type" prop name, you can now specify that a location is a "data-center" location and also use the "class" property to qualify the data center location as "primary" or "alternate".
In {top-level-object}/metadata/parties:
- renamed "party-name" to "name"
- renamed "properties" to "props"
- made use of addresses and location-uuids mutually exclusive, since either a static address or a reference to location provides similar functionality. The "location-type" property on "location-uuid" has been removed. This should data should now be described on the referenced "location" element using a prop element with a name of "type".
In {top-level-object}/metadata/parties/props:
- defined allowed values for the "name" property. This can be used to provide a "mail-stop", "office", or "job-title".
In {top-level-object}/metadata/parties/external-ids:
- renamed "type" to "scheme"
In {top-level-object}/metadata/roles:
- renamed "desc" to "description"
- renamed "properties" to "props"
In {top-level-object}/back-matter/resources:
- renamed "desc" to "description"
- renamed "properties" to "props"
In {top-level-object}/back-matter/resources/props:
- defined allowed values "type", "version", and "published" for the "name" property.
In {top-level-object}/back-matter/resources/citation:
- renamed "properties" to "props"
In {top-level-object}/back-matter/resources/document-ids:
- renamed "type" to "scheme" and changed to data type from "string" to "uri"
In {top-level-object}/back-matter/resources/rlinks:
- changed type from "uri" to "uri-reference"
Changes to all "props" objects:
- changed the data type of "ns" to "uri"
Changes to all "annotations" objects:
- changed the data type of "ns" to "uri"
- the "value" property is now required.
Changes to all "address" or "addresses" objects:
- renamed "postal-address" to "addr-lines"
Changes to all "responsible-party" objects:
- renamed "properties" to "props"
Changes to all "responsible-role" objects:
- renamed "properties" to "props"
- renamed "party-ids" to "party-uuids"
The following changes have been made to format structures that are shared between the formats for the catalog and profile models.
Changes to all "part" elements:
- changed the data type of "ns" to "uri"
Changes to all "param" elements:
- added the "prop" and "link" elements.
- changed the sequencing of where "link" appears to be consistent with other elements that include "link".
- changed the data type of "usage" from "markup-line" to "markup-multiline"
- changed "constraint" from an element with a text value, to an element with child elements. The text value is now contained in the "description" element. Also changed the "test" attribute to be a sequence of child "test" elements, with the text value now contained in the "expression" child element of "test". This structure will allow for more extension going forward.
- changed the cardinality of "value" to allow for multiple values". The data type of a value has changed from markup-line to string.
Changes to all "part" or "parts" objects:
- changed the data type of "ns" to "uri"
- renamed "properties" to "props"
- added allowed values "label" and "sort-id" for props/name.
Changes to all "param" or "params" objects:
- added the "props" and "links" properties.
- changed the data type of "usage" from "markup-line" to "markup-multiline"
- renamed "guidance" to "guidelines"
- renamed "value" to "values". Also, changed the cardinality of "value" to allow for multiple "values". The data type of a value has changed from markup-line to string.
- changed the sequencing of where "link" appears to align with similar elements in OSCAL.
For params/select/how-many:
- renamed "alternatives" to "choices"
For params/select/how-many/alternatives:
- renamed "RICHTEXT" property to "value"
For params/constraints:
- renamed "detail" to "description". Change the data type from "string" to "markup-multiline".
- renamed "test" to "tests", which is now an array of objects.
- The original "test" string value is now stored in the child object's "expression" property.
- Added a new "remarks" property.
The following changes have been made in the XML, JSON, and YAML formats for the OSCAL catalog model.
For /catalog//group and /catalog//control:
- defined allowed values for prop/@name
For /catalog, /catalog//groups, and /catalog//controls:
- renamed "parameters" to "params"
For /catalog//groups and /catalog//controls:
- renamed "properties" to "props"
- defined allowed values for props/name
The following changes have been made in the XML, JSON, and YAML formats for the OSCAL profile model.
For /profile/merge/custom//groups:
- added "annotation" and "link"
For /profile/modify/set-parameter:
- added "prop" and "annotation"
- change sequencing of where "link" appears
For /profile/modify/alter/add:
- defined allowed values for prop/@name
For /profile/imports/(include|exclude):
- renamed "id-selectors" to "calls"
- renamed "pattern-selectors" to "matches"
For /profile/merge/custom//groups:
- renamed "parameters" to "params"
- renamed "properties" to "props"
- added "annotations" and "links"
For /profile/modify:
- renamed "parameter-settings" to "set-parameters"
- renamed "alterations" to "alters"
For /profile/modify/set-parameters:
- added "props" and "annotations"
- renamed "usages" to "usage", and changed data type from an array of "string" to "markup-multiline"
For /profile/modify/alters:
- renamed "removals" to "removes"
- renamed "additions" to "adds"
For /profile/modify/alters/adds:
- renamed "parameters" to "params"
- renamed "properties" to "props"
- defined allowed values for props/name
A number of changes have been made to the SSP model to support the use of leveraged authorizations. Another key change is the use of the "this-system" component to define controls at the system-level. This now means that all SSPs will make use of at least one component.
The following changes have been made in the XML, JSON, and YAML formats for the OSCAL SSP model.
For /system-security-plan/system-characteristics:
- added allowed values for prop/@name, annotation/@name, link/@rel, and responsible-roles/role-id
For /system-security-plan/system-characteristics/*/diagram:
- added "annotation"
- changed the data type of "caption" from "string" to "markup-line"
- added allowed values for link/@rel="diagram", which allows for the linking of an image to use for the diagram.
For /system-security-plan/system-characteristics/system-information/information-type:
- renamed "id" to "uuid"
- changed structure of "information-type-id" to be wrapped by an outer "categorization", which now defines the "system" for all referenced information type identifiers.
- added "annotation"
For /system-security-plan/system-characteristics/system-information/information-type/*-impact:
- added "annotation" and "link"
For /system-security-plan/system-implementation/leveraged-authorization:
- defined additional allowed values "implementation-point", "leveraged-authorization-uuid", "inherited-uuid" for prop/@name, which provides traceability to a leveraged SSP
- defined allowed values for link/@rel
For /system-security-plan/system-implementation/user:
- defined allowed values for annotation/@name and role-id
For /system-security-plan/system-implementation/component:
- renamed "component-type" to "type", and updated allowed values
- defined allowed values for prop/@name, annotation/@name, link/@rel, and responsible-role/@role-id
For /system-security-plan/system-implementation/inventory-item:
- moved "@asset-id" to a required prop/@name
- defined allowed values for prop/@name, annotation/@name, link/@rel, and responsible-role/@role-id
For /system-security-plan/system-implementation/inventory-item/implemented-component:
- renamed "component-id" to "component-uuid"
- defined allowed values for prop/@name, annotation/@name, and responsible-party/@role-id
- removed "use", since this is capturing similar information to the component's type
For /system-security-plan/control-implementation/implemented-requirement:
- removed "description"
- added allowed values for annotation/@name including "implementation-status", "control-origination"
- added allowed values for prop/@name including "leveraged-authorization" to indicate if a control implementation is inherited from an underlying authorized system
- added allowed values for responsible-role/$role-id
- changed the sequencing of "set-parameter" and "responsible-role"
For /system-security-plan/control-implementation/implemented-requirement/by-component:
- renamed "component-id" to "component-uuid"
- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations
- added "remarks" to allow for adding general commentary
- changed the sequencing of where "set-parameter" appears
For /system-security-plan/control-implementation/implemented-requirement/statement:
- removed "description"
For /system-security-plan/control-implementation/implemented-requirement/statement/by-component:
- renamed "component-id" to "component-uuid"
- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations
- added "remarks" to allow for adding general commentary
- changed the sequencing of where "set-parameter" appears
For /system-security-plan/system-characteristics:
- renamed "properties" to "props"
- added allowed values for props/name, annotations/name, links/rel, and responsible-roles/role-id
For /system-security-plan/system-characteristics/*/diagrams:
- added "annotation"
- changed the data type of "caption" from "string" to "markup-line"
- added allowed values for link/@rel="diagram", which allows for the linking of an image to use for the diagram.
For /system-security-plan/system-characteristics/system-information:
- renamed "properties" to "props"
For /system-security-plan/system-characteristics/system-information/information-types:
- renamed "id" to "uuid"
- changed structure of "information-type-ids" to be wrapped by an outer "categorizations", which now defines the "system" for all referenced information type identifiers.
- added "annotations"
For /system-security-plan/system-characteristics/system-information/information-types/*-impact:
- added "annotations" and "links"
For /system-security-plan/system-characteristics/authorization-boundary:
- renamed "properties" to "props"
For /system-security-plan/system-characteristics/network-architecture:
- renamed "properties" to "props"
For /system-security-plan/system-characteristics/data-flow:
- renamed "properties" to "props"
For /system-security-plan/system-implementation:
- renamed "properties" to "props"
For /system-security-plan/system-implementation/leveraged-authorizations:
- defined additional allowed values "implementation-point", "leveraged-authorization-uuid", "inherited-uuid" for prop/name, which provides traceability to a leveraged SSP
- defined allowed values for links/rel
For /system-security-plan/system-implementation/users:
- defined allowed values for annotation/name and role-id
For /system-security-plan/system-implementation/components:
- renamed "component-type" to "type", and updated allowed values
- defined allowed values for props/name, annotations/name, links/rel, and responsible-roles/role-id
For /system-security-plan/system-implementation/inventory-items:
- moved "asset-id" to a required props/name
- defined allowed values for props/name, annotations/name, links/rel, and responsible-parties/role-id
For /system-security-plan/system-implementation/inventory-items/implemented-components:
- renamed "component-id" to "component-uuid"
- defined allowed values for props/name, annotations/name, and responsible-parties/role-id
- removed "use", since this is capturing similar information to the component's type
For /system-security-plan/control-implementation/implemented-requirements:
- removed "description"
- renamed "properties" to "props"
- added allowed values for annotations/name including "implementation-status", "control-origination"
- added allowed values for props/name including "leveraged-authorization" to indicate if a control implementation is inherited from an underlying authorized system
- added allowed values for responsible-roles/role-id
For /system-security-plan/control-implementation/implemented-requirements/by-components:
- renamed "component-id" to "component-uuid"
- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations
- added "remarks" to allow for adding general commentary
For /system-security-plan/control-implementation/implemented-requirements/statements:
- removed "description"
For /system-security-plan/control-implementation/implemented-requirements/statements/by-components:
- renamed "component-id" to "component-uuid"
- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations
- added "remarks" to allow for adding general commentary
Overall, this model was updated to bring the structure of components into alignment with how components are organized in the system security plan model.
The following changes have been made in the XML, JSON, and YAML formats for the OSCAL component definition model.
For /component-definition:
- added "uuid"
For /component-definition/component:
- removed "name"
- changed the data type of "title" from "string" to "markup-line"
- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper.
- added "prop" and "annotation"
- changed the sequencing of where "link" appears
- replaced "responsible-party" with "responsible-role"
- added "protocol", which can be used to specify protocol information for a "service" or "network" component
- changed "remarks" adding "remarks" wrapper
- defined allowed values for prop/@name, annotation/@name, link/@rel, and responsible-role/@role-id
- renamed "component-type" to "type", and updated allowed values
For /component-definition/component/control-implementation:
- changed data type of "uuid" from "string" to "uuid"
- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper.
For /component-definition/component/control-implementation/implemented-requirement:
- changed data type of "uuid" from "string" to "uuid"
- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper.
For /component-definition/capabilities:
- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper.
- changed "remarks" adding "remarks" wrapper
For /component-definition:
- added "uuid"
For /component-definition/components:
- removed "name"
- changed the data type of "title" from "string" to "markup-line"
- changed the data type of "description" from "string" to "markup-multiline"
- added "props" and "annotations"
- replaced "responsible-parties" with "responsible-roles"
- added "protocols", which can be used to specify protocol information for a "service" or "network" component
- defined allowed values for props/name, annotations/name, links/rel, and responsible-roles/role-id
- renamed "component-type" to "type", and updated allowed values
For /component-definition/components/control-implementations:
- changed data type of "uuid" from "string" to "uuid"
- changed the data type of "description" from "string" to "markup-multiline"
- renamed "properties" to "props"
For /component-definition/components/control-implementations/implemented-requirements:
- changed data type of "uuid" from "string" to "uuid"
- changed the data type of "description" from "string" to "markup-multiline"
- renamed "properties" to "props"
For /component-definition/capabilities:
- changed the data type of "description" from "string" to "markup-multiline"
- renamed "properties" to "props"
The assessment plan, assessment results, and plan of actions and milestones models have undergone some significant revisions. These revisions have been based on community feedback and a need to provide more extensibility for future growth. Extra review of these models is appreciated as we make preparations for the OSCAL 1.0.0 FINAL release.
Due to the nature of changes in this model, the following documentation details how the new model roughly maps to the older 1.0.0-milestone3 model. The following changes have been made in the XML, JSON, and YAML formats for the OSCAL assessment plan model.
/assessment-plan/local-definitions
- The structures located in /assessment-plan/assessment-subjects/local-definitions has been moved here. This includes the component, inventory-item, and user element constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level element.
- The "add-objectives-and-methods" element has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original elements located in /assessment-plan/objectives/objective and /assessment-plan/objectives/method.
- The "activity" element has been added to allow an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action.
/assessment-plan/terms-and-conditions
- This new element provides a means to include textual front matter in the assessment plan. This can be used to define rules of engagement, activities to include/exclude from assessments, instructions for delivering results, etc.
/assessment-plan/reviewed-controls
- This element includes constructs that previously appeared under /assessment-plan/objectives in the "controls" and "control-objectives" elements. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process.
/assessment-plan/assessment-subject
- This element replaces the previous /assessment-plan/assessment-subjects element.
- The old version intermixed included and excluded subjects of different types.
- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward.
/assessment-plan/assessment-assets
- This new element replaces the previous /assessment-plan/assets element.
- The old element allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools.
- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-component" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "prop" element on the "assessment-platform".
/assessment-plan/assessment-action
- This new element replaces the /assessment-plan/assessment-activities/test-method element.
- The old element required that information about an assessment process was defined by a "test-method".
- The new construction allows:
- The use of "associated-activity" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action elements.
- Use of "assessment-subject" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against.
- Use of the "responsible-role" element to identify assessment roles and optionally parties which are associated with the action.
/assessment-plan/task
- This element updates the old element located in /assessment-plan/assessment-activities/schedule/task
- "title" is now required.
- "activity-uuid" is replaced with "related-action".
- "party-uuid" and "location-uuid" is now specified on a per-action basis using the referenced "assessment-action" element's "assessment-subject" entries, which allows both parties and locations to be subjects.
- "compare-to" has been removed, since this was intended to be used in assessment-results only.
/assessment-plan/local-definitions
- The structures located in /assessment-plan/assessment-subjects/local-definitions has been moved here. This includes the components, inventory-items, and users object constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level element.
- Use of "protocols" has been removed in lieu of defining "network" or "service" components under local-definitions.
- The "add-objectives-and-methods" object array has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original objects located in /assessment-plan/objectives/objectives and /assessment-plan/objectives/method-definitions.
- The "activities" object array has been added to allow an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action.
/assessment-plan/terms-and-conditions
- This new object provides a means to include textual front matter in the assessment plan. This can be used to define rules of engagement, activities to include/exclude from assessments, instructions for delivering results, etc.
/assessment-plan/reviewed-controls
- This element includes constructs that previously appeared under /assessment-plan/objectives in the "control-group" and "control-objective-group" object arrays. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process.
/assessment-plan/assessment-subject
- This element replaces the previous /assessment-plan/assessment-subjects element.
- The old version intermixed included and excluded subjects of different types.
- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward.
/assessment-plan/assessment-assets
- This new element replaces the previous /assessment-plan/assets element.
- The old element allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools.
- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-components" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "props" object array on an "assessment-platforms" array item object.
/assessment-plan/assessment-actions
- This new element replaces the /assessment-plan/assessment-activities/test-methods element.
- The old element required that information about an assessment process was defined by "test-methods".
- The new construction allows:
- The use of "associated-activities" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action elements.
- Use of "assessment-subjects" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against.
- Use of the "responsible-roles" to identify assessment roles and optionally parties which are associated with the action.
/assessment-plan/tasks
- This element updates the old element located in /assessment-plan/assessment-activities/schedule/tasks
- "title" is now required.
- "activity-uuids" is replaced with "related-actions".
- "party-uuids" and "location-uuids" are now specified on a per-action basis using the referenced "assessment-action" object's "assessment-subjects" array items, which allows both parties and locations to be subjects.
- "compare-to" has been removed, since this was intended to be used in assessment-results only.
Due to the nature of changes in this model, the following documentation details how the new model roughly maps to the older 1.0.0-milestone3 model. The following changes have been made in the XML, JSON, and YAML formats for the OSCAL assessment results model.
/assessment-results
- Most of the top-level elements in this model have been relocated under the "result" element or it's children. This allows the assessment details to be specified for each result set. This better supports continuous and evolving assessments.
/assessment-results/local-definitions
- The "objective" element relocates and updates the old element in /assessment-results/objectives/objective allowing new assessment objectives to be defined that were not defined in the catalog supporting the system's baseline or the assessment plan.
- The new "activity" element is similar to the related one in the assessment plan, and allows an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action.
/assessment-results/results/local-definitions
- The structures located in /assessment-results/assessment-subjects/local-definitions has been moved here. This includes the "component", "inventory-item", and "user" element constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level element.
- The "add-objectives-and-methods" element has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original elements located in /assessment-results/objectives/objective and /assessment-results/objectives/method. /assessment-results/results/assessment-actions
- The "assessment-action" element replaces the /assessment-plan/assessment-activities/test-methods element.
- The old element required that information about an assessment process was defined by "test-methods". This structure was moved to local-definitions, since this is adding to the actions defined in the assessment plan.
- The new construction allows:
- The use of "associated-activities" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action elements.
- Use of "assessment-subjects" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against.
- Use of the "responsible-roles" to identify assessment roles and optionally parties which are associated with the action.
/assessment-results/results/reviewed-controls
- This element includes constructs that previously appeared under /assessment-results/objectives in the "controls" and "control-objectives" elements. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process.
/assessment-results/results/assessment-subject
- This element replaces the previous /assessment-results/assessment-subjects element.
- The old version intermixed included and excluded subjects of different types.
- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward.
/assessment-results/results/assessment-assets
- This new element replaces the previous /assessment-results/assets element.
- The old element allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools.
- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-components" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "props" object array on an "assessment-platforms" array item object.
/assessment-results/results/attestation
- This new element allows for arbitrary statements to be made in the assessment results.
/assessment-results/results/assessment-log
- This new element implements the functionality previously supported by the /assessment-results/assessment-activities/schedule/tasks element, but in a refactored way.
- An "entry" can be used to log any event that occurs during an assessment.
- An "entry" can be associated with an action or a task. An action is a concrete activity that is performed during an assessment, while a task is a high-level scheduled event used for project management that may be associated with multiple actions. The two can be used together to detail the work accomplished during the assessment.
- The "related-action" element can associate the log entry with an action declared in the plan or the results to record progress on or completion of the action. The "related-action" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject".
- The "related-task" element can associate the log entry with a task declared in the plan to record progress on or completion of the task. The "related-task" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject".
- "title" is now required.
- "activity-uuids" is replaced with "related-actions".
- "party-uuids" and "location-uuids" are now specified on a per-action basis using the referenced "assessment-action" object's "assessment-subjects" array items, which allows both parties and locations to be subjects.
/assessment-results/results/observation
- This element updates the old element located in /assessment-results/results/finding/observation. Observations have been separated out from findings to allow a given observation to be linked to by many findings and risks.
- renamed "observation-method" to "method"
- renamed "observation-type" to "type"
- "assessor" has been replaced with "origin", which allows the tool, assessment-platform, and/or any parties to be identified as one or more "actor" elements. The related action and/or task can also be associated here using "related-action" and "related-task".
/assessment-results/results/risk
- This element updates the old element located in /assessment-results/results/finding/risk. Risks have been separated out from findings to allow a given risk to be linked to by many findings.
- Renamed "risk-status" to "status"
- The new "origin" element can be used to describe the tool or party that generated the risk record.
- Replaced "risk-metric" with "characterization", which allows any risk characteristic to be as a "facet". The specific tool, assessment-platform, and/or any parties producing a characterization can be identified using one or more "actor" elements. The related action and/or task can also be associated here using "related-action" and "related-task".
- All remediation related contents has been moved to "response", which will be discussed below.
- A "risk-log/entry" can be used to identify any action that relates to the assessment of or handling of a risk. This replaces the "/assessment-results/results/risk/remediation-tracking", while proving more robust capabilities.
- "party-id" has been replaced with identifying the party as an actor under "origin".
/assessment-results/results/risk/response
- This new element realigns all of the risk/remediation information in a way that supports other risk response activities in addition to remediation.
- "origin" allows the tool, assessment-platform, and/or party identifying the response to be identified, replacing /assessment-results/results/risk/remediation-origin.
- "task" is used to define a schedule of events replacing /assessment-results/results/risk/remediation-deadline and /assessment-results/results/risk/remediation/schedule/task. This allows risk responses to be defined in a more fine-grained way.
- Renamed "required" to "required-asset"
/assessment-results/results/finding
- This element maps to the same element in the old model.
- Moved the embedded "observation" and "risk" elements to "related-observation" and "associated-risk" references.
/assessment-results
- Most of the top-level properties in this model have been relocated under the "results" property or it's child objects. This allows the assessment details to be specified for each result set. This better supports continuous and evolving assessments.
/assessment-results/local-definitions
- The "objectives" object array relocates and updates the old object array in /assessment-results/objectives/objectives allowing new assessment objectives to be defined that were not defined in the catalog supporting the system's baseline or the assessment plan.
- The new "activities" object array is similar to the related one in the assessment plan, and allows an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action.
/assessment-results/results/local-definitions
- The structures located in /assessment-results/assessment-subjects/local-definitions has been moved here. This includes the "components", "inventory-items", and "users" property constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level property.
- The "add-objectives-and-methods" property has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original properties located in /assessment-results/objectives/objectives and /assessment-results/objectives/methods. /assessment-results/results/assessment-actions
- The "assessment-action" property replaces the /assessment-plan/assessment-activities/test-methods property.
- The old property required that information about an assessment process was defined by "method-definitions". This structure was moved to local-definitions, since this is adding to the actions defined in the assessment plan.
- The new construction allows:
- The use of "associated-activities" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action properties.
- Use of "assessment-subjects" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against.
- Use of the "responsible-roles" to identify assessment roles and optionally parties which are associated with the action.
/assessment-results/results/reviewed-controls
- This property includes constructs that previously appeared under /assessment-results/objectives in the "controls_group" and "control-objectives_group" properties. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process.
/assessment-results/results/assessment-subjects
- This property replaces the previous /assessment-results/assessment-subjects property.
- The old version intermixed included and excluded subjects of different types.
- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward.
/assessment-results/results/assessment-assets
- This new property replaces the previous /assessment-results/assets property.
- The old property allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools.
- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-components" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "props" object array on an "assessment-platforms" array item object.
/assessment-results/results/attestations
- This new property allows for arbitrary statements to be made in the assessment results.
/assessment-results/results/assessment-log
- This new property implements the functionality previously supported by the /assessment-results/assessment-activities/schedule/tasks property, but in a refactored way.
- An "entry" can be used to log any event that occurs during an assessment.
- An "entry" can be associated with an action or a task. An action is a concrete activity that is performed during an assessment, while a task is a high-level scheduled event used for project management that may be associated with multiple actions. The two can be used together to detail the work accomplished during the assessment.
- The "related-actions" property can associate the log entry with an action declared in the plan or the results to record progress on or completion of the action. The "related-action" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject".
- The "related-tasks" property can associate the log entry with a task declared in the plan to record progress on or completion of the task. The "related-task" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject".
- "title" is now required.
- "activity-uuids" is replaced with "related-actions".
- "party-uuids" and "location-uuids" are now specified on a per-action basis using the referenced "assessment-action" object's "assessment-subjects" array items, which allows both parties and locations to be subjects.
/assessment-results/results/observation
- This property updates the old property located in /assessment-results/results_group/findings/observations. Observations have been separated out from findings to allow a given observation to be linked to by many findings and risks.
- renamed "observation-method" to "method"
- renamed "observation-type" to "type"
- "assessor" has been replaced with "origin", which allows the tool, assessment-platform, and/or any parties to be identified as one or more "actor" properties. The related action and/or task can also be associated here using "related-action" and "related-task".
/assessment-results/results/risks
- This property updates the old property located in /assessment-results/results_group/findings/risks. Risks have been separated out from findings to allow a given risk to be linked to by many findings.
- Renamed "risk-status" to "status"
- The new "origin" property can be used to describe the tool or party that generated the risk record.
- Replaced "risk-metric" with "characterization", which allows any risk characteristic to be as a "facet". The specific tool, assessment-platform, and/or any parties producing a characterization can be identified using one or more "actor" properties. The related action and/or task can also be associated here using "related-action" and "related-task".
- All remediation related contents has been moved to "response", which will be discussed below.
- A "risk-log/entry" can be used to identify any action that relates to the assessment of or handling of a risk. This replaces the "/assessment-results/results_group/risks/remediation-tracking" and "/assessment-results/results_group/risks/closure-actions", while proving more robust capabilities.
- "party-ids" has been replaced with identifying the party as an actor under "origin".
/assessment-results/results/risks/responses
- This new property realigns all of the risk/remediation information in a way that supports other risk response activities in addition to remediation.
- "origin" allows the tool, assessment-platform, and/or party identifying the response to be identified, replacing /assessment-results/results_group/risks/remediation-group/origins.
- "task" is used to define a schedule of events replacing /assessment-results/results_group/risks/remediation-deadline and /assessment-results/results_group/risks/remediation-group/schedule/tasks. This allows risk responses to be defined in a more fine-grained way.
- Renamed "required" to "required-asset"
/assessment-results/results/findings
- This property maps to the same property in the old model.
- Moved the embedded "observation" and "risk" properties to "related-observation" and "associated-risk" references.
Due to the nature of changes in this model, the following documentation details how the new model roughly maps to the older 1.0.0-milestone3 model. The following changes have been made in the XML, JSON, and YAML formats for the OSCAL PO&M model.
- The PO&M XML format has been updated to align with the assessment results XML format. Most of the changes in the previous section related to assessment results apply here.
/plan-of-action-and-milestones/poam-item
- Like the assessment results, the "poam-item" now has the "observation" and "risk" elements broken out as siblings and references to these elements are used instead.
- Removed "objective-status" and "implementation-status-uuid, since this was added here by mistake and is covered in the assessment results.
- The PO&M JSON and YAML format has been updated to align with the assessment results JSON and YAML format. Most of the changes in the previous section related to assessment results apply here.
/plan-of-action-and-milestones/poam-items
- Replaces /plan-of-action-and-milestones/poam-items/poam-item-group
- Like the assessment results, the "poam-items" now has the "observation" and "risk" elements broken out as siblings and references to these objects are used instead.
- Removed "objective-status" and "implementation-status-uuid, since this was added here by mistake and is covered in the assessment results.
--
The following new models have been added to OSCAL.
- Component Definition model: Allows for the definition of a set of components that each provide a description of the controls supported by a specific implementation of a hardware, software, or service; or by a given policy, process, procedure, or compliance artifact (e.g., FIPS 140-2 validation).
- Assessment Plan model: Represents the planning for a periodic or continuous assessment.
- Assessment Results model: Represents the findings of a periodic or continuous assessment of a specific system.
- Plan of Action and Milestones (POA&M) model: Represents the known risks for a specific system, as well as the identified deviations, remediation plan, and disposition status of each risk.
On several assemblies, what had been represented with a 'name' flag is now represented with a 'title' field, which permits inline markup.
'title' now appears in these assemblies: 'metadata', 'revision', 'location', 'resource', 'role', 'information-type', 'leveraged-authorization', 'user', 'authorized-privilege', 'component', and 'protocol'.
A number of assemblies that used to carry 'id' flags now carry 'uuid' flags instead. These include (in the SSP model) : 'location', 'party', 'resource', 'diagram', 'user', 'component', 'protocol', 'inventory-item', 'implemented-requirement', 'statement', and 'by-component'. In all models, it includes 'location', 'party', and 'resource'. Finally, the full assemblies 'catalog', 'profile' and 'system-security-plan' fall into this category.
Similarly, flags and fields that are named to indicate they provide a point of reference, are now renamed '-uuid' reflecting when their references is given specifically as a 'uuid' (and validated as such) not as an 'id'. These include 'location-uuid' and 'party-uuid'.
Milestone 3 has two assemblies in the metadata, revision for tracking a revision history, and location, an abstraction (and alternative) to the older address modeling.
[M2] model: title (field), published? (field), last-modified (field), version (field), oscal-version (field), doc-id* (field), prop* (field), link* (field), role* (assembly), party* (assembly), responsible-party* (assembly), remarks? (field)
[M3] model: title (field), published? (field), last-modified (field), version (field), oscal-version (field), revision* (assembly), doc-id* (field), prop* (field), link* (field), role* (assembly), location* (assembly), party* (assembly), responsible-party* (assembly), remarks? (field)
Tracking revisions can now be done by capturing a snapshot of metadata at an earlier point, potentially with properties or remarks added to indicate revision status or purpose.
[M3] model: title? (field), published? (field), last-modified? (field), version? (field), oscal-version? (field), prop* (field), link* (field), remarks? (field)
A new assembly permits factoring out geographic or contact information (an address or contact point) into a separate data structure, for reference using its 'uuid' flag.
[M3] model: title? (field), address (assembly), email* (field), phone* (field), url* (field), prop* (field), annotation* (assembly), link* (field), remarks? (field)
'party' is for Party (organization or person). It has been refactored to reflect the (somewhat arbitrary) 'organization' vs 'person' distinction into a 'type' flag.
Where before, we had an 'id' flag, now we have 'uuid'. We also have 'type', a flag whose value can capture "person" or "organization".
We also have new fields for linking to other assemblies, including 'member-of-organization'. Instead of 'org-name' and 'person-name' we simply have 'party-name'.
[M2] flags: id?
[M3] flags: uuid?, type?
[M2] model: person* (assembly), org? (assembly), prop* (field), annotation* (assembly), link* (field), remarks? (field)
[M3] model: party-name (field), short-name? (field), external-id* (field), prop* (field), annotation* (assembly), link* (field), address* (assembly), email* (field), phone* (field), member-of-organization (field), location-uuid (field)**, remarks? (field)
Replaces 'person/id' and 'org/id' from the M2 model.
Replaces 'party-id' and 'org-id' from the M2 model.
Used to associate a person or organization with another organization. This can be used to create organization hierarchies.
Replaces 'org-name' and 'person-name' from the M2 model.
In the back matter, the old 'citation' element has been refactored as a special case of 'resource'.
[M2] model: citation* (assembly), resource* (assembly)
[M3] model: resource* (assembly)
The old 'citation' assembly is now a child, not a sibling of resource within 'back-matter'. As such it has been remodeled to support as much specialized citation information as may be available for a resource.
[M2] flag: id?
[M3] flags: uuid?
[M2] model: desc? (field), prop* (field), (A choice: rlink* (assembly), base64? (field) ) , remarks? (field)
[M3] model: title? (field), desc? (field), prop* (field), doc-id* (field), citation? (assembly), rlink* (assembly), base64* (field), remarks? (field), (any)
New assemblies and fields to support the citation model.
A plain-text capture of a bibliographic citation.
A structured representation of a bibliographic resource (an extension point).
A 'citation' now appears only as a child of a 'resource'.
[M2] flag: id?
[M3] flag: [none]
[M2] model: target* (field), title? (field), desc? (field), doc-id* (field), prop* (field), ? (any)
[M3] model: text (field), prop* (field), biblio? (assembly)
A new 'id-ref' flag permits targeting an addition to a particular object (branch) within the structure addressed for addition. Additionally, an 'annotation' element may also be added.
[M2] flag: position?
[M3] flags: position?, id-ref?
[M2] model: title? (field), param* (assembly), prop* (field), link* (field), part* (assembly)
[M3] model: title? (field), param* (assembly), prop* (field), annotation* (assembly), link* (field), part* (assembly)
An assembly for 'leveraged-authorization' has been added. 'leveraged-authorization' used to be in 'system-characteristics'.
[M2] model: prop* (field), annotation* (assembly), link* (field), user* (assembly), component* (assembly), service* (assembly), interconnection* (assembly), system-inventory? (assembly), remarks? (field)
[M3] model: prop* (field), annotation* (assembly), link* (field), leveraged-authorization* (assembly), user* (assembly), component* (assembly), system-inventory? (assembly), remarks? (field)
The component assembly has been remodeled to permit greater generality and expressiveness. New assemblies include 'title', 'purpose', and 'protocol'.
[M2] flags: id?, name?, component-type?
[M3] flags: uuid?, component-type?
[M2] model: description (field), prop* (field), annotation* (assembly), link* (field), status (assembly), responsible-role* (assembly), remarks? (field)
[M3] model: title (field), description (field), purpose? (field), prop* (field), annotation* (assembly), link* (field), status (assembly), responsible-role* (assembly), protocol* (assembly), remarks? (field)
In profile SSP models, the assembly used to set a parameter is consistently called 'set-parameter'.
--
- A System Security Plan (SSP) model has been added to OSCAL for use by organizations to document the implementation of security and privacy controls in an information system.
The following content model changes have been made to the catalog and profile models that may break content compatibility:
last-modifiedis now required. Its value must be a date-time with time zone (i.e., a timestamp). The old elementlast-modified-dateis no longer permitted.publishedis permitted for a nominal publication date, as assigned by the owner or publisher of the catalog or resource. An electronic version of a previously published catalog should carry its own publication date, if any, not that of the original resource (which can be described elsewhere with its own metadata).role-idis now assigned as an element in the XML, not an attribute. This permits it to be tokenized more explicitly.
In the SP800-53 catalog, we have added a property called sort-id to controls and enhancements. Its string value represents the control's ID in a (zero-padded) notation that will sort gracefully against other sort-id values. This permits a robust reordering of controls in receiving systems without having to refer to an out-of-line document to restore the canonical order.
Control enhancements are now represented using control not subcontrol. The advantages of restricting to two levels of hierarchy (even given groups and parts) became too few in view of the sacrifices to expressiveness so we have gone back to clean recursion.
Data type handling has been extended in several respects to provide for the validating of lexical forms of nominal datatypes. Datatypes for dates and times have been added. Several XML-peculiar datatypes have been removed.
The schema has also been extended to support validation against enumerated values, either exclusively (only declared values may appear) or inclusively (enumerations are documented while other values are also permitted). All allowed values now being declared (Milestone 2) are inclusive of other values (user- or application-defined), so this is not a breaking change.
Affected data points (in both models): prop/name, address/type, phone/type, hash/algorithm, role-id. The enumerated values provided for each are documented.
Supported for lexical datatyping has also been added to link/href, rlink/href (URI references), published and last-modified (timestamps), email (a nominal email address), url (a URI), img/src.
From call statements, since subcontrol has been dropped from the catalog model, subcontrol-id has been replaced with control-id, and with-subcontrols has been replaced by with-child-controls (on call, all and match). Essentially, a subcontrol is now represented as a control that is a child another parent control.
Elements besides control references are now permitted inside group within the merge construct, so profile authors can provide titles and introductory content to groups they define for their represented aggregate control structures.
Added 'guideline' to profile model. It was omitted in error.
XXX see Issues #494, #288 (adding 'guideline' to profile model)
--
- The first official OSCAL release
- Provides stable versions of the OSCAL catalog and profile models in XML and JSON formats, along with associated XML and JSON schemas.
- Includes draft versions of the NIST SP 800-53 revision 4 OSCAL content and FedRAMP baselines in OSCAL XML, JSON, and YAML formats.
- Provides content converters that are capable of accurately converting between OSCAL catalog and profile content in OSCAL XML to OSCAL JSON format and vice versa.