Skip to content

Commit

Permalink
Support for control mapping (#1150)
Browse files Browse the repository at this point in the history 
* Added mapping model supporting mapping controls and control statements between two catalogs.
* Adjusted relationships based on PR #1150 discussions. Added type enumerations.
* Included a simple example
  • Loading branch information
@david-waltermire @aj-stein-nist
david-waltermire authored and aj-stein-nist committed Jul 10, 2023
1 parent ef28023 commit d145dfe
Show file tree
Hide file tree
Showing 6 changed files with 244 additions and 57 deletions.
37 changes: 37 additions & 0 deletions src/metaschema/examples/cis-sp-800-53-mapping.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- This is a mapping example used for development. This file should be moved to the oscal-content repo when this feature is ready. -->
<mapping-collection xmlns="http://csrc.nist.gov/ns/oscal/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/1.0 oscal-complete.xsd" uuid="3559d200-4849-41ac-a420-28b2ffa22c52">
<metadata>
<title>Example mapping between CIS controls and SP 800-53 rev5</title>
<last-modified>2022-04-13T08:37:21.323321800-04:00</last-modified>
<version>0.0.1</version>
<oscal-version>1.1.0</oscal-version>
</metadata>
<mapping uuid="9eb2019c-f3be-4f96-947e-58876a46b2a9">
<source-resource type="catalog" href="#a84961de-55ae-4bf3-a2d3-86cc32b651af"></source-resource>
<target-resource type="catalog" href="#711085f6-c390-4b25-b5f1-30066a56073d"></target-resource>
<map uuid="6a9a1161-770e-4556-9740-41e1809e14ea">
<!-- Note: Once issue #1332 is resolved, one of the new relationships can be used, in place of subset-of, to represent that cis-1.1 is a stricter version of the same requirements defined by the combination of {cm-8 and cm-8.1}. -->
<relationship>subset-of</relationship>
<source type="control" id-ref="#cis-1.1"/>
<target type="control" id-ref="#cm-8">
<!-- TODO: consider a way to reference parameters allowing the review period of at least bi-annually to be described. This would allow for equivalent-to to be used. -->
<!-- <using-param id="cm-08_odp.02">at least bi-annually</using-param>-->
</target>
<target type="control" id-ref="#cm-8.1"/>
<remarks>
<p>The combination of SP 800-53 CM-8 and CM-8(1) describe similar implementation requirements to CIS 1.1.</p>
</remarks>
</map>
</mapping>
<back-matter>
<resource uuid="a84961de-55ae-4bf3-a2d3-86cc32b651af">
<rlink href="cis-catalog.xml" media-type="application/oscal+xml"/>
</resource>
<resource uuid="711085f6-c390-4b25-b5f1-30066a56073d">
<rlink href="https://github.com/usnistgov/oscal-content/raw/main/nist.gov/SP800-53/rev5/xml/NIST_SP-800-53_rev5_catalog.xml" media-type="application/oscal+xml"/>
</resource>
</back-matter>
</mapping-collection>
57 changes: 0 additions & 57 deletions src/metaschema/examples/computer-build_metaschema.xml
View file

This file was deleted.

17 changes: 17 additions & 0 deletions src/metaschema/oscal_catalog_metaschema.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
</remarks>
<import href="oscal_control-common_metaschema.xml"/>
<import href="oscal_metadata_metaschema.xml"/>
<import href="oscal_mapping-common_metaschema.xml"/>
<define-assembly name="catalog">
<formal-name>Catalog</formal-name>
<description>A collection of controls.</description>
Expand Down Expand Up @@ -173,6 +174,22 @@
<assembly ref="part" max-occurs="unbounded">
<group-as name="parts" in-json="ARRAY"/>
</assembly>
<define-assembly name="mapping">
<formal-name>Mapping</formal-name>
<description>A mapping between the containing control and another resource.</description>
<define-flag name="uuid" as-type="uuid" required="yes">
<formal-name>Mapping Identifier</formal-name>
<description>The unique identifier for the mapping.</description>
</define-flag>
<model>
<assembly ref="mapping-resource-reference" min-occurs="1">
<use-name>target-resource</use-name>
</assembly>
<assembly ref="map" min-occurs="1" max-occurs="unbounded">
<group-as name="maps" in-json="ARRAY"/>
</assembly>
</model>
</define-assembly>
<assembly ref="control" max-occurs="unbounded">
<group-as name="controls" in-json="ARRAY"/>
</assembly>
Expand Down
1 change: 1 addition & 0 deletions src/metaschema/oscal_complete_metaschema.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
<p>This format represents a combination of all of the OSCAL models.</p>
</remarks>
<import href="oscal_catalog_metaschema.xml"/>
<import href="oscal_mapping_metaschema.xml"/>
<import href="oscal_profile_metaschema.xml"/>
<import href="oscal_component_metaschema.xml"/>
<import href="oscal_ssp_metaschema.xml"/>
Expand Down
123 changes: 123 additions & 0 deletions src/metaschema/oscal_mapping-common_metaschema.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="../../build/metaschema/toolchains/xslt-M4/validate/metaschema-check.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<METASCHEMA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/metaschema/1.0 ../../build/metaschema/toolchains/xslt-M4/validate/metaschema.xsd" abstract="yes">
<schema-name>OSCAL Mapping Model -- Common Models</schema-name>
<schema-version>1.0.0</schema-version>
<short-name>oscal-mapping-common</short-name>
<namespace>http://csrc.nist.gov/ns/oscal/1.0</namespace>
<json-base-uri>http://csrc.nist.gov/ns/oscal</json-base-uri>

<import href="oscal_metadata_metaschema.xml"/>

<define-assembly name="map">
<formal-name>Mapping Entry</formal-name>
<description>A relationship-based mapping between a source and target set consisting of members (i.e., controls, control statements) from the respective source and target.</description>
<define-flag name="uuid" as-type="uuid" required="yes">
<formal-name>Mapping Entry Identifier</formal-name>
<description>The unique identifier for the mapping entry.</description>
</define-flag>
<model>
<assembly ref="property" max-occurs="unbounded">
<group-as name="props" in-json="ARRAY"/>
</assembly>
<assembly ref="link" max-occurs="unbounded">
<group-as name="links" in-json="ARRAY"/>
</assembly>
<define-field name="relationship" as-type="token" min-occurs="1">
<formal-name>Mapping Entry Relationship</formal-name>
<description>The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets.</description>
<define-flag name="ns" as-type="uri">
<formal-name>Relationship Value Namespace</formal-name>
<description>A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.</description>
<remarks>
<p>An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.</p>
<p>When a <code>ns</code> is not provided, its value should be assumed to be <code>http://csrc.nist.gov/ns/oscal</code> and the name should be a name defined by the associated OSCAL model.</p>
</remarks>
</define-flag>
<constraint>
<allowed-values target=".[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]">
<enum value="equivalent-to">The effective requirements of the source is equivalent in semantic meaning to the effective requirements of the target. The words may differ, but both mapped sets convey similar information with the same effective meaning. This relationship may be reversed, since `A equivalent-to B` also means that `B equivalent-to A`.</enum>
<enum value="equal-to">The actual requirements of the source are the same as the actual requirements target. Differences in capitalization, spelling, and grammar can be ignored, if these differences do not change the meaning. This relationship may be reversed, since `A equal-to B` also means that `B equal-to A`.</enum>
<enum value="subset-of">The effective requirements of the source is a semantic subset of the effective requirements of the target. This relationship may be reversed as a `superset-of`, since `A subset-of B` also means that `B superset-of A`.</enum>
<enum value="superset-of">The effective requirements of the source is a semantic superset of the effective requirements of the target. This relationship may be reversed as a `subset-of`, since `A superset-of B` also means that `B subset-of A`.</enum>
<enum value="intersects-with">The effective requirements of the source and target have some semantic equivalence, but not all effective requirements from each are contained within the other. This relationship may be reversed, since `A intersects-with B` also means that `B intersects-with A`. A lower granularity mapping, such as a statement level mapping using 'equivalent-to', 'subset-of', and/or 'superset-of', may provide a more functional mapping that allows for more inference than using this relationship type.</enum>
</allowed-values>
</constraint>
<remarks>
<p>When establishing relationships, mapping SHOULD be done at the control statement level where possible. This approach allows for more use of 'equivalent-to', which represents a stronger relationship than the other relationship types.</p>
</remarks>
</define-field>
<assembly ref="mapping-item" min-occurs="1" max-occurs="unbounded">
<use-name>source</use-name>
<group-as name="sources" in-json="ARRAY"/>
</assembly>
<assembly ref="mapping-item" min-occurs="1" max-occurs="unbounded">
<use-name>target</use-name>
<group-as name="targets" in-json="ARRAY"/>
</assembly>
<field ref="remarks" in-xml="WITH_WRAPPER" min-occurs="0" max-occurs="1"/>
</model>
</define-assembly>
<define-assembly name="mapping-item">
<formal-name>Mapping Entry Item (source or target)</formal-name>
<description>Identifies a specific edge within a source or target that is the subject of a mapping.</description>
<define-flag name="type" as-type="token" required="yes">
<formal-name>Subject Type</formal-name>
<description>The semantic type of the subject.</description>
<constraint>
<allowed-values>
<enum value="control">A control as <a href="https://pages.nist.gov/OSCAL/concepts/terminology/#control">defined</a> by OSCAL.</enum>
<enum value="statement">A textual element of a control that defines part of the control's requirements.</enum>
</allowed-values>
</constraint>
</define-flag>
<define-flag name="id-ref" as-type="string" required="yes">
<formal-name>Subject Type</formal-name>
<description>The semantic type of the subject.</description>
</define-flag>
<model>
<assembly ref="property" max-occurs="unbounded">
<group-as name="props" in-json="ARRAY"/>
</assembly>
<assembly ref="link" max-occurs="unbounded">
<group-as name="links" in-json="ARRAY"/>
</assembly>
<field ref="remarks" in-xml="WITH_WRAPPER" min-occurs="0" max-occurs="1"/>
</model>
</define-assembly>

<define-assembly name="mapping-resource-reference">
<formal-name>Mapped Resource Reference</formal-name>
<description>A reference to a back-matter resource that is either the source or target of a mapping.</description>
<define-flag name="type" as-type="token" required="yes">
<formal-name>Resource Type</formal-name>
<description>The semantic type of the resource.</description>
<constraint>
<allowed-values>
<enum value="catalog">The mapped resource is a control catalog.</enum>
</allowed-values>
</constraint>
</define-flag>
<define-flag name="href" as-type="uri-reference" required="yes">
<formal-name>Catalog or Profile Reference</formal-name>
<description>A resolvable URL reference to the base catalog or profile that this profile is tailoring.</description>
<remarks>
<p>The value of the <code>href</code> can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a <code>back-matter</code>
<code>resource</code> in the same document.</p>
<!-- TODO: Add a link to "within the scope of the containing OSCAL document" to point to documentation of identification scopes" -->
<p>If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified <code>resource</code> in the document's <code>back-matter</code> or another object that is within the scope of the containing OSCAL document.</p>
<p>If an internet resource is used, the <code>href</code> value will be an absolute or relative URL pointing to the location of the referenced resource. A relative URL will be resolved relative to the location of the document containing the link.</p>
</remarks>
</define-flag>
<model>
<assembly ref="property" max-occurs="unbounded">
<group-as name="props" in-json="ARRAY"/>
</assembly>
<assembly ref="link" max-occurs="unbounded">
<group-as name="links" in-json="ARRAY"/>
</assembly>
<field ref="remarks" in-xml="WITH_WRAPPER" min-occurs="0" max-occurs="1"/>
</model>
</define-assembly>
</METASCHEMA>
Loading

0 comments on commit d145dfe

Please sign in to comment.