From 333ed6abea769fa49916525ab0d88b199e0fe523 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Mon, 31 Jan 2022 15:18:46 -0500 Subject: [PATCH 01/15] Updates to tests including whitespace scrub test --- .../example-set.xspec | 41 +++++++++++++++++++ .../oscal-profile-test-helper.xsl | 3 +- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec b/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec index e17d79042b..9a64e55d10 100644 --- a/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec +++ b/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec @@ -27,4 +27,45 @@ + + + + + Control A1 + + + a1.a value + + + +

A1 aaaaa aaaaaaaaaa

+

Parameter A.a is set: + +

+

Parameter a1.a is set: + +

+ + + + + + + + + Control A1 + + + a1.a value + + + +

A1 aaaaa aaaaaaaaaa

+

Parameter A.a is set: +

+

Parameter a1.a is set:

+ + + + diff --git a/src/utils/util/resolver-pipeline/oscal-profile-test-helper.xsl b/src/utils/util/resolver-pipeline/oscal-profile-test-helper.xsl index a423068823..612b5507db 100644 --- a/src/utils/util/resolver-pipeline/oscal-profile-test-helper.xsl +++ b/src/utils/util/resolver-pipeline/oscal-profile-test-helper.xsl @@ -3,7 +3,8 @@ xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution" xmlns:xs="http://www.w3.org/2001/XMLSchema" exclude-result-prefixes="#all" - xpath-default-namespace="http://csrc.nist.gov/ns/oscal/1.0"> + xpath-default-namespace="http://csrc.nist.gov/ns/oscal/1.0" + default-mode="scrubbing"> diff --git a/src/specifications/profile-resolution/specml-html-preview.xsl b/src/specifications/profile-resolution/lib/specml-html-preview.xsl similarity index 64% rename from src/specifications/profile-resolution/specml-html-preview.xsl rename to src/specifications/profile-resolution/lib/specml-html-preview.xsl index c98065bec8..b7bab0f301 100644 --- a/src/specifications/profile-resolution/specml-html-preview.xsl +++ b/src/specifications/profile-resolution/lib/specml-html-preview.xsl @@ -24,10 +24,16 @@ - +
@@ -43,14 +49,25 @@ body {{ line-height: 140%; font-family: "Cambria", serif }} * {{ box-sizing: border-box }} -aside.toc {{ position: fixed; overflow-y: scroll; max-width: 36%; top: 1em; bottom: 0px; font-family: { $display-font } }} +aside.navpanel {{ position: fixed; overflow-y: scroll; max-width: 36%; top: 1em; bottom: 0px; font-family: { $display-font } }} + +aside.navpanel div.rqrmts * {{ margin: 0em }} + +.req {{ background-color: pink; padding: 0.2em; font-size: 110%; margin-top: 0.2em !important }} +div.rqrmts .req {{ font-size: 90%; border-top: thin solid red; border-bottom: thin solid red }} +.req.should {{ background-color: peachpuff; border-top: thin solid orange; border-bottom: thin solid orange }} +.req.may {{ background-color: cornsilk; border-top: thin solid gold; border-bottom: thin solid gold }} +.req.recommended {{ background-color: mintcream; border-top: thin solid blue; border-bottom: thin solid blue }} + +span.reqlabel {{ background-color: mintcream; color: forestgreen; margin-right: 0.4em; padding: 0.1em; border: thin solid green }} + .toc ul {{ list-style: none; padding-left: 1em }} main {{ margin-left: 40%; max-width: 48em }} details {{ margin-top: 1.5em }} -details details {{ margin-left: 2em; border-left: thin solid black; padding-left: 1em }} +details details {{ border-left: thin solid black; padding-left: 1em }} summary > * {{ display: inline }} @@ -69,6 +86,8 @@ a {{ color: inherit }} a.linked {{ color: inherit }} .toc a {{ text-decoration: none }} +span.req {{ color: royalblue }} +span.req:hover {{ background-color: beige }} .example {{ padding: 0.5em; border: thin dotted black; margin-top: 1em }} .example > *:first-child {{ margin-top: 0em }} @@ -85,7 +104,52 @@ a.linked {{ color: inherit }} + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + + + + + + +

+ + + + + + +

+ +
    @@ -111,10 +175,14 @@ a.linked {{ color: inherit }} - + + + + + @@ -151,7 +219,6 @@ a.linked {{ color: inherit }}

    Source (profile):

     -

    Intermediate (catalog):

     diff --git a/src/specifications/profile-resolution/specml-html-static.xsl b/src/specifications/profile-resolution/lib/specml-html-static.xsl similarity index 100% rename from src/specifications/profile-resolution/specml-html-static.xsl rename to src/specifications/profile-resolution/lib/specml-html-static.xsl diff --git a/src/specifications/profile-resolution/specml-html-xslt1.xsl b/src/specifications/profile-resolution/lib/specml-html-xslt1.xsl similarity index 90% rename from src/specifications/profile-resolution/specml-html-xslt1.xsl rename to src/specifications/profile-resolution/lib/specml-html-xslt1.xsl index 3228178bdf..249f3160c6 100644 --- a/src/specifications/profile-resolution/specml-html-xslt1.xsl +++ b/src/specifications/profile-resolution/lib/specml-html-xslt1.xsl @@ -100,7 +100,13 @@ - + + + + + + +
      @@ -143,7 +149,21 @@ - + + + + + + + + + + + + + + + diff --git a/src/specifications/profile-resolution/specml-html-xslt3.xsl b/src/specifications/profile-resolution/lib/specml-html-xslt3.xsl similarity index 100% rename from src/specifications/profile-resolution/specml-html-xslt3.xsl rename to src/specifications/profile-resolution/lib/specml-html-xslt3.xsl diff --git a/src/specifications/profile-resolution/specml.css b/src/specifications/profile-resolution/lib/specml.css similarity index 100% rename from src/specifications/profile-resolution/specml.css rename to src/specifications/profile-resolution/lib/specml.css diff --git a/src/specifications/profile-resolution/specml.rnc b/src/specifications/profile-resolution/lib/specml.rnc similarity index 100% rename from src/specifications/profile-resolution/specml.rnc rename to src/specifications/profile-resolution/lib/specml.rnc diff --git a/src/specifications/profile-resolution/oscal-specs_share.xpr b/src/specifications/profile-resolution/oscal-specs_share.xpr index 80143dacc0..9b2fd74b7e 100644 --- a/src/specifications/profile-resolution/oscal-specs_share.xpr +++ b/src/specifications/profile-resolution/oscal-specs_share.xpr @@ -5,9 +5,136 @@ + + custom.refactoring.dir + ${pd}/lib + + + editor.format.preserve.spaces.elements.v11 + + xsl:text + xsl:comment + xsl:processing-instruction + literallayout + programlisting + screen + synopsis + pre + xd:pre + tagging + + + + key.editor.format.xml.option.pane + true + + + key.xml.refactoring.option.pane + true + scenario.associations + + + lib/build-xspec.xsl + + + + Produce XSpec for //req/@eg (file list) from SpecML + + + + + XSL + + + + + 2 + + + + + + requirements-working-set.xspec + + + + Produce XSpec for //req/@eg (file list) from SpecML + + + + + XSL + + + + + 2 + + + + + + profile-resolution-specml-working.xml + + + + Produce XSpec for //req/@eg (file list) from SpecML + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-include-all-flat.xml + + + + RESOLVE the current profile and write result to ./output-expected + + + + + XSL + + + + + 2 + + + + + + lib/specml-html-preview.xsl + + + + Produce HTML preview for (this) SpecML XML - refresh + + + + + XSL + + + + + 2 + + + profile-resolution-specml.xml @@ -28,6 +155,66 @@ + + + profile-resolution-specml-demo.xml + + + + Produce HTML preview for (this) SpecML XML - refresh and open + + + + + XSL + + + + + 2 + + + + + + profile-resolution-specml-working2.xml + + + + Produce Profile Resolution Spec - preview (HTML) - refresh + + + + + XSL + + + + + 2 + + + + + + profile-resolution-specml-tidier2.xml + + + + Test (this) XSLT on Profile Resolution Spec XML + + + + + XSL + + + + + 2 + + + specml-html-hugo-uswds.xsl @@ -98,7 +285,7 @@ - Produce Profile Resolution Spec - preview (HTML) - refresh + Produce HTML preview for (this) SpecML XML - refresh @@ -116,10 +303,10 @@ - ${pdu}/specml-html-preview.xsl + ${pdu}/lib/specml-html-preview.xsl - ${pdu}/profile-resolution-specml.xml + ${currentFileURL} false @@ -137,7 +324,7 @@ false - ${pd}/profile-resolution-preview.html + ${pd}/${cfn}-preview.html false @@ -181,7 +368,7 @@ - Produce Profile Resolution Spec - preview (HTML) - refresh and open + Produce HTML preview for (this) SpecML XML - refresh and open @@ -199,10 +386,10 @@ - ${pdu}/specml-html-preview.xsl + ${pdu}/lib/specml-html-preview.xsl - ${pdu}/profile-resolution-specml.xml + ${currentFileURL} false @@ -220,7 +407,7 @@ true - ${pd}/profile-resolution-preview.html + ${pd}/${cfn}-preview.html false @@ -264,7 +451,7 @@ - Produce Profile Resolution Spec - publish (HTML for site) + Produce Profile Resolution Spec - preview (HTML) - refresh @@ -282,7 +469,7 @@ - ${pdu}/specml-html-hugo-uswds.xsl + ${pdu}/lib/specml-html-preview.xsl ${pdu}/profile-resolution-specml.xml @@ -303,7 +490,7 @@ false - C:\Users\wap1\Documents\usnistgov\OSCAL\docs\content\documentation\specification\processing\profile-resolution.html + ${pd}/profile-resolution-preview.html false @@ -347,7 +534,7 @@ - Test (this) XSLT on Profile Resolution Spec XML + Produce Profile Resolution Spec - preview (HTML) - refresh and open @@ -365,10 +552,10 @@ - ${currentFileURL} + ${pdu}/lib/specml-html-preview.xsl - ${pdu}/profile-resolution-working-specml.xml + ${pdu}/profile-resolution-specml.xml false @@ -383,10 +570,10 @@ true - false + true - + ${pd}/profile-resolution-preview.html false @@ -401,8 +588,91 @@ false + false + + + false + + + false + + + true + + + + + + + + + Saxon-PE + + + + + + + + + + + Produce Profile Resolution Spec - publish (HTML for site) + + + + + + + + + pdf + + + Apache FOP + + + + + + ${pdu}/lib/specml-html-hugo-uswds.xsl + + + ${pdu}/profile-resolution-specml.xml + + + false + + + false + + + XSL + + true + + false + + + C:/Users/wap1/Documents/usnistgov/OSCAL/docs/content/documentation/specification/processing/profile-resolution.html + + + false + + + + + + false + + + false + + + false + false @@ -425,7 +695,569 @@ - + + + + + + Produce XSpec for //req/@eg (file list) from SpecML + + + + + + + + + pdf + + + Apache FOP + + + + + + ${pdu}/lib/build-xspec.xsl + + + ${currentFileURL} + + + false + + + false + + + XSL + + + true + + + false + + + ${cfn}-${timeStamp}.xspec + + + false + + + + + + true + + + false + + + false + + + false + + + false + + + true + + + + + + + + + Saxon-PE + + + + + + + + + + + RESOLVE the current profile and write result to ./output-expected + + + + + + + + + pdf + + + Apache FOP + + + + + + ${pdu}/../../utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl + + + ${currentFileURL} + + + false + + + false + + + XSL + + + true + + + false + + + output-actual/${cfn}_RESOLVED.xml + + + false + + + + + + true + + + false + + + false + + + false + + + false + + + true + + + + + + + + + Saxon-PE + + + + + + + + + + + Test (this) XSLT on Profile Resolution Spec XML + + + + + + + + + pdf + + + Apache FOP + + + + + + ${currentFileURL} + + + ${pdu}/lib/profile-resolution-working-specml.xml + + + false + + + false + + + XSL + + + true + + + false + + + + + + false + + + + + + false + + + false + + + true + + + false + + + false + + + true + + + + + + + + + Saxon-PE + + + + + + + + + validation.scenario.associations + + + + requirement-tests/output-actual/ + + + + OSCAL Catalog schema (current local copy) + + + + + Validation_scenario + + + + + 2 + + + + + + requirements-working-set.xspec + + + + OSCAL profile resolution test check + + + + + Validation_scenario + + + + + 2 + + + + + + requirement-tests/req-include-all-flat.xml + + + + OSCAL Profile schema (current local copy) + OSCAL profile resolution test check + + + + + Validation_scenario + Validation_scenario + + + + + 2 + 2 + + + + + + requirement-tests/req-include-all-asis.xml + + + + OSCAL Profile schema (current local copy) + OSCAL profile resolution test check + + + + + Validation_scenario + Validation_scenario + + + + + 2 + 2 + + + + + + requirement-tests/req-include-all_01.xml + + + + OSCAL profile resolution test check + + + + + Validation_scenario + + + + + 2 + + + + + + requirement-tests.xspec + + + + OSCAL profile resolution test check + + + + + Validation_scenario + + + + + 2 + + + + + + + validation.scenarios + + + + + + + + + text/xml + + + + + ${currentFileURL} + + + + + <Default engine> + + + true + + + + + true + + + + + + + + + + + + + + 2 + + + file:/C:/Users/wap1/Documents/usnistgov/OSCAL/xml/schema/oscal_catalog_schema.xsd + + + + + + + + + + + Validation_scenario + + + OSCAL Catalog schema (current local copy) + + + + + + + + + + text/xml + + + + + ${currentFileURL} + + + + + <Default engine> + + + true + + + + + true + + + + + + + + + + + + + + 2 + + + file:/C:/Users/wap1/Documents/usnistgov/OSCAL/xml/schema/oscal_profile_schema.xsd + + + + + + + + + + + Validation_scenario + + + OSCAL Profile schema (current local copy) + + + + + + + + + + text/xml + + + + + ${currentFileURL} + + + + + <Default engine> + + + true + + + + + true + + + + + + + + + + + + + + 7 + + + ${pdu}/lib/xspec-test-dev.sch + + + + + + + + + + + Validation_scenario + + + OSCAL profile resolution test check + + + diff --git a/src/specifications/profile-resolution/readme.md b/src/specifications/profile-resolution/readme.md index bc019f4039..427daea19c 100644 --- a/src/specifications/profile-resolution/readme.md +++ b/src/specifications/profile-resolution/readme.md @@ -6,32 +6,23 @@ Please post Issues in Github or questions to the OSCAL mailing list, or ask abou The specifications are being edited in an ad-hoc XML back end format, a lightweight extension to HTML tagging. If you wish to edit the files directly, we have stylesheets for presentation and HTML conversion along with Schematron for validation (runtime or at check points); please contact us. +### Capabilities -TODO: - -### Requirements index - -Annotate a copy/mirror of profile metaschema (composed) - link to requirements - link to test(s) - -current XSpecs - for each test - if green - confirm correctness of test - if pink - -XSLT to poll unit tests - drawing profile model element tree with links to tests showing usages - - - -new XSpecs - - -for every test document, list -- objects of interest (assembles fields flags or flag/values) - xpath -- for each of these - - requirement(s) being tested - - index into spec (section title/phrase) +- XML authoring of specifications +- HTML previews with ToC / requirements index +- HTML rendering for Hugo / site load +- Back end validation support for specialized semantics +- Tagging of requirements integrates with unit tests +- Cosmetic reformatter rewrites your document with clean tagging and whitespace + +- Unit test set (XSpec) is annotated with keys (links) back to spec document +- Two-way indexing enables assessment of coverage by unit tests (per marked up requirements) + +- The tests themselves can be illustrated (in/out) using another rendering XSLT + +### oXygen project for editing specs + +Included in this folder is an oXygen XML Editor project file with settings for many of these operations. + +### Next steps / ongoing diff --git a/src/specifications/profile-resolution/spec-checkup.sch b/src/specifications/profile-resolution/spec-checkup.sch deleted file mode 100644 index bf2c4034a6..0000000000 --- a/src/specifications/profile-resolution/spec-checkup.sch +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - section is too deep - - - From 8be991bb6f70b61dbccad5ec4fef69071d04226b Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Mon, 7 Mar 2022 12:10:31 -0500 Subject: [PATCH 04/15] Profile resolution testing infrastructure, plus some tests --- .../profile-resolution/example-set.xspec | 127 + .../profile-resolution/lib/build-xspec.xsl | 78 + .../lib/oscal-profile-test-helper.xsl | 90 + .../lib/specml-tidy-config.xml | 9 + .../profile-resolution/lib/specml-tidy.xsl | 106 + .../profile-resolution/lib/xspec-oxygen.css | 68 + .../profile-resolution/lib/xspec-test-dev.sch | 91 + .../assess-test-coverage.xsl | 110 + .../profile-element-usage-survey.html | 229 ++ .../scrub-testing.xspec | 43 + .../profile-resolution-preview.html | 2348 +++++++++++++++++ .../profile-resolution-specml-64f22b.xml | 1524 +++++++++++ ...ion-specml-working-20220215163241705.xspec | 35 + ...ile-resolution-specml-working-preview.html | 2045 ++++++++++++++ .../profile-resolution-specml-working.xml | 1063 ++++++++ .../requirement-tests.xspec | 22 + .../catalogs/abc-full_catalog.xml | 141 + .../catalogs/abc-mixed-up_catalog.xml | 105 + .../catalogs/abc-simple_catalog.xml | 106 + .../catalogs/xyz-tiny_catalog.xml | 55 + .../req-include-all-asis_RESOLVED.xml | 103 + .../req-include-all-flat_RESOLVED.xml | 94 + .../req-include-all-asis_RESOLVED.xml | 103 + .../req-include-all-flat_RESOLVED.xml | 94 + .../req-include-all-asis.xml | 17 + .../req-include-all-flat.xml | 14 + .../requirements-working-set.xspec | 810 ++++++ .../specml-html-preview-preview.html | 59 + 28 files changed, 9689 insertions(+) create mode 100644 src/specifications/profile-resolution/example-set.xspec create mode 100644 src/specifications/profile-resolution/lib/build-xspec.xsl create mode 100644 src/specifications/profile-resolution/lib/oscal-profile-test-helper.xsl create mode 100644 src/specifications/profile-resolution/lib/specml-tidy-config.xml create mode 100644 src/specifications/profile-resolution/lib/specml-tidy.xsl create mode 100644 src/specifications/profile-resolution/lib/xspec-oxygen.css create mode 100644 src/specifications/profile-resolution/lib/xspec-test-dev.sch create mode 100644 src/specifications/profile-resolution/profile-resolution-examples/assess-test-coverage.xsl create mode 100644 src/specifications/profile-resolution/profile-resolution-examples/profile-element-usage-survey.html create mode 100644 src/specifications/profile-resolution/profile-resolution-examples/scrub-testing.xspec create mode 100644 src/specifications/profile-resolution/profile-resolution-preview.html create mode 100644 src/specifications/profile-resolution/profile-resolution-specml-64f22b.xml create mode 100644 src/specifications/profile-resolution/profile-resolution-specml-working-20220215163241705.xspec create mode 100644 src/specifications/profile-resolution/profile-resolution-specml-working-preview.html create mode 100644 src/specifications/profile-resolution/profile-resolution-specml-working.xml create mode 100644 src/specifications/profile-resolution/requirement-tests.xspec create mode 100644 src/specifications/profile-resolution/requirement-tests/catalogs/abc-full_catalog.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/catalogs/abc-mixed-up_catalog.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/catalogs/abc-simple_catalog.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/catalogs/xyz-tiny_catalog.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-actual/req-include-all-asis_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-actual/req-include-all-flat_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-expected/req-include-all-asis_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-expected/req-include-all-flat_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/req-include-all-asis.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/req-include-all-flat.xml create mode 100644 src/specifications/profile-resolution/requirements-working-set.xspec create mode 100644 src/specifications/profile-resolution/specml-html-preview-preview.html diff --git a/src/specifications/profile-resolution/example-set.xspec b/src/specifications/profile-resolution/example-set.xspec new file mode 100644 index 0000000000..4442e4ee94 --- /dev/null +++ b/src/specifications/profile-resolution/example-set.xspec @@ -0,0 +1,127 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/specifications/profile-resolution/lib/build-xspec.xsl b/src/specifications/profile-resolution/lib/build-xspec.xsl new file mode 100644 index 0000000000..185ab69491 --- /dev/null +++ b/src/specifications/profile-resolution/lib/build-xspec.xsl @@ -0,0 +1,78 @@ + + + + + + + + autogenerated { current-dateTime() } following model in example-set.xspec + href="lib/xspec-test-dev.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron" + type="text/css" href="lib/xspec-oxygen.css" + { replace(document-uri(/),'.*/','') } + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + requirement-tests/{$filename} + + + { $req-id} + + + + + + + + [Section {@rid}] + + diff --git a/src/specifications/profile-resolution/lib/oscal-profile-test-helper.xsl b/src/specifications/profile-resolution/lib/oscal-profile-test-helper.xsl new file mode 100644 index 0000000000..44eb91412b --- /dev/null +++ b/src/specifications/profile-resolution/lib/oscal-profile-test-helper.xsl @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + ... + + + + ... + + + + ... + + + + + + + + + + + + diff --git a/src/specifications/profile-resolution/lib/specml-tidy-config.xml b/src/specifications/profile-resolution/lib/specml-tidy-config.xml new file mode 100644 index 0000000000..762528d137 --- /dev/null +++ b/src/specifications/profile-resolution/lib/specml-tidy-config.xml @@ -0,0 +1,9 @@ + + + Any assigned ID is normalized. IDs are assigned to some elements that do not have them. + + + +
      +

      Importing catalogs/abc-mixed-up_catalog.xml

      +

      In catalog catalogs/abc-mixed-up_catalog.xml

      +
      +
      + +
      +

      catalog

      +
      +       +
      + +
      +

      group

      +
      +
      +

      title Group B of C

      +
      +
      +
      +       +
      + +
      +

      control b2

      +
      +
      +

      title Control B2

      +
      +
      +
      +       +
      +
      +

      part statementb2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b1

      +
      +
      +

      title Control B1

      +
      +
      +
      +       +
      +
      +

      part statementb1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b3

      +
      +
      +

      title Control B3

      +
      +
      +
      +       +
      +
      +

      part statementb3-stmt ▮

      +
      +
      +
      +
      +
      + +
      +

      group

      +
      +
      +

      title Group A of C

      +
      +
      +
      +       +
      + +
      +

      control a3

      +
      +
      +

      title Control A3

      +
      +
      +
      +       +
      +
      +

      param a3_prm1

      +
      +
      +

      label A3 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa3-stmt ▮

      +
      +
      +
      +
      + +
      +

      control a2

      +
      +
      +

      title Control A2

      +
      +
      +
      +       +
      +
      +

      part statementa2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control a1

      +
      +
      +

      title Control A1

      +
      +
      +
      +       +
      +
      +

      param a1_prm1

      +
      +
      +

      label A1 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa1-stmt ▮

      +
      +
      +
      +
      +
      + +
      +

      group

      +
      +
      +

      title Group C of C

      +
      +
      +
      +       +
      + +
      +

      control c3

      +
      +
      +

      title Control C3

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a

      +
      +
      +

      title Control C3-A

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a-1

      +
      +
      +

      title Control C3-A-1

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      +
      +
      +
      + +
      +

      control c1

      +
      +
      +

      title Control C1

      +
      +
      +
      +       +
      +
      +

      part statementc1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control c2

      +
      +
      +

      title Control C2

      +
      +
      +
      +       +
      +
      +

      part statementc2-stmt ▮

      +
      +
      +
      +
      +
      +
      +
      +
      +

      Profile req-include-all-asis.xml

      +
      +
      + +
      +

      profile

      +
      +       +
      + +
      +

      importcatalogs/abc-mixed-up_catalog.xml

      +
      +       +
      +
      +

      include-all

      +
      +
      +
      +
      + +
      +

      merge

      +
      +       +
      +
      +

      as-is true

      +
      +
      +
      +
      +
      +
      +
      +

      Result output-expected/req-include-all-asis_RESOLVED.xml

      +
      +
      + +
      +

      catalog

      +
      +       +
      + +
      +

      group

      +
      +
      +

      title Group B of C

      +
      +
      +
      +       +
      + +
      +

      control b2

      +
      +
      +

      title Control B2

      +
      +
      +
      +       +
      +
      +

      part statementb2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b1

      +
      +
      +

      title Control B1

      +
      +
      +
      +       +
      +
      +

      part statementb1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b3

      +
      +
      +

      title Control B3

      +
      +
      +
      +       +
      +
      +

      part statementb3-stmt ▮

      +
      +
      +
      +
      +
      + +
      +

      group

      +
      +
      +

      title Group A of C

      +
      +
      +
      +       +
      + +
      +

      control a3

      +
      +
      +

      title Control A3

      +
      +
      +
      +       +
      +
      +

      param a3_prm1

      +
      +
      +

      label A3 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa3-stmt ▮

      +
      +
      +
      +
      + +
      +

      control a2

      +
      +
      +

      title Control A2

      +
      +
      +
      +       +
      +
      +

      part statementa2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control a1

      +
      +
      +

      title Control A1

      +
      +
      +
      +       +
      +
      +

      param a1_prm1

      +
      +
      +

      label A1 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa1-stmt ▮

      +
      +
      +
      +
      +
      + +
      +

      group

      +
      +
      +

      title Group C of C

      +
      +
      +
      +       +
      + +
      +

      control c3

      +
      +
      +

      title Control C3

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a

      +
      +
      +

      title Control C3-A

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a-1

      +
      +
      +

      title Control C3-A-1

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      +
      +
      +
      + +
      +

      control c1

      +
      +
      +

      title Control C1

      +
      +
      +
      +       +
      +
      +

      part statementc1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control c2

      +
      +
      +

      title Control C2

      +
      +
      +
      +       +
      +
      +

      part statementc2-stmt ▮

      +
      +
      +
      +
      +
      +
      +
      + + \ No newline at end of file diff --git a/src/specifications/profile-resolution/requirement-tests/illustrations/req-include-by-id-view.html b/src/specifications/profile-resolution/requirement-tests/illustrations/req-include-by-id-view.html new file mode 100644 index 0000000000..5e4084d0fd --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/illustrations/req-include-by-id-view.html @@ -0,0 +1,487 @@ + + + + + + + + +
      +

      Importing catalogs/abc-simple_catalog.xml

      +

      In catalog catalogs/abc-simple_catalog.xml

      +
      +
      + +
      +

      catalog

      +
      +       +
      + +
      +

      group

      +
      +
      +

      title Group A of C

      +
      +
      +
      +       +
      + +
      +

      control a1

      +
      +
      +

      title Control A1

      +
      +
      +
      +       +
      +
      +

      param a1_prm1

      +
      +
      +

      label A1 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control a2

      +
      +
      +

      title Control A2

      +
      +
      +
      +       +
      +
      +

      part statementa2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control a3

      +
      +
      +

      title Control A3

      +
      +
      +
      +       +
      +
      +

      param a3_prm1

      +
      +
      +

      label A3 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa3-stmt ▮

      +
      +
      +
      +
      +
      + +
      +

      group

      +
      +
      +

      title Group B of C

      +
      +
      +
      +       +
      + +
      +

      control b1

      +
      +
      +

      title Control B1

      +
      +
      +
      +       +
      +
      +

      part statementb1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b2

      +
      +
      +

      title Control B2

      +
      +
      +
      +       +
      +
      +

      part statementb2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b3

      +
      +
      +

      title Control B3

      +
      +
      +
      +       +
      +
      +

      part statementb3-stmt ▮

      +
      +
      +
      +
      +
      + +
      +

      group

      +
      +
      +

      title Group C of C

      +
      +
      +
      +       +
      + +
      +

      control c1

      +
      +
      +

      title Control C1

      +
      +
      +
      +       +
      +
      +

      part statementc1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control c2

      +
      +
      +

      title Control C2

      +
      +
      +
      +       +
      +
      +

      part statementc2-stmt ▮

      +
      +
      +
      +
      + +
      +

      control c3

      +
      +
      +

      title Control C3

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a

      +
      +
      +

      title Control C3-A

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a-1

      +
      +
      +

      title Control C3-A-1

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +

      Profile req-include-by-id.xml

      +
      +
      + +
      +

      profile

      +
      +       +
      + +
      +

      importcatalogs/abc-simple_catalog.xml

      +
      +       +
      + +
      +

      include-controls

      +
      +
      +

      with child controls yes

      +
      +
      +
      +       +
      +
      +

      with-id a1

      +
      +
      +
      +
      +

      with-id b1

      +
      +
      +
      +
      +

      with-id c1

      +
      +
      +
      +
      +

      with-id c3

      +
      +
      +
      +
      +
      +
      +
      +
      +

      Result output-expected/req-include-by-id_RESOLVED.xml

      +
      +
      + +
      +

      catalog

      +
      +       +
      + +
      +

      control a1

      +
      +
      +

      title Control A1

      +
      +
      +
      +       +
      +
      +

      param a1_prm1

      +
      +
      +

      label A1 Parameter 1

      +
      +
      +
      +
      +
      +
      +

      part statementa1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control b1

      +
      +
      +

      title Control B1

      +
      +
      +
      +       +
      +
      +

      part statementb1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control c1

      +
      +
      +

      title Control C1

      +
      +
      +
      +       +
      +
      +

      part statementc1-stmt ▮

      +
      +
      +
      +
      + +
      +

      control c3

      +
      +
      +

      title Control C3

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a

      +
      +
      +

      title Control C3-A

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      + +
      +

      control c3.a-1

      +
      +
      +

      title Control C3-A-1

      +
      +
      +
      +       +
      +
      +

      part statementc3-stmt ▮

      +
      +
      +
      +
      +
      +
      +
      +
      + + \ No newline at end of file diff --git a/src/specifications/profile-resolution/requirement-tests/keep-everything-twice.xml b/src/specifications/profile-resolution/requirement-tests/keep-everything-twice.xml new file mode 100644 index 0000000000..7452b3f9f4 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/keep-everything-twice.xml @@ -0,0 +1,17 @@ + + + + + Test Profile + 2022-02-14T17:44:59.245623-05:00 + 1.0 + 1.0.0 + + + + + + + + diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/keep-everything-twice_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/keep-everything-twice_RESOLVED.xml new file mode 100644 index 0000000000..7f603bcf77 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/keep-everything-twice_RESOLVED.xml @@ -0,0 +1,178 @@ + + + + Test Profile + 2022-04-25T16:32:27.0669689-04:00 + 1.0 + 1.0.0 + + + + + Control B2 + + +

      B2 bbb bbbbbbbbbbb bbbbbbbbbbbb.

      +       +       + + Control B1 + + +

      B1 bbbb bbbbbbb.

      +       +       + + Control B3 + + +

      B3 bbbb bbbbbbb bbbb.

      +       +       + + Control A3 + + + + + +

      A3 aaaaa aaaaaaaaaa

      +       +       + + Control A2 + + +

      A2 aaa aaaaaaaaaa aaaaaaaaaaaaa

      +       +       + + Control A1 + + + + + +

      A1 aaaaa aaaaaaaaaa

      +       +       + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       + + Control C3-A-1 + + +

      C3 A-1 ccccc cccccccccccccc.

      +       +       +       +       + + Control C1 + + +

      C1 ccccc ccc ccccccccccccccccc.

      +       +       + + Control C2 + + +

      C2 cccccccc ccccccccccccccccc.

      +       +       + + Control B2 + + +

      B2 bbb bbbbbbbbbbb bbbbbbbbbbbb.

      +       +       + + Control B1 + + +

      B1 bbbb bbbbbbb.

      +       +       + + Control B3 + + +

      B3 bbbb bbbbbbb bbbb.

      +       +       + + Control A3 + + + + + +

      A3 aaaaa aaaaaaaaaa

      +       +       + + Control A2 + + +

      A2 aaa aaaaaaaaaa aaaaaaaaaaaaa

      +       +       + + Control A1 + + + + + +

      A1 aaaaa aaaaaaaaaa

      +       +       + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       + + Control C3-A-1 + + +

      C3 A-1 ccccc cccccccccccccc.

      +       +       +       +       + + Control C1 + + +

      C1 ccccc ccc ccccccccccccccccc.

      +       +       + + Control C2 + + +

      C2 cccccccc ccccccccccccccccc.

      +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-chained-deepA_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-chained-deepA_RESOLVED.xml new file mode 100644 index 0000000000..8c843136a6 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-chained-deepA_RESOLVED.xml @@ -0,0 +1,81 @@ + + + + Test Profile + 2022-04-25T15:47:00.2942155-04:00 + 1.0 + 1.0.0 + + + + Group B of C + + Control B1 + + +

      B1 bbbb bbbbbbb.

      +       +       + + Control B3 + + +

      B3 bbbb bbbbbbb bbbb.

      +       +       +       + + Group A of C + + Control A3 + + + + + +

      A3 aaaaa aaaaaaaaaa

      +       +       + + Control A1 + + + + + +

      A1 aaaaa aaaaaaaaaa

      +       +       +       + + Group C of C + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       + + Control C3-A-1 + + +

      C3 A-1 ccccc cccccccccccccc.

      +       +       +       +       + + Control C1 + + +

      C1 ccccc ccc ccccccccccccccccc.

      +       +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-include-exclude4_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-include-exclude4_RESOLVED.xml new file mode 100644 index 0000000000..31f7820633 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-include-exclude4_RESOLVED.xml @@ -0,0 +1,25 @@ + + + + Test Profile + 2022-04-25T16:18:40.4891642-04:00 + 1.0 + 1.0.0 + + + + Control B2 + + +

      B2 bbb bbbbbbbbbbb bbbbbbbbbbbb.

      +       +       + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-include-exclude5_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-include-exclude5_RESOLVED.xml new file mode 100644 index 0000000000..f192200e80 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-include-exclude5_RESOLVED.xml @@ -0,0 +1,25 @@ + + + + Test Profile + 2022-04-25T16:20:19.1426274-04:00 + 1.0 + 1.0.0 + + + + Control B2 + + +

      B2 bbb bbbbbbbbbbb bbbbbbbbbbbb.

      +       +       + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/req-chained-deepA.xml b/src/specifications/profile-resolution/requirement-tests/req-chained-deepA.xml new file mode 100644 index 0000000000..bd62a69304 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-chained-deepA.xml @@ -0,0 +1,29 @@ + + + + + Test Profile + 2022-04-18T15:14:17.679398100-04:00 + 1.0 + 1.0.0 + + + + + a1 + b1 + c1 + c3 + + + + + a3 + b3 + + + + true + + diff --git a/src/specifications/profile-resolution/requirement-tests/req-include-exclude4.xml b/src/specifications/profile-resolution/requirement-tests/req-include-exclude4.xml new file mode 100644 index 0000000000..ad8bf1a3f3 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-include-exclude4.xml @@ -0,0 +1,22 @@ + + + + + + Test Profile + 2020-05-30T14:39:47.217-04:00 + 1.0 + 1.0.0 + + + + + + + + + + + + diff --git a/src/specifications/profile-resolution/requirement-tests/req-include-exclude5.xml b/src/specifications/profile-resolution/requirement-tests/req-include-exclude5.xml new file mode 100644 index 0000000000..55609abb5a --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-include-exclude5.xml @@ -0,0 +1,25 @@ + + + + + + Test Profile + 2020-05-30T14:39:47.217-04:00 + 1.0 + 1.0.0 + + + + + + + + + + + + + + + From 8595f3756ea3ee5d236e4bdb15fcc510d366387b Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Tue, 26 Apr 2022 14:07:36 -0400 Subject: [PATCH 09/15] Adjusted gitignore; extended spec with more bindings; illustrator XSLT --- .../profile-resolution/.gitignore | 3 +- .../lib/illustrate-resolution.xsl | 331 ++++++++++++++++++ .../profile-resolution/oscal-specs_share.xpr | 243 ++++++++++++- .../profile-resolution-queryset.xspec | 20 +- .../profile-resolution-specml-102plus.xml | 76 ++-- ...ofile-resolution-specml-requirements.xspec | 103 +++++- 6 files changed, 709 insertions(+), 67 deletions(-) create mode 100644 src/specifications/profile-resolution/lib/illustrate-resolution.xsl diff --git a/src/specifications/profile-resolution/.gitignore b/src/specifications/profile-resolution/.gitignore index b22def9186..c3dbbe3538 100644 --- a/src/specifications/profile-resolution/.gitignore +++ b/src/specifications/profile-resolution/.gitignore @@ -1 +1,2 @@ -!oscal-specs_share.xpr \ No newline at end of file +!oscal-specs_share.xpr +requirement-tests/output-actual/ \ No newline at end of file diff --git a/src/specifications/profile-resolution/lib/illustrate-resolution.xsl b/src/specifications/profile-resolution/lib/illustrate-resolution.xsl new file mode 100644 index 0000000000..9eccf19845 --- /dev/null +++ b/src/specifications/profile-resolution/lib/illustrate-resolution.xsl @@ -0,0 +1,331 @@ + + + + + + + + + + + + + + + + + + +
      + +
      +
      + +
      +
      + +
      + + +       + + + + + + + + + + + + + + + + + + + + + +

      In { name(child::*) } { $href }

      +
      + +
      +       +       + +
      No document found at { $href }
      +       +       + + +       + + + +

      Importing { @href }

      +       + + + + + + + +

      Profile { document-uri(/) => replace('.*/','') }

      +
      + +
      +       + + + { /document-uri(.) } + { $where => replace('.+/','') => replace('\.xml$','_RESOLVED.xml') } + output-expected/{ $resolvedname } +

      Result { $resultpath }

      +
      + +
      +       + + + + + + + + + + + + +
      + +
      + + +
      +       + +
      +       + + +
      +
      + + +
      +
      +       + + + +
      + +
      +       +       + + + +
      + +
      +       +       + + + +
      + +
      +       +       + + + +
      + +
      +       +       + + + +
      + +
      +       +       + + + + +

      { name() }

      +       + + +

      { name() }

      +       + + +

      + import + + + +

      +       + + + + + + + +

      with-id { . }

      +       + + +

      set-parameter { @param-id }

      +       + + +

      alter { @control-id }

      +       + + +

      { local-name() } { @id }

      +       + + +

      { local-name() } { @id }

      +       + + +

      resource { @uuid }

      +       + + +

      insert { @type } { @id-ref }

      +       + + +

      combine { @method }

      +       + + +

      { local-name() } { . }

      +       + + + + ID_{ parent::*/(@id,@param-id)[1] }-{ local-name(.) } +

      { local-name() } { . }

      +       + + +

      rlink { @href }

      +       + + +

      title

      +       + + +

      { local-name(.) } { @name } { @id } { [1 to count(child::*) ] ! '▮' }

      +       + + + +

      { local-name(.) } { @name }{ @value }

      +       + + +

      { local-name() } { (1 to count(child::*)) ! '▮' }

      +       + + +
      +

      with child controls { . }

      +
      +       + + +
      +

      { replace(local-name(.),'\-',' ') } { . }

      +
      +       + + + + + + + +       \ No newline at end of file diff --git a/src/specifications/profile-resolution/oscal-specs_share.xpr b/src/specifications/profile-resolution/oscal-specs_share.xpr index e4be749a18..ea8742b88e 100644 --- a/src/specifications/profile-resolution/oscal-specs_share.xpr +++ b/src/specifications/profile-resolution/oscal-specs_share.xpr @@ -37,7 +37,127 @@ - requirement-tests/req-include-exclude2.xml + requirement-tests/req-include-all-asis.xml + + + + Produce RESOLUTION ILLUSTRATION from this profile + + + + + XSL + + + + + 2 + + + + + + requirement-tests/output-expected/req-include-all-asis_RESOLVED.xml + + + + Produce RESOLUTION ILLUSTRATION from this profile + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-include-by-id.xml + + + + Produce RESOLUTION ILLUSTRATION from this profile + + + + + XSL + + + + + 2 + + + + + + profile-resolution-specml-102plus.xml + + + + Produce XSpec for //req from SpecML + + + + + XSL + + + + + 2 + + + + + + requirement-tests/keep-everything-twice.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-include-exclude5.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-include-exclude4.xml @@ -77,7 +197,7 @@ - requirement-tests/req-include-by-match.xml + requirement-tests/req-chained-deepA.xml @@ -97,11 +217,11 @@ - profile-resolution-specml-102plus.xml + requirement-tests/req-include-exclude2.xml - Produce XSpec for //req from SpecML + RESOLVE the current profile and write result to ./output-actual @@ -117,7 +237,7 @@ - requirement-tests/req-include-by-id.xml + requirement-tests/req-include-by-match.xml @@ -715,6 +835,89 @@ + + + + + + Produce RESOLUTION ILLUSTRATION from this profile + + + + + + + + + pdf + + + Apache FOP + + + + + + ${pdu}/lib/illustrate-resolution.xsl + + + ${currentFileURL} + + + false + + + false + + + XSL + + + true + + + false + + + illustrations/${cfn}-view.html + + + false + + + + + + false + + + false + + + false + + + false + + + false + + + true + + + + + + + + + Saxon-PE + + + + + @@ -1054,7 +1257,7 @@ - requirement-tests/req-include-exclude1.xml + requirement-tests/req-include-exclude4.xml @@ -1094,11 +1297,11 @@ - requirements-working-set.xspec + requirement-tests/req-include-exclude1.xml - OSCAL profile resolution test check + OSCAL Profile schema (current local copy) @@ -1114,7 +1317,7 @@ - requirement-tests/req-include-all-flat.xml + requirement-tests/req-include-all-asis.xml @@ -1137,7 +1340,27 @@ - requirement-tests/req-include-all-asis.xml + requirements-working-set.xspec + + + + OSCAL profile resolution test check + + + + + Validation_scenario + + + + + 2 + + + + + + requirement-tests/req-include-all-flat.xml diff --git a/src/specifications/profile-resolution/profile-resolution-queryset.xspec b/src/specifications/profile-resolution/profile-resolution-queryset.xspec index e84f3ce56a..0a45bc7a3b 100644 --- a/src/specifications/profile-resolution/profile-resolution-queryset.xspec +++ b/src/specifications/profile-resolution/profile-resolution-queryset.xspec @@ -2,7 +2,7 @@ - + - - - + -\-> + - + + --> + + + + + diff --git a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml index d1d7fcf4c7..fd3fdd75db 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml @@ -370,24 +370,25 @@ profile:
      Resolving Imports of Profiles -

      chained profilesIf the resource - acquired is an OSCAL Profile, the tool MUST apply this specification to resolve it, then - continue processing having imported the resulting catalog.

      -

      chained profilesWhen a profile - imports a profile, the subordinate profile SHOULD be resolved first into a catalog using - this specification, before it is imported. This presents the possibility of - circular imports, when a profile is directed to import itself either directly or - indirectly.

      +

      PENDING chained profilesIf the resource acquired is an OSCAL Profile, the tool + MUST apply this specification to resolve it, then continue processing having imported + the resulting catalog.

      +

      PENDING chained profilesPENDING [bug repair] chained profile + merged with controls from its own source catalogWhen a profile imports a profile, + the subordinate profile SHOULD be resolved first into a catalog using this + specification, before it is imported. This presents the possibility of circular + imports, when a profile is directed to import itself either directly or indirectly.

      A circular import occurs when a profile imports an already imported profile, which was called at an earlier place in the import hierarchy. For example, if profile A imports profile B, and profile B imports profile A, the second import is circular. (An import at the top can only be circular if a profile tries to import itself.) If A imports B, B imports C and C imports A, C’s import is circular.

      Note that an import can only be circular within the context of processing a particular profile. In the last example, C’s import would not be circular if invoked in the context of resolving B by itself.

      -

      If a processor encounters a - circular import as described above (self-imports are inherently - circular), the processor MUST cease processing and generate an error.

      +

      PENDING circular import detectionIf a processor encounters a circular + import as described above (self-imports are inherently circular), the processor + MUST cease processing and generate an error.

      A profile identified as home_profile.yamlimports another one identified as circular_profile.yaml:

      @@ -423,9 +424,11 @@ profile:
      Multiple imports -

      Each import directive is processed to produce a set of controls. Note that this occurs even if the same catalog is imported multiple times: each distinct import collects controls into a separate - selection: -

      +

      Each import directive is processed to produce a set of controls. PENDING + chained profilesNote that this occurs even if the same catalog is imported + multiple times: each distinct import collects controls into a separate + selection:

      -

      The control inclusions are combined and collapsed in the next phase of processing, - merge(see ) . -

      +

      PENDING + chained profilesThe control inclusions are combined and collapsed in the next + phase of processing, merge(see ) .

      Multiple imports against the same resource are allowed, and would most commonly occur when the profile author is using to create very specific output. Multiple imports may result in outputs with clashing control IDs if mapping or the merge directive is not set correctly.

      @@ -624,17 +627,22 @@ include-controls: included and excluded, MUST be excluded. This holds irrespective of the specificity of the selection for inclusion or exclusion. For example, if AC-1 is included by id ac-1 and excluded by matching ac*, it is excluded.

      -

      When - exclude-controls has at least one - with-ids or - matching directive, the processor MUST follow the same rules as defined in the relevant sections above for these directives, but exclude instead of include any controls. All optional features (with-child-controls, etc.) also apply to exclusion directives. -

      +

      When exclude-controls + has at least one with-ids or matching directive, the processor + MUST follow the same rules as defined in the relevant sections above for these + directives, but exclude instead of include any controls. All optional features + (with-child-controls, etc.) also apply to exclusion directives.

      Redundant Inclusions and Exclusions -

      A given - import may have any number of inclusion statements and any number of exclusion statements. Their effect is cumulative; any control that is included (or excluded) more than once MUST be considered to be included (or excluded) only once. In other words, a given control being included or excluded more than once has no effect. Exclusion still takes priority over inclusion (see above). -

      +

      A given import may have + any number of inclusion statements and any number of exclusion statements. Their effect + is cumulative; any control that is included (or excluded) more than once MUST be + considered to be included (or excluded) only once. In other words, a given control being + included or excluded more than once has no effect. Exclusion still takes priority over + inclusion (see above).

      Note that this requirement only applies to controls included within the context of a single import. Controls with duplicate IDs included under a different import are not discarded. Also note that this redundancy pruning happens after any relevant mappings have been applied.

      @@ -713,13 +721,11 @@ include-controls:

      In order to apply the combination method, IDs of each control explicitly included are compared against one another. As IDs are unique across entire OSCAL documents, different imports or any groupings have no bearing on collision. Processing requirements for each method are described below.

      No Combine Directive -

      If no - merge directive is given in the profile, or if a - merge is given without a - combine, merge conflicts MUST be treated as if - method: keep was given. For example, a profile with no - merge directive: -

      +

      + If no merge directive + is given in the profile, or if a merge is given without a combine, + merge conflicts MUST be treated as if method: keep was given. For + example, a profile with no merge directive:

      - + @@ -97,7 +97,8 @@ - + - + + + + + - + + + + + + + + + + + + + @@ -183,17 +211,56 @@ + pending="[dev]"> + + + pending="[dev]"> + + - - - + pending="[dev]"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + Date: Tue, 26 Apr 2022 17:22:43 -0400 Subject: [PATCH 10/15] slowly building out more tests --- .../profile-resolution/oscal-specs_share.xpr | 148 ++++++++++++++++-- .../profile-resolution-specml-102plus.xml | 23 +-- ...ofile-resolution-specml-requirements.xspec | 35 +++-- .../profile-resolution/readme.md | 34 +++- .../catalogs/loose-parameters.xml | 59 +++++++ .../req-with-parent-controls-no1_RESOLVED.xml | 24 +++ ...req-with-parent-controls-none_RESOLVED.xml | 25 +++ ...req-with-parent-controls-yes1_RESOLVED.xml | 32 ++++ ...req-with-parent-controls-yes2_RESOLVED.xml | 25 +++ .../req-with-parent-controls-no1.xml | 17 ++ .../req-with-parent-controls-none.xml | 17 ++ .../req-with-parent-controls-yes1.xml | 17 ++ .../req-with-parent-controls-yes2.xml | 17 ++ 13 files changed, 438 insertions(+), 35 deletions(-) create mode 100644 src/specifications/profile-resolution/requirement-tests/catalogs/loose-parameters.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-no1_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-none_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes1_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes2_RESOLVED.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-no1.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-none.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes1.xml create mode 100644 src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes2.xml diff --git a/src/specifications/profile-resolution/oscal-specs_share.xpr b/src/specifications/profile-resolution/oscal-specs_share.xpr index ea8742b88e..f3791d1686 100644 --- a/src/specifications/profile-resolution/oscal-specs_share.xpr +++ b/src/specifications/profile-resolution/oscal-specs_share.xpr @@ -37,11 +37,11 @@ - requirement-tests/req-include-all-asis.xml + requirement-tests/req-with-parent-controls-none.xml - Produce RESOLUTION ILLUSTRATION from this profile + RESOLVE the current profile and write result to ./output-actual @@ -57,7 +57,107 @@ - requirement-tests/output-expected/req-include-all-asis_RESOLVED.xml + requirement-tests/req-with-parent-controls-yes1.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + + + + profile-resolution-specml-102plus.xml + + + + Produce XSpec for //req from SpecML + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-with-parent-controls-yes2.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-with-parent-controls-no1.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-with-parent-controls-no.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + + + + requirement-tests/req-include-all-asis.xml @@ -77,7 +177,7 @@ - requirement-tests/req-include-by-id.xml + requirement-tests/output-expected/req-include-all-asis_RESOLVED.xml @@ -97,11 +197,11 @@ - profile-resolution-specml-102plus.xml + requirement-tests/req-include-by-id.xml - Produce XSpec for //req from SpecML + Produce RESOLUTION ILLUSTRATION from this profile @@ -1257,7 +1357,7 @@ - requirement-tests/req-include-exclude4.xml + requirement-tests/req-with-child-controls-no.xml @@ -1277,27 +1377,30 @@ - requirement-tests/output-actual/ + requirement-tests/req-include-all-asis.xml - OSCAL Catalog schema (current local copy) + OSCAL Profile schema (current local copy) + OSCAL profile resolution test check Validation_scenario + Validation_scenario 2 + 2 - requirement-tests/req-include-exclude1.xml + requirement-tests/req-include-exclude4.xml @@ -1317,23 +1420,40 @@ - requirement-tests/req-include-all-asis.xml + requirement-tests/output-actual/ - OSCAL Profile schema (current local copy) - OSCAL profile resolution test check + OSCAL Catalog schema (current local copy) Validation_scenario - Validation_scenario 2 + + + + + + requirement-tests/req-include-exclude1.xml + + + + OSCAL Profile schema (current local copy) + + + + + Validation_scenario + + + + 2 diff --git a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml index fd3fdd75db..64292ed5d8 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml @@ -605,17 +605,22 @@ include-controls: with-parent-controls applies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they should use an exclude directive that lists all of the undesired parents. As a shortcut for this, with-parent-controls provides the following functionality:

      -

      PENDING PR https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: +

      PR + https://github.com/usnistgov/OSCAL/pull/1207PR + https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: yes directive on an include-controls indicates that all parent controls of the included control MUST also be included.

      -

      PENDING PR https://github.com/usnistgov/OSCAL/pull/1207A - with-parent-controls: no directive on an - include-controls indicates that ONLY the matching control is included, any parent MUST NOT be included. -

      -

      PENDING PR https://github.com/usnistgov/OSCAL/pull/1207If no - with-parent-controls is provided, the processor MUST consider the directive as being equivalent to one having - with-parent-controls:yes. -

      +

      PENDING PR + https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: + no directive on an include-controls indicates that ONLY the + matching control is included, any parent MUST NOT be included.

      +

      PENDING PR + https://github.com/usnistgov/OSCAL/pull/1207If no + with-parent-controls is provided, the processor MUST consider the + directive as being equivalent to one having with-parent-controls:yes.

      diff --git a/src/specifications/profile-resolution/profile-resolution-specml-requirements.xspec b/src/specifications/profile-resolution/profile-resolution-specml-requirements.xspec index 440f2a17b5..f4c64e37e6 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml-requirements.xspec +++ b/src/specifications/profile-resolution/profile-resolution-specml-requirements.xspec @@ -1,5 +1,5 @@ - + @@ -210,20 +210,33 @@ href="requirement-tests/output-expected/req-with-child-controls-none_RESOLVED.xml"/> - - + + + + + + + + + - - + + + + + - + diff --git a/src/specifications/profile-resolution/readme.md b/src/specifications/profile-resolution/readme.md index 427daea19c..295fa1dc29 100644 --- a/src/specifications/profile-resolution/readme.md +++ b/src/specifications/profile-resolution/readme.md @@ -24,5 +24,37 @@ The specifications are being edited in an ad-hoc XML back end format, a lightwei Included in this folder is an oXygen XML Editor project file with settings for many of these operations. -### Next steps / ongoing +### SpecML requirement tagging + +`//req` shows requirements called out as statements in line. + +`//eg` shows bindings to example documents for purposes of testing. + +``` +PENDING chained profiles +``` + +The `@href` is the file instance for the example. The text is a qualifying description. Prefixing the text with `PENDING` signals that a test should be deactivated. In this case, as soon as chained profiles are supported, the description can be changed and the test will be run. + +Presently all `eg` are inside `req` so there is an implicit relation there (no examples are named apart from stated requirements). + +### Unit tests + +Based on markup in the SpecML document, XSpec unit test sheets can be generated framing the unit test held in this subdirectory, to be executed in any (current) XSpec implementation. + +#### Requirements listing + +Broken out by requirement - corresponding line by line to //req in the Spec document source. + +This XSpec is generated by applying the XSLT `lib/build-reqs-xspec.xsl` to the SpecML source document (marked with `req` and `eg` tags). + +#### File listing + +Grouped by file instead of by requirement (since there is a many-to-many relation), this XSpec may be faster and more efficient to execute. + +This XSpec is generated by applying the XSLT `lib/build-examples-xspec.xsl` to the same SpecML source document. + +#### Handmade XSpec + +Additionally handmade XSpec works, such as `profile-resolution-queryset.xspec` diff --git a/src/specifications/profile-resolution/requirement-tests/catalogs/loose-parameters.xml b/src/specifications/profile-resolution/requirement-tests/catalogs/loose-parameters.xml new file mode 100644 index 0000000000..63c182eef8 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/catalogs/loose-parameters.xml @@ -0,0 +1,59 @@ + + + + + Loose Parameters + 2022-04-26T15:43:06.6638546-04:00 + 1.0 + 1.0.0 + + + +

      When referenced from anywhere, this should float through.

       + + + Group of Controls + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       + + Control C3-A-1 + + +

      Making reference to a parameter in another control, like this: .

      +       +       +       +       + + Control C1 + + +

      C1 ccccc ccc ccccccccccccccccc.

      +       +       + + Control C2 + + +

      If Control C2 is missing, should be floating free.

       + + + +

      C2 cccccccc ccccccccccccccccc.

      +       +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-no1_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-no1_RESOLVED.xml new file mode 100644 index 0000000000..5605cb1acb --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-no1_RESOLVED.xml @@ -0,0 +1,24 @@ + + + + Test Profile + 2022-04-26T17:10:21.286142-04:00 + 1.0 + 1.0.0 + + + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       + + Control C3-A-1 + + +

      C3 A-1 ccccc cccccccccccccc.

      +       +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-none_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-none_RESOLVED.xml new file mode 100644 index 0000000000..229f9cabd2 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-none_RESOLVED.xml @@ -0,0 +1,25 @@ + + + + Test Profile + 2022-04-26T17:19:59.7102091-04:00 + 1.0 + 1.0.0 + + + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes1_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes1_RESOLVED.xml new file mode 100644 index 0000000000..90cd98f27f --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes1_RESOLVED.xml @@ -0,0 +1,32 @@ + + + + Test Profile + 2022-04-26T17:11:18.9602994-04:00 + 1.0 + 1.0.0 + + + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       + + Control C3-A-1 + + +

      C3 A-1 ccccc cccccccccccccc.

      +       +       +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes2_RESOLVED.xml b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes2_RESOLVED.xml new file mode 100644 index 0000000000..813f9ac4b9 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/output-expected/req-with-parent-controls-yes2_RESOLVED.xml @@ -0,0 +1,25 @@ + + + + Test Profile + 2022-04-26T17:11:18.9602994-04:00 + 1.0 + 1.0.0 + + + + Control C3 + + +

      C3 ccccc cccccccccccccc.

      +       + + Control C3-A + + +

      C3 A ccccc cccccccccccccc.

      +       +       +       +       diff --git a/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-no1.xml b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-no1.xml new file mode 100644 index 0000000000..6925264970 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-no1.xml @@ -0,0 +1,17 @@ + + + + + + Test Profile + 2022-04-26T16:46:04.8198642-04:00 + 1.0 + 1.0.0 + + + + c3 + + + diff --git a/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-none.xml b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-none.xml new file mode 100644 index 0000000000..e911c6ef89 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-none.xml @@ -0,0 +1,17 @@ + + + + + + Test Profile + 2022-04-26T17:19:08.8113625-04:00 + 1.0 + 1.0.0 + + + + c3.a + + + diff --git a/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes1.xml b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes1.xml new file mode 100644 index 0000000000..eefb32678e --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes1.xml @@ -0,0 +1,17 @@ + + + + + + Test Profile + 2022-04-26T17:09:44.5371952-04:00 + 1.0 + 1.0.0 + + + + c3.a + + + diff --git a/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes2.xml b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes2.xml new file mode 100644 index 0000000000..6c73c9c3a5 --- /dev/null +++ b/src/specifications/profile-resolution/requirement-tests/req-with-parent-controls-yes2.xml @@ -0,0 +1,17 @@ + + + + + + Test Profile + 2022-04-26T17:09:44.5371952-04:00 + 1.0 + 1.0.0 + + + + c3.a + + + From a3bdc85a4097e50483f67b32c95b363db420a5c7 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Fri, 29 Apr 2022 15:42:21 -0400 Subject: [PATCH 11/15] Adding XSLT producing Markdown summary of requirements w/ examples; updates --- .../lib/reqs-md-punchlist.xsl | 72 ++++++++++ .../profile-resolution/oscal-specs_share.xpr | 129 ++++++++++++++---- .../profile-resolution-specml-102plus.xml | 9 +- 3 files changed, 183 insertions(+), 27 deletions(-) create mode 100644 src/specifications/profile-resolution/lib/reqs-md-punchlist.xsl diff --git a/src/specifications/profile-resolution/lib/reqs-md-punchlist.xsl b/src/specifications/profile-resolution/lib/reqs-md-punchlist.xsl new file mode 100644 index 0000000000..327b870b08 --- /dev/null +++ b/src/specifications/profile-resolution/lib/reqs-md-punchlist.xsl @@ -0,0 +1,72 @@ + + + + + + + + + + + + + + + + + + + - [{ if (eg/@href != '') then 'x' else ' ' }] + + + + + [test { @href ! ('`' || . || '`')} + + ] + + + `{.}` + + + + + + `{ @id }` + + + + + + + + + + + + + * + + + + * + + + + + + + + + { replace(.,'\s+',' ') } + + + + [Section {@rid}] + + + diff --git a/src/specifications/profile-resolution/oscal-specs_share.xpr b/src/specifications/profile-resolution/oscal-specs_share.xpr index f3791d1686..7038507e13 100644 --- a/src/specifications/profile-resolution/oscal-specs_share.xpr +++ b/src/specifications/profile-resolution/oscal-specs_share.xpr @@ -37,11 +37,11 @@ - requirement-tests/req-with-parent-controls-none.xml + profile-resolution-specml-102plus.xml - RESOLVE the current profile and write result to ./output-actual + Requirements summary from XSpec (Markdown) @@ -57,7 +57,7 @@ - requirement-tests/req-with-parent-controls-yes1.xml + requirement-tests/req-with-parent-controls-none.xml @@ -75,26 +75,6 @@ - - - profile-resolution-specml-102plus.xml - - - - Produce XSpec for //req from SpecML - - - - - XSL - - - - - 2 - - - requirement-tests/req-with-parent-controls-yes2.xml @@ -515,6 +495,26 @@ + + + requirement-tests/req-with-parent-controls-yes1.xml + + + + RESOLVE the current profile and write result to ./output-actual + + + + + XSL + + + + + 2 + + + @@ -1267,6 +1267,89 @@ + + + + + + Requirements summary from XSpec (Markdown) + + + + + + + + + pdf + + + Apache FOP + + + + + + ${pdu}/lib/reqs-md-punchlist.xsl + + + ${currentFileURL} + + + false + + + false + + + XSL + + + true + + + false + + + + + + false + + + + + + false + + + false + + + true + + + false + + + false + + + true + + + + + + + + + Saxon-PE + + + + + diff --git a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml index 64292ed5d8..3ac7a77564 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml @@ -617,10 +617,11 @@ include-controls: https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: no directive on an include-controls indicates that ONLY the matching control is included, any parent MUST NOT be included.

      -

      PENDING PR - https://github.com/usnistgov/OSCAL/pull/1207If no - with-parent-controls is provided, the processor MUST consider the - directive as being equivalent to one having with-parent-controls:yes.

      +

      Neither setting is + givenIf no with-parent-controls is provided, the processor MUST + consider the directive as being equivalent to one having + with-parent-controls:yes.

      From 9c494802eadaf9a3520867497ac6a85a6fd136b3 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Mon, 9 May 2022 16:32:26 -0400 Subject: [PATCH 12/15] Adding a small utility for converting JSON "prop" fields to "props" fields (emended 1.0.2 syntax) --- .../content-upgrade/json-prop-to-props.xsl | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 src/release/content-upgrade/json-prop-to-props.xsl diff --git a/src/release/content-upgrade/json-prop-to-props.xsl b/src/release/content-upgrade/json-prop-to-props.xsl new file mode 100644 index 0000000000..d986a18aa1 --- /dev/null +++ b/src/release/content-upgrade/json-prop-to-props.xsl @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 51114f5e4ed47fae34131c1cb169e97d3042acb9 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Mon, 9 May 2022 16:35:18 -0400 Subject: [PATCH 13/15] Cleanup --- .../profile-resolution-preview.html | 2348 ----------------- .../profile-resolution-specml-102.xml | 1538 ----------- .../profile-resolution-specml-102plus.xml | 1602 ----------- .../profile-resolution-specml-64f22b.xml | 1524 ----------- ...ile-resolution-specml-working-preview.html | 2045 -------------- .../specml-html-preview-preview.html | 59 - 6 files changed, 9116 deletions(-) delete mode 100644 src/specifications/profile-resolution/profile-resolution-preview.html delete mode 100644 src/specifications/profile-resolution/profile-resolution-specml-102.xml delete mode 100644 src/specifications/profile-resolution/profile-resolution-specml-102plus.xml delete mode 100644 src/specifications/profile-resolution/profile-resolution-specml-64f22b.xml delete mode 100644 src/specifications/profile-resolution/profile-resolution-specml-working-preview.html delete mode 100644 src/specifications/profile-resolution/specml-html-preview-preview.html diff --git a/src/specifications/profile-resolution/profile-resolution-preview.html b/src/specifications/profile-resolution/profile-resolution-preview.html deleted file mode 100644 index ba6b384f72..0000000000 --- a/src/specifications/profile-resolution/profile-resolution-preview.html +++ /dev/null @@ -1,2348 +0,0 @@ - - - - OSCAL Profile Resolution Specification - - - - - -
      -
      - -

      1 Abstract

      -       -

      This specification provides the minimal requirements for processing an OSCAL Profile - to create a new OSCAL Catalog Document. This process of applying a profile to a catalog - to create a new catalog is called - Profile Resolution. Not all OSCAL Profiles will be resolved, nor are expected to be; however, the resolution - requirements in this document are crucial to understanding the intended functionality - of any given OSCAL Profile. - This specification is intended for software developers who intend to develop an OSCAL - Profile Resolver, or for OSCAL Profile authors who want a more in-depth understanding - of profile resolution. -

      -
      -
      - -

      2 Introduction

      -       -
      - -

      2.1 Purpose

      -       -

      This document defines the normative requirements for an OSCAL Profile Resolver. Profile - resolution is core to addressing a fundamental OSCAL requirement: - the representation of baselines separately from the control catalogs on which they - depend). The requirements for resolution must therefore be well-defined and deterministic, - - enabling tool developers and parties exchanging OSCAL Profiles can work from a common - understanding.

      -

      No requirements are placed on implementation-level details, instead, requirements - are laid out as what the output of resolution must look like given a certain input. - By adhering to these requirements OSCAL producers, OSCAL consumers, and any other - members of the OSCAL ecosystem can create and resolve profiles deterministically, - - with repeatable results, regardless of the tool used.

      -
      -
      -
      - -

      3 Reading This Document

      -       -
      - -

      3.1 Terminology

      -       -

      Many core OSCAL concepts are defined on the OSCAL Terminology Page. The most important are repeated in this document, but readers should verify their - understanding of all core OSCAL terms before reading this document.

      -

      Additionally, many terms in the wider domain have overloaded definitions. Unless defined - otherwise by OSCAL or explicitly in this document, terms are to be understood as defined - in the NIST CSRC Glossary.

      -
        -
      • -

        - profile- an OSCAL Profile Document. Defines a set of inclusions, modifications, and transformations - against a - catalog. See - OSCAL Profile Model. -

        -
        • -
      • -

        - catalog- an OSCAL Catalog Document. Contains a well-defined set of - controls. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - control- an individual item in an OSCAL Catalog. See - NIST Special Publication 800-53r5for a more in-depth definition. -

        -
        • -
      • -

        - profile resolution- The process of consuming one or more OSCAL Profiles and the OSCAL Catalogs that - they reference to produce a new tailored - catalog. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - source- refers to the profile document that is input into the profile resolution processor. - This is the profile being resolved. In this document, when referring to objects from - the - sourcedocument, the following style is used: - source-object. -

        -
        • -
      • -

        - target- the intended output of the transformation, a catalog document. In this document, - when referring to objects of a - targetdocument, the following style is used: - target-object. -

        -
        • -
      • -

        - directive- refers to an object or combination of objects in source documents, which is designed - to affect a particular outcome in the target catalog. For the most part, directives - are in the source profile document – for example, a - set-parameterobject in a source profile is a directive to set a parameter value in the target catalog. -

        -
        • -
      • -

        - original order- the order of objects as presented in the - sourcedocument(s). See XYZ. -

        -
        • -
      • -

        - canonical order- the order of objects as required in the appropriate OSCAL Model (Profile, Catalog, - etc.). This can differ from the above order when converting between "ordered" formats - (ex. XML), and "non-ordered" formats (ex. JSON). -

        -
        • -
      -
      -
      - -

      3.2 Requirement Keywords

      -       -

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD - NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are - to be interpreted as described in - BCP 14 - [RFC2119] - [RFC8174]when, and only when, they appear in all capitals, as shown here. -

      -
      -
      - -

      3.3 Use of YAML

      -       -

      OSCAL supports a variety of serialization formats, each of which having it's own benefits - and drawbacks. In this document, YAML (YAML Ain't Markup Language) is used to represent - the various objects of the - sourceand - target. All examples and in-line references will be represented using - YAML 1.2. -

      -

      YAML maps cleanly to JSON, thus allowing easy use of existing JSON/XML transformers - where needed. With that in mind, the - OSCAL Complete JSON Referenceis a valuable resource for understanding the YAML-based information structures used - in this document. All JSON properties and objects defined in the reference equate - to a YAML mapping, list, or dictionary. -

      -
      -
      - -

      3.4 Reading YAML Examples

      -       -

      YAML is a particularly human-readable format. For those unfamiliar with the format, - the basics:

      -
        -
      • -

        Each line is a key-value pair, presented as - key:value, or as - key:with any number of list items on the following lines. -

        -
        • -
      • -

        Indentation, spacing, and white space matters. Items below a key and indented one - level in are members (or children) of that key.

        -
        • -
      • -

        List items are represented with a preceding dash - - listitemkey:value. -

        -
        • -
      -

      The YAML specification is freely available here: - YAML 1.2. -

      -

      Additionally, in order to unambiguously express information, this specification uses - additional conventions, as described below.

      -

      There are some objects whose values must be determined dynamically at processing time. - The most common example of this is timestamping output as it is processed. In this - case, and any other dynamic-value cases, the expression - ${{ }}is used. -

      -

      For example:

      -
      -

      Target (catalog):

      - 
      last-modified: ${{ timestamp }}
      -
      -

      Indicates the - last-modifiedobject should be produced with contents generated appropriately, in this case, the - timestamp at the time of processing. -

      -

      Some examples may elide content to enhance readability or save space. In these cases, - a YAML comment (any line that starts with - #) will be used to explain the elision. -

      -

      Finally, although examples are syntactically faithful to OSCAL, they are not necessarily - always formally valid in every respect. For example, OSCAL defines allowed property - names ( - props) and values, and those rules may not be observed here. Examples are given for purposes - of illustrating profile resolution semantics only, and should not be taken as normative - for any actual use. -

      -
      -
      - -

      3.5 Document Layout

      -       -

      The specification is broken into the following major sections:

      -
        -
      • -

        - Phases of Profile Resolution- Lays out the necessary steps and phases of profile resolution. As each phase executes, - the processor is understood to be creating and editing an intermediate representation - of the output. There is one section for each of the three main phases. -

        -
        • -
      • -

        - Target Catalog Structure- Provides the requirements for structuring the final output from the intermediate - representation generated throughout the previous section. -

        -
        • -
      -

      - Please note: As referenced in the Purpose section - [See: 2.1 Purpose], this specification makes no hard requirements on the specifics of implementation. - It is feasible for an implementation to use no intermediate representation, and to - directly and iteratively build the output. As long as all processing and output requirements - are satisfied, any approach is allowed. With that said, the specification has been - laid out to aid in implementation by providing a clear organization as a sequence - of distinct operations. -

      -
      -
      - -

      3.6 The Intermediate and Implementation Guidance

      -       -

      The overall intent of this document, in addition to defining strict requirements, - is to provide rough guidelines on implementing an OSCAL Profile Resolution Tool. To - this end, each phase of resolution will be framed as a series of transformations applied - to an internal data structure that is persistent throughout the process. We call this - "the intermediate".

      -

      Any examples that are labelled as "Intermediate" are pseudo-code, designed to represent - how this data structure might look as we apply different operations to it. The example - intermediates are often not valid OSCAL, and are not to be taken as guidance, but - rather a useful visualization tool for implementers.

      -

      The authors believe that applying the steps of resolution in order against this intermediate - representation is the simplest way to achieve full compliance with the specification. - However, there is no requirement to implement profile resolution in this way. Requirements - are given as rules on the output of resolution, and as such, tools can operate any - way they would like internally.

      -
      -
      -
      - -

      4 Phases of Profile Processing

      -       -

      An OSCAL Profile has three major sections, each which correspond to a phase of profile - resolution. In order to complete the profile resolution process, each section must - be fully parsed and a catalog output created.

      -

      It is strongly RECOMMENDED that implementations execute the following steps in the - order that they are provided here. While it is possible to achieve compliance with - a non-standard approach, the iterative nature of profile resolution lends itself to - linear processing.

      -

      The three steps are - import; - merge; and - modify. In brief: -

      -
        -
      • -

        - import- identifies one or more control sources (catalogs or profiles) and defines the controls - within them to be included in the result catalog. If nothing is imported, no resulting - catalog is produced. Invoked by - importdirectives in source profiles; -

        -
        • -
      • -

        - merge- designates the rules for how controls will be organized (ordered and/or grouped) - and merged (addressing conflicts or ambiguities) in the result catalog. Controlled - by the - mergedirective in source profiles; if none are included, default merge rules are used; -

        -
        • -
      • -

        - modify- indicates how controls and their parameters in the underlying catalog are to be - altered, edited, amended or added in the final result catalog. Logical evaluation - and parameter constraints provide advanced processing. Controlled by the - modifydirective in source profiles. If a - modifydirective is not provided, no changes will be made to the controls that have been - imported/merged. -

        -
        • -
      -

      As described in the previous section, when resolved, an OSCAL Profile takes the form - of an OSCAL Catalog. The phases described below will produce outputs conforming to - the catalog model.

      -
      -
      - -

      5 Import Phase

      -       -

      A profile begins by listing a set of catalogs and/or profiles to be imported. Each - is represented by a resolvable resource URI and a directive specifying which controls - to import from that resource. These resources may be available as static resources, - or they may be produced dynamically on request; such as is the case when a profile - is imported. Imports are given in sequence after the metadata:

      -
      -

      Source (profile):

      - 
      -      
-profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: ${{ catalog URI }}
-      include-controls: ${{ list of selected controls }}
-    - href: ${{ profile URI }}
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      In an import directive, the reference to the resource to be imported appears on an - hrefchild object. It takes either of two forms, external or internal: -

      -

      An external reference appears as an absolute or relative URL:

      -
      -

      Source (profile):

      - 
      -      
-profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: >-
-        https://github.com/usnistgov/oscal-content/tree
-        /master/nist.gov/SP800-53/rev4/yaml/NIST_SP-800-53_rev4_catalog.yaml
-      include-controls: ${{ list of selected controls }}
-    - href: "../../NIST_SP-800-53_rev5_catalog.yaml"
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      While an internal reference appears as below (see - [See: 5.1.3 Internal References]): -

      -
      -

      Source (profile):

      - 
      -      
-profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: #80052rev4
-      include-controls: ${{ list of selected controls }}
-    - href: #80052rev5
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      All import directives will contain either - include-all: ~or - include-controls. These directives indicate which controls from the imported document are explicitly - selected - [See: 5.2 Including Controls]. -

      -

      The following section contains requirements for processing the - importchild of a source - profile -

      -
      - -

      5.1 Import href Requirements

      -       -
      - -

      5.1.1 Import URI Resolution

      -       -

      Tools MUST resolve URIs by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST - instead be resolved as defined in - [See: 5.1.3 Internal References]. -

      -
      -
      - -

      5.1.2 Import Resource Acquisition

      -       -

      Tools MUST acquire resources at the resolved URI by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST - instead be acquired as defined in - [See: 5.1.3 Internal References]. -

      -

      For the purposes of resolving URIs using the above specification, the Base URI MUST - be considered to be the absolute URI of the containing profile.

      -

      In the case that acquiring a resource fails, the tool MUST cease processing and provide - an error. In order to ensure profile resolution results in the same catalog regardless - of which tool resolves it, all imports must successfully resolve. While this may cause - inconvenience if resources are frequently not available, it ensures interoperability.

      -

      Note that receiving a cached version of an import, or resolving an import that is - otherwise unavailable through some other (but automatic) means still satisfies the - above requirement. This specification does not put requirements on the precise function - of the import, as long as the correct document is retrieved.

      -
      -
      - -

      5.1.3 Internal References

      -       -

      URI Fragments in OSCAL represent internal references to other OSCAL objects in the - same document. These references follow the pattern of "#{{objectID}}". For example, - the URI Fragment "#param1" is referencing the Parameter with unique ID "param1".

      -

      In the context of the Import Phase, internal references will only appear as a reference - to a profile or catalog that is in the resources section of the source. When tools encounter such a reference, they MUST locate the - object in resources with the matching ID value, and resolve the import using the - rlinkURI and the above resolution requirements. -

      -

      If the object fetched cannot be found or is not a valid OSCAL object, the tool MUST - cease processing and provide an error.

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  metadata: ~
-  imports:
-    - href: "#nist-sp800-53_catalog"
-      include-controls: ${{ list of selected controls }}
-    
-  # Content Elided
-    
-  backmatter:
-    resources:
-      - uuid: "nist-sp800-53_catalog"
-        description: "NIST SP 800-53 rev5 OSCAL format, on Github."
-        rlinks:
-          - rlink:
-              href: >-
-                https://github.com/usnistgov/oscal-content/tree
-                /master/nist.gov/SP800-53/rev4/xml/NIST_SP-800-53_rev5_catalog.xml   
-
      -
      -
      -
      - -

      5.1.4 Resolving Imports of Profiles

      -       -

      If the resource acquired is an OSCAL Profile, the tool MUST apply this specification - to resolve it, then continue processing having imported the resulting catalog.

      -

      When a profile imports a profile, the subordinate profile SHOULD be resolved first - into a catalog using this specification, before it is imported. This presents the - possibility of circular imports, when a profile is directed to import itself either - directly or indirectly.

      -

      A - circular importoccurs when a profile imports an already imported profile, which was called at an - earlier place in the import hierarchy. For example, if profile A imports profile B, - and profile B imports profile A, the second import is circular. (An import at the - top can only be circular if a profile tries to import itself.) If A imports B, B imports - C and C imports A, C’s import is circular. -

      -

      Note that an import can only be circular within the context of processing a particular - profile. In the last example, C’s import would not be circular if invoked in the context - of resolving B by itself.

      -

      If a processor encounters a - circular importas described above (self-imports are inherently circular), the processor MUST cease - processing and generate an error. -

      -

      A profile identified as - home_profile.yamlimports another one identified as - circular_profile.yaml: -

      -
      -

      Source (profile):

      - 
      -            
-profile:
-  id: "home_profile.yaml"
-  metadata: ~
-  imports:
-    - href: "circular_profile.yaml"
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      In turn this file invokes - home_profile.xml: -

      -
      -

      Source (profile):

      - 
      -            
-profile:
-  id: "circular_profile.yaml"
-  metadata: ~
-  imports:
-    - href: "home_profile.yaml"
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      Once detected, this circular import will result in an error and no further processing - will take place.

      -
      -

      Target (catalog):

      - 
      -            
-  # Import at href: "circular_profile.yaml" failed.
-  # Reason: Error during profile import:
-  # Import at href: "home_profile.yaml" failed.
-  # Reason: Circular import 
-
      -
      -
      -
      - -

      5.1.5 Multiple imports

      -       -

      Each import directive is processed to produce a set of controls. Note that this occurs - even if the same catalog is imported multiple times: each distinct import collects - controls into a separate - selection: -

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: "#catalog"
-      include-controls:
-       - with-ids:
-          - ac-1
-          - ac-2
-    - href: "#catalog"
-      include-controls:
-       - with-ids:
-          - ac-3
-          - ac-4 
-
      -
      -
      -

      Intermediate (catalog):

      - 
      -          
-intermediate:
-  inclusions:
-    - id: ${{uuid of #catalog}}
-      included-controls:
-          - ac-1
-          - ac-2
-    - id: ${{uuid of #catalog}}
-      included-controls:
-          - ac-3
-          - ac-4 
-
      -
      -

      The control inclusions are combined and collapsed in the next phase of processing, - merge(see [See: 6 Merge Phase]) . -

      -

      Multiple imports against the same resource are allowed, and would most commonly occur - when the profile author is using [See: 5.1.6 Mapping Controls] to create very specific output. - Multiple imports may result in outputs with clashing control IDs if mapping or the - merge directive is not set correctly.

      -
      -
      - -

      5.1.6 Mapping Controls

      -       -

      The optional - mappingchild of a given - importprovides a simple ID remapping for objects included from that specific import. This - provides the means for profile authors to proactively avoid clashing IDs of controls - and other objects. -

      -

      The Mapping section consists of 5 optional subsections, each covering a particular - type of object. Each subsection is a list of ID mappings to be applied for objects - that are the parent object type.

      -

      When encountering a given mapping instruction, processors:

      -
        -
      • -

        MUST change the distinctive ID of that object to be equal to the value of the - toobject. -

        -
        • -
      • -

        MUST update all known references to the old ID in other included content, allowing - the new ID to be used in subsequent profile sections.

        -
        • -
      -

      Since mapping is a self contained process inside each import, the rest of this specification - will continue to reference IDs with the assumption that mapping has already been applied - if it was present. Since mapping is most commonly used to avoid clashing IDs, processors - should take care to not handle duplicate IDs until after mapping is complete.

      -

      Below is a simple example of mapping. The second - importis included controls from a different catalog whose ID values happen to collide. Knowing - this, the profile author has remapped those IDs to new values. -

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: "#catalog"
-      include-controls:
-       - with-ids:
-          - ac-1
-          - ac-2
-    - href: "#catalog2"
-      include-controls:
-       - with-ids:
-          - ac-1
-          - ac-2
-      mapping:
-       - controls:
-          - from: ac-1
-            to: map-ac-1
-          - from: ac-2
-            to: map-ac-2
-
      -
      -

      Using the intermediate approach, an internal data structure resembling the following - would result from the above profile:

      -
      -

      Intermediate (catalog):

      - 
      -          
-intermediate:
-  metadata: ~
-  inclusions:
-    - id: ${{uuid of #catalog}}
-      included-controls:
-          - ac-1
-          - ac-2
-    - id: ${{uuid of #catalog2}}
-      included-controls:
-          - map-ac-1
-          - map-ac-2 
-
      -
      -
      -
      -
      - -

      5.2 Including Controls

      -       -

      Each import contains directives on which controls from the imported catalog are to - be fetched and used for further processing. Throughout the rest of the document we - will refer to this as "inclusion". - If a control is included, and the source profile makes no other changes to it, it - will be present in the output. Exclusion directives in this section, as well as directives - in the following two major sections (merge and modify), - may make changes to an included control or group that could cause it to appear differently, - or not at all, in the output. Using the intermediate implementation approach, any - control(s) that are included would be extracted from the referenced catalogs, any - applicable mappings would be applied, then the controls(s) would be stored.

      -
      - -

      5.2.1 include-all

      -       -

      When an import provides the - include-alldirective, ALL controls and groups in the referenced document (including nested controls) - MUST be included: -

      -
      -

      Source (profile):

      - 
      include-all: ~
      -
      -
      -
      - -

      5.2.2 include-controls plus with-id

      -       -

      When an import provides the - include-controlsdirective, with a - with-idchild, all controls in the referenced document whose - idmatch one of the listed - idvalues MUST be included: -

      -
      -

      Source (profile):

      - 
      -          
-include-controls:
-  - with-ids:
-    - id: ac-1
-    - id: ac-2
-
      -
      -
      -
      - -

      5.2.3 include-controls plus matching

      -       -

      Controls may also be included using match patterns against their IDs. This is useful - because related controls (either in a hierarchy, or together in a group) frequently - have related IDs as well.

      -

      When an import provides the - include-controlsdirective, with a - matchingchild, all controls in the referenced document whose - idmatches one of the listed - patternvalues (Glob matching) MUST be included: -

      -

      If a - matchingobject is provided with no - pattern, it MUST be treated as matching nothing. While not providing a pattern is technically - valid, resolution tool implementers should be aware that it is generally undesirable, - and warnings or notices to the user may be appropriate. -

      -
      -

      Source (profile):

      - 
      -          
-include-controls:
-  - matching:
-    - pattern: "ac*" 
-
      -
      -
      -
      - -

      5.2.4 Dealing with Nested Controls and Groups

      -       -

      In OSCAL, controls may contain child controls. For instance, in SP 800-53 many controls - are supplemented with control enhancements; in OSCAL these are represented as child - controls within parent controls. So parent AC-2 (in a given catalog) has children - AC-2(1) through AC-2(13), for example.

      -

      By default, inclusion of a control also causes any of that control's ancestors (or - parents) to also be included. By default, inclusion of a control DOES NOT cause the - inclusion of any descendants (or children) of that control to be included. This applies - to both controls and groups.

      -

      This default behavior can be modified by the following two optional children of the - include-controlsobject. -

      -
      - -
      5.2.4.1 with-child-controls
      -       -

      Child controls are, for the most part, treated the same as top level controls: they - can be explicitly included using the selection directives above. As a shortcut to - manually including all of the desired descendant controls of a given control, OSCAL - provides the "with-child-controls" option. "with-child-controls" appears as a child - object under a given inclusion directive, and defines additional behavior that is - to be executed alongside the parent inclusion.

      -

      A - with-child-controls: yesdirective on an - include-controlsindicates that - all descendant controlsof the included control MUST also be included. -

      -

      A - with-child-controls: nodirective on an - include-controlsindicates that ONLY the matching control is included, any descendant children are - not included. -

      -

      If no - with-child-controlsis provided, the processor MUST consider the directive as being equivalent to one - having - with-child-controls:no. -

      -
      -
      - -
      5.2.4.2 with-parent-controls
      -       -

      Although similar to the above - with-child-controls, the optional - with-parent-controlsapplies to parents of the included control, and has the opposite default behavior. - In order to maintain the structure of the source catalog, profile resolution includes - all parents of an included control by default. If a profile author wants to change - this structure, they could use an exclude directive that lists all of the undesired - parents. As a shortcut for this, - with-parent-controlsprovides the following functionality: -

      -

      A - with-parent-controls: yesdirective on an - include-controlsindicates that - all parent controlsof the included control MUST also be included. -

      -

      A - with-parent-controls: nodirective on an - include-controlsindicates that ONLY the matching control is included, any parents are not included. -

      -

      If no - with-parent-controlsis provided, the processor MUST consider the directive as being equivalent to one - having - with-parent-controls:yes. -

      -
      -
      -
      - -

      5.2.5 exclude-controls

      -       -

      Exclusions work the same way as inclusions, except with the opposite effect - the - indicated control(s) do not appear in the target catalog.

      -

      Any control designated to be both included and excluded, MUST be excluded. This holds - irrespective of the specificity of the selection for inclusion or exclusion. For example, - if AC-1 is included by id - ac-1and excluded by matching - ac.*, it is excluded. -

      -

      When - exclude-controlshas at least one - with-idsor - matchingdirective, the processor MUST follow the same rules as defined in the relevant sections - above for these directives, but exclude instead of include any controls. All optional - features (with-child-controls, etc.) also apply to exclusion directives. -

      -
      -
      - -

      5.2.6 Redundant Inclusions and Exclusions

      -       -

      A given - importmay have any number of inclusion statements and any number of exclusion statements. - Their effect is cumulative; any control that is included (or excluded) more than once - MUST be considered to be included (or excluded) only once. In other words, a given - control being included or excluded more than once has no effect. Exclusion still takes - priority over inclusion (see above). -

      -

      Note that this requirement only applies to controls included within the context of - a single import. Controls with duplicate IDs included under a different - importare not discarded. Also note that this redundancy pruning happens after any relevant - mappings have been applied. -

      -
      -
      - -

      5.2.7 Handling Params

      -       -

      Any - paramthat is not directly under a control is referred to as a - looseparam. -

      -

      All loose params from both imported documents and the profile source MUST be included. - These params will be kept in the final output if document contains any references - to them, and discarded otherwise. See - [See: 8.3 Pruning and Ordering]. Since new references can be created during the - modifyphase, tools should be careful not to prune params without fully understanding the - final state of the output document. -

      -
      -
      - -

      5.2.8 Handling Groups

      -       -

      Some source catalogs use - groupobjects to place controls into arbitrary groupings. Tools will need to be aware of - these groups when executing the "merge" phase below, as they will duplicated into - the output under the "as-is" mode and can be referenced in "custom" mode. The naïve - intermediate approach would keep all groups until all other phases are complete, but - implementations may find it more performant to look ahead and prune unused groups - early. -

      -
      -
      - -

      5.2.9 Avoiding Implementation Pitfalls

      -       -

      In order to ensure that implementers have as much flexibility as possible, requirements - in this section have purposefully been kept minimal. Below are some common issues - for implementers to be aware of:

      -
        -
      • The ordering and hierarchical organization of included controls as they were present - in the original catalog may be used later in the resolution process. - Specifically, if the profile is using the "as-is" structuring directive, the ordering - and organziation of the output should match the source catalog as closely as possible. - - Implementations may want to track this information, or look ahead to see what structuring - mode is being used. Note that "as-is" also requires implementations to replicate any - use of the group element. -
        • -
      -
      -
      -
      - -

      5.3 Wrapping up the Import Phase

      -       -

      At this point all requirements for content importing and control inclusion have been - covered. If using the intermediate approach, the processor should have an intermediate - that contains: a set of included controls and all of their child informational (non-control, - non-group) objects, any relevant - groupobjects and their informational content, and a set of included "loose params" - [See: 5.2.7 Handling Params](zero to many). The general structure of the intermediate would match that of the - imported catalogs (i.e. Nested controls remain nested, grouped controls remain grouped). -

      -
      -
      -
      - -

      6 Merge Phase

      -       -

      Profiles may contain a - mergesection, where directives are given to instruct the processor how to combine the set - of included objects collected during the Import Phase. - mergehas two parts: a "combine" directive, and a "structuring" directive. -

      -

      It is RECOMMENDED that tools apply the "combine" directive to the intermediate generated - by the Import phase first, then apply the "structuring" directive.

      -

      The following section contains requirements for processing the - mergechild of a source profile. -

      -
      - -

      6.1 The "combine" Directive

      -       -

      - combineis an optional child of - mergethat provides the rules for dealing with objects that have duplicate (or clashing) - distinct IDs - [See: 9.1 Distinct ID of Objects]. -

      -

      There are two valid combination methods provided by OSCAL, provided by the - methodchild of - combine: -

      -
        -
      • -

        use-first: Use the first definition - the first control with a given ID is used; subsequent - ones are discarded

        -
        • -
      • -

        keep: Keep - controls with the same ID are kept, retaining the clash

        -
        • -
      -

      Note that "merge: combine" is deprecated, and MUST be considered undefined behavior - when encountered.

      -

      In order to apply the combination method, IDs of each control explicitly included - are compared against one another. As IDs are unique across entire OSCAL documents, - different imports or any groupings have no bearing on collision. Processing requirements - for each method are described below.

      -
      - -

      6.1.1 No Combine Directive

      -       -

      If no - mergedirective is given in the profile, or if a - mergeis given without a - combine, merge conflicts MUST be treated as if - method: keepwas given. For example, a profile with no - mergedirective: -

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~ 
-
      -
      -

      is the same as

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~
-  merge:
-    combine:
-      method: keep
-      flat: ~ 
-
      -
      -
      -
      - -

      6.1.2 - method:keep -

      -       -

      When a merge is indicated by - method:keep, or not given, the - keepcombination rule is used. Any controls with the same distinctive ID - [See: 9.1 Distinct ID of Objects]MUST NOT not merged. (They are kept.) -

      -
      -

      Source (profile):

      - 
      -          
-  merge:
-    combine:
-      method: keep 
-
      -
      -

      Under this directive, colliding controls will result in invalid results, as they will - both appear in the results with the same ID. Accordingly, this setting may be useful - in ensuring integrity of references to controls as given in the profile: if any included - control is called only once, clashing controls will not be produced and validation - will succeed.

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-2
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-2 
-  merge:
-    combine:
-      method: keep
-
      -
      -

      In the intermediate (showing control inclusions):

      -
      -

      Intermediate (catalog):

      - 
      -          
-intermediate:
-  inclusions:
-    - explicitly-included-controls:
-          - ac-1
-          - ac-2
-          - ac-1
-          - ac-2 
-
      -
      -

      In this case, downstream errors should be expected: the two - ac-1controls clash with each other, as do the two - ac-2controls. -

      -

      Processors SHOULD provide a warning under this directive when duplicate controls are - detected. The processor MAY throw an error and cease processing (short-circuiting - a certain future error).

      -
      -
      - -

      6.1.3 - method:use-first -

      -       -
      -

      Source (profile):

      - 
      -          
-  merge:
-    combine:
-      method: use-first 
-
      -
      -

      When the - use-firstcombination rule is applied, and controls that share a distinctive ID are found, the - first control encountered MUST be kept, the rest MUST be discarded. - FirstMUST be determined by a top-down, depth-first traversal of the source profile's import - hierarchy. -

      -
      -

      Source (profile):

      - 
      -            
-profile:
-  imports:
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-3
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-2 
-  merge:
-    combine:
-      method: use-first
-
      -
      -

      In the intermediate(showing control inclusions):

      -
      -

      Intermediate (catalog):

      - 
      -            
-intermediate:
-  inclusions:
-    - explicitly-included-controls:
-          - ac-1 (From catalog1)
-          - ac-3
-          - ac-2 
-
      -
      -
      -
      - -

      6.1.4 - method:merge -

      -       -

      Deprecated, unspecified behavior.

      -
      -
      -
      - -

      6.2 The "structuring" Directive

      -       -

      This section describes how a profile may dictate the structure of the target - catalog, apart from its - metadataor - back-matter. Optionally, one of three "structuring" directives can be included as a child of - merge: - flat, - as-isand - custom. When one of these appears, it is the selected structuring directive. If more than - one appears, processors MUST generate an error and cease processing. Processing requirements - for each are given below: -

      -
      - -

      6.2.1 No Structuring Directive

      -       -

      If no - mergedirective is given in the profile, or if a - mergeis given without a structuring directive, structuring the output MUST be treated as - if the structuring directive - flatwas given. For example, a profile with no - mergedirective: -

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~ 
-
      -
      -

      is the same as

      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~
-  merge:
-    combine:
-      method: keep 
-      flat: ~ 
-
      -
      -
      -
      - -

      6.2.2 "flat"

      -       -

      Profiles with the "flat" merge directive are resolved as unstructured catalogs, with - no groupings of controls.

      -

      Unstructured catalog output MUST be produced by adhering to the following requirements:

      -
        -
      • -

        All included controls are output to the target as a flat list directly under "catalog".

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under - "catalog".

        -
        • -
      • Any groups are discarded.
        • -
      -

      An example of flat structuring is provided below

      -
      -

      Source (catalog):

      - 
      -          
-catalog:
-  groups:
-    - groupA
-      - ac-1
-      - ac-2
-    - groupB
-      - bc-1 
-
      -
      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalogURI
-      include-controls:
-        with-ids:
-          - ac-1
-          - ac-2
-          - bc-1
-  merge:
-    combine:
-      method: keep 
-      flat: ~ 
-
      -
      -
      -

      Intermediate (catalog):

      - 
      -          
-intermediate:
-  controls:
-    - ac-1
-    - ac-2
-    - bc-1 
-
      -
      -
      -
      - -

      6.2.3 - as-is -

      -       -

      An - as-isdirective is used to reproduce the structure of the source documents in the target - catalog. -

      -

      Processors MUST handle the - as-isdirective by adhering to the following requirements: -

      -
        -
      • -

        All included controls are output to the target, keeping the structure of the groups - and nested controls. Any group that holds an included control MUST appear in the output - with all of its non-control children intact. - If an included control has a parent control that was not included, that control's - output location is "up-leveled", or made equal to the non-included parent. This applies - recursively until the control is directly under either "catalog" or another included - control.

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under - "catalog".

        -
        • -
      -

      Example:

      -
      -

      Source (catalog):

      - 
      -          
-catalog:
-  groups:
-    - groupA
-      - ac-1
-      - ac-2
-    - groupB
-      - bc-1 
-
      -
      -
      -

      Source (profile):

      - 
      -          
-profile:
-  imports:
-    - href: #catalogURI
-      include-controls:
-        with-ids:
-          - ac-1
-          - ac-2
-          - bc-1
-  merge:
-    combine:
-      method: keep 
-      as-is: ~ 
-
      -
      -
      -

      Intermediate (catalog):

      - 
      -          
-intermediate: 
-#In this approach, the original hierarchy of the controls under the groups is stored,
-#but is not shown in this example.
-  controls:
-    - ac-1
-    - ac-2
-    - bc-1
-  groups:
-    - groupA
-    - groupB 
-
      -
      -
      -
      - -

      6.2.4 - custom -

      -       -

      The - customdirective provides the target catalog with a custom structure. A one-to-one mapping - of the desired structure of the target catalog is defined alongside control matching - instructions, resulting in a strictly controlled output catalog. -

      -
      - -
      6.2.4.1 Creating Custom Groups
      -       -

      A - groupobject given under - customMUST result in a - groupwith the exact same content (excluding - insert-controls) in the target catalog. -

      -

      If the ID of the group matches the ID of a group that has been included during the - import phase, all contents inside the group, including - title, - param, - propand - partobjects MUST be copied into the target, appearing in the same order as in the source. -

      -

      Note that groups defined in - custommay vary from fully featured to minimally instantiated. This includes arbitrary nesting - of such groups inside of one another. No groups other than those explicitly declared - should appear in the output catalog. -

      -
      -
      - -
      6.2.4.2 Inserting Controls
      -       -

      The - insert-controlsdirective may appear anywhere under - custom, whether as a direct child or inside any of the defined groups. Inside insert-controls, - include-controlsand - include-allfrom the Import Phase - [See: 5 Import Phase]are used with the same basic behavior to configure which controls are selected and - inserted at the current location. -

      -

      In order to provide clarity, controls that match the various conditions of these inclusion - directives inside the - customobject will be referred to as "selected" instead of "included". Only directly selected - controls will appear in the target catalog. -

      -

      A - insert-controlswith an - include-controlschild results in the following behavior: -

      -
        -
      • -

        - with-idresults in selecting and inserting, at that point inside the new grouping, the included - controls with the - idgiven by - with-id. They should be given in the same order as they appear in the control selection(s). -

        -
        • -
      • -

        A - matchingdirective results in selecting and inserting, at that point inside the new grouping, - all included controls whose - idmatch, as a Glob expression, the pattern given in the - pattern. They are given in the same order as they appear in the input control selection(s). -

        -
        • -
      -

      An - insert-controlswith an - include-allchild results in all included controls being selected and inserted. They are given - in the same order as they appear in the input control selection(s). -

      -

      - insert-controlscan also indicate the order that the selected controls are to be emitted in the result - catalog using an - orderchild. Three values MUST be supported and handled as specified below: -

      -
        -
      • -

        - ascendingwill sort all selected controls into ascending alphanumeric order by their ID. -

        -
        • -
      • -

        - descendingwill sort all selected controls into descending alphanumeric order by their ID. -

        -
        • -
      • -

        - keepindicates that controls should be inserted in the order of their appearance, using - a depth-first traversal of the source profile's imports. -

        -
        • -
      -

      In the case that a control selection matches none of the included controls, it MUST - be ignored; a warning SHOULD be provided. If a control that was included by the Import - Phase is never selected, no error occurs, that control simply does not appear in the - output catalog.

      -
      -
      -
      -
      - -

      6.3 Wrapping up the Merge Phase

      -       -

      After the merge phase, the intermediate should now closely resemble the content and - structure of the final output catalog. Controls and groups have been included, remapped, - de-duplicated, then placed into their final location within the output's structure. - Note: there is still an opportunity for included controls or groups to become referenced; - and therefore, not eligible for pruning - [See: 8.3 Pruning and Ordering]in the next phase. -

      -

      Regardless of any merge directives, there also likely remains "loose params" that - have been propagated forward; these too must be persisted.

      -
      -
      -
      - -

      7 Modify Phase

      -       -

      There are two ways profiles may further modify the results of profile resolution: - setting parameters, and altering controls. These activities are defined as two child - objects inside the third step of profile resolution, the Modify Phase.

      -

      The following section contains requirements for processing the - modifychild of a source profile. -

      -
      - -

      7.1 Setting Parameters

      -       -

      Modification of parameter settings is indicated using the - set-parameterobject under - modify. For this section, a given - set-parameterobject will be referred to as the - source. -

      -

      Profile Resolution Tools MUST adhere to the following requirements for processing - "set-parameter":

      -
        -
      • -

        First, the list of included params (among "loose params" and remaining included controls - and groups) is searched for a param who has a "id" equal to this object's "param-id". - This is the "target". If no such parameter is found, a warning SHOULD be issued, but - processing MUST continue.

        -
        • -
      • -

        When encountering the following objects in the source: class, depends-on, label, usage, - values, select; overwrites the object of the same name in the target. If no such object - exists in the target, it is created.

        -
        • -
      • -

        When encountering the following objects in the source: props, links, constraints, - guidelines; adds the contents of the source object to the contents of the target object - of the same name. If no such object exists in the target, it is created. For each - individual child object of "props" and "links" in the source, if an individual child - inside the target object has the same distinctive ID, it is instead overwritten by - the source object - [See: 9.1 Distinct ID of Objects] -

        -
        • -
      • -

        If more than one - set-parameterdirective is given for the same parameter, all are applied, in the sequence given - in the profile. -

        -
        • -
      -
      -
      - -

      7.2 Altering controls

      -       -

      A control can be altered by an - alterobject inside "modify". The - control-idchild object under the - alterindicates the control to which the alteration is applied. -

      -
      - -

      7.2.1 Adding contents to controls

      -       -

      Contents may be added to controls using an add directive inside an alter directive. - There are two forms of alteration: with implicit and explicit bindings.

      -
      - -
      7.2.1.1 Implicit binding
      -       -

      An - adddirective with no - by-idis taken to apply to the control as a whole. Its - positionmay be either of two values: - startingand - ending. -

      -

      The contents of the add directive are then added to the control contents in the target, - either after its - titlewhen - positionis - starting, or at the end if its position is - ending, or not given. -

      -

      However, control contents in catalogs must appear in the order - title, param, prop, link, part, control. Subsequent to adding new objects, the control contents are sorted to appear in the - required order. As a consequence, a new - propappears after any - propalready in the control, when - positionis - ending, or not given, or before any - propin the control when - positionis - starting. -

      -

      When add has no - ref-id(has an implicit binding), the - positionvalues - beforeand - afterare treated like - startingand - ending, respectively. - The schema permits these values. -

      -

      An addition operating on a control with implicit binding and position - starting -

      -
      -

      Source (catalog):

      - 
      -               
-control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready 
-
      -
      -
      -

      Source (profile):

      - 
      -               
-alter:
-  control-id: a1
-  add:
-    position: starting
-    props:
-      - name: basis
-        value: enumerated
-    parts:
-      - name: caution
-        prose: \\n\\nPending scheduled testing. 
-
      -
      -
      -

      Target (catalog):

      - 
      -               
-control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: basis
-      value: enumerated
-    - name: status
-      value: ready
-  parts:
-    - name: caution
-      prose: \\n\\nPending scheduled testing. 
-
      -
      -

      Position is - startingbut the new - partis added after the existing - prop, because - propobjects must always occur first. -

      -

      An addition operating on a control with implicit binding and position - ending -

      -
      -

      Source (catalog):

      - 
      -               
-control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready 
-
      -
      -
      -

      Source (profile):

      - 
      -               
-alter:
-  control-id: a1
-  add:
-    position: starting
-    props:
-      - name: basis
-        value: enumerated
-    parts:
-      - name: caution
-        prose: \\n\\nPending scheduled testing. 
-
      -
      -
      -

      Target (catalog):

      - 
      -               
-control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready
-    - name: basis
-      value: enumerated
-  parts:
-    - name: caution
-      prose: \\n\\nPending scheduled testing. 
-
      -
      -

      The - positionis - endingso the new - propappears after the existing - prop. -

      -
      -
      - -
      7.2.1.2 Explicit binding
      -       -

      An explicit binding on an addition permits inserting new contents anywhere in a control, - not only at the top level. It is given by a - ref-idon the - adddirective. The value of the - ref-idmust correspond to the value of an - idon an object inside the control, and not the control itself. If - ref-iddoes not correspond to such a value, the - adddirective is inoperative. A warning MAY be issued in such a case. -

      -

      The object with - idequal to the - ref-idis considered the - targetof the addition. -

      -

      Additionally, with an explicit binding given by a - ref-id, - positionmay have any of the values - starting, - ending, - beforeand - after. -

      -

      When - positionis - startingor - ending, the new contents are added at the beginning or ending of the target object, inside - that object, as are additions into controls (using implicit bindings). -

      -

      Additionally, a - positiongiven as - beforeindicates the addition should be made directly before the target object, while - afterindicates the addition should appear directly after the target object. -

      -

      An addition operating on a control with explicit binding and position - after -

      -
      -

      Source (catalog):

      - 
      -               
-control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready
-  parts:
-    - name: recommendations
-      id: a1.b
-      parts: 
-        - name: task1
-          id: a1.b1
-          prose: Collect recycling for pickup
-        - name: task2
-          id: a1.b2
-          prose: Sweep surfaces free of dust
-
      -
      -

      Note that the - adddirective identifies the object with - id - a1.b1as its target. -

      -
      -

      Source (profile):

      - 
      -               
-alter:
-  control-id: a1
-  add:
-    position: after
-    ref-id: a1.b1
-    props:
-      - name: basis
-        value: allocated
-    parts:
-      - name: caution
-        prose: Unavailable on weekends 
-
      -
      -
      -

      Target (catalog):

      - 
      -               
-control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready
-  parts:
-    - name: recommendations
-      id: a1.b
-      parts: 
-        - name: task1
-          id: a1.b1
-          prose: Collect recycling for pickup
-        - name: caution
-          prose: Unavailable on weekends
-        - name: task2
-          id: a1.b2
-          prose: Sweep surfaces free of dust
-      props:
-        - name: basis
-          value: allocated
-
      -
      -

      The - positionis - afterso both objects inside - addare added after (not inside) the target object. Since the target object is inside - another - partin the control, the new additions appear there as well. -

      -

      Note that the result in this case will be schema-invalid since a - propmay not occur directly following a - part. A better result can be obtained (a better target may be defined) by using two - adddirectives, to insert the new - propseparately before any - partobjects in the target. -

      -
      -
      - -
      7.2.1.3 Usage of - adddirectives modifying controls inside controls -
      -       -

      OSCAL supports control extensions inside controls in the form of - controlobjects inside - controlobjects. Because the semantics of the - adddirective target any (object) contents of controls, they can be used to target these - control extensions for modification as well as other contents. -

      -

      Because such a control can already be modified using implicit bindings, it is recommended - that they not be targeted with explicit bindings. Using an implicit binding supports - more robust alteration since contents in the target can be ordered properly by the - resolution processor. - XXX can we guarantee valid results here and do we have to specify a sort/order?However, it is not an error to target control objects in this way, manipulating them - in the same way as other targets may be manipulated. -

      -
      -
      -
      - -

      7.2.2 Removing contents from controls

      -       -

      Contents inside controls can be removed from them in catalog targets. In combination - with adding new contents, this feature can be used to edit controls as well as amend - them.

      -

      A - removedirective inside an - alterdirective identifies an object or set of objects inside a control to be removed. It - does this using any of five child objects. These are - additive; that is, if more than one is given, all must match: -

      -
        -
      • -

        - by-id, like - add:by-id, matches an object by its - idvalue. -

        -

        Because - idvalues are unique, the remove directive will remove only a single object. Ordinarily - this would not combined with other identifiers for removal. -

        -
        • -
      • -

        - name-refkeys to the - namechild object on any object inside the control. -

        -

        Any object inside the control with the assigned - name, is removed (typically providing there is also a match on - ns). -

        -
        • -
      • -

        - ns-refkeys to the - nschild object on any object inside the control. -

        -

        Any object inside the control with the assigned - name, is removed (typically providing there is also a match on - name). -

        -
        • -
      • -

        - class-refkeys to the - classchild object on any object inside the control. All objects with matching - classare removed. -

        -
        • -
      • -

        - item-namekeys to the object or property name; for example, - remove: item-name: prophas the effect of removing all - propobjects from inside the control. -

        -
        • -
      -

      Unlike an - adddirective, a - removemay not be bound implicitly to the control; its binding, to contents inside the control, - must be explicit. -

      -

      To remove an control, simply avoid selecting it into the profile, or exclude it specifically - using - import/exclude-controls. -

      -

      As with - add, a remove that targets any object outside the control, is inoperative. Similarly, - a remove directive that indicates that all - propobjects should be removed from the target catalog, applies only to - prop -

      -
      -
      -
      -
      - -

      8 Final Operations

      -       -
      - -

      8.1 Backmatter Resolution

      -       -

      - back-matterin the result is produced by combining all objects within - back-matterin all source catalogs, with the - back-matterin the input profile. The merge method and merge structuring directives are ignored. - The following requirements MUST be adhered to by the processor: -

      -
        -
      • -

        Each import's backmatter is processed in order it was provided in the source profile, - then the source profile's backmatter is processed.

        -
        • -
      • -

        Each - resourceis added to the target in the order given inside the import. -

        -
        • -
      • -

        If a - resourcehas the same - uuidas a resource that has already been added, the previous resource is removed, and the - more recent one added. -

        -
        • -
      • -

        A resource with a child prop of name:keep and value:always can only be replaced following - the above rule by a duplicate that also has the keep always prop.

        -
        • -
      -

      Tools MAY check for pruning conditions - [See: 8.3 Pruning and Ordering]as resources are added as long as the final result is the same as if the pruning had - taken place at the end of all resource addition. -

      -

      Placing the keep always prop on a resource in a catalog has the effect of ensuring - it will always appear in the output produced by any profile importing that catalog, - even if nothing links to the resource. This version of the resource will also be the - one copied, unless a later-imported catalog or importing profile offers its own version - marked to keep always.

      -
      -
      - -

      8.2 Metadata Resolution

      -       -

      The following requirements MUST be followed with regards to the Metadata section of - the output catalog:

      -
        -
      • -

        The output catalog MUST have a unique top-level UUID (metadata:uuid). This UUID may - be generated as seen fit by the tool, as long as it is reasonable to assume it is - globally unique. It is RECOMMENDED that tools use a combination of meaningful text - and a uniquely generated value (Ex. - {{sourceprofilename}}-RESOLVED-{{GUIDv5}}). -

        -
        • -
      • -

        The value of metadata:version in the target MUST be set with a string that identifies - the version of this document. This SHOULD be used to track updates to this specific - output document.

        -
        • -
      • -

        The value of metadata:oscal-version in the target MUST be set with a string that identifies - the version of OSCAL used by this tool to resolve the profile (ex. 1.0.0). This value - MUST be determined by compiling the oscal-versions from each imported document and - the source profile, and taking the most recent minor version. If this version is more - recent than what the resolution tool is using, then the value of the output oscal-version - MUST be the version that the tool used internally. If any of the above OSCAL versions - (imported document versions, source profile version, tool version) are of a different - major version (the first digit differs), the tool SHOULD provide an error and cease - processing.

        -
        • -
      • -

        The value of metadata:last-modified in the target MUST be set with a valid timestamp - representing the time the profile resolution completed.

        -
        • -
      • -

        The value of metadata:source-profile in the target SHOULD be set with a valid URI - that points to the profile that resulted in this catalog. If there are privacy or - security concerns, the value MAY be set to anything, in which case the simple existence - of the source-profile property indicates that this is a resolved profile.

        -
        • -
      • -

        The value of metadata:resolution-tool in the target SHOULD be set with a string that - represents the tool that was used to resolve this catalog.

        -
        • -
      • For any metadata:roles or metadata:parties that exist in the source catalogs, if they - have a prop child with name:keep and value:always, they are to be copied as is into the output - metadata.
        • -
      -

      Beyond these requirements, tools are free to use any and all of the objects inside - metadata to provide additional information downstream.

      -

      Because of options in producing metadata and especially the requirement for a timestamp, - developers and users should note that two different resolutions of the same profile - will not, ordinarily, be identical inside - metadata. -

      -
      -
      - -

      8.3 Pruning and Ordering

      -       -

      The processor SHOULD prune the result catalog to remove unused values. A given object - is considered unused if it meets ALL of the following criteria:

      -
        -
      • -

        The object does not have a child prop with name:keep and value:always

        -
        • -
      • -

        The object is not explicitly included - [See: 5.2 Including Controls]. -

        -
        • -
      • -

        There are no references to the object anywhere in the final result catalog, except - in other objects that also meet all other pruning criteria. A reference to a given - object exists if "#{distinctiveID}" appears anywhere, where {distinctiveID} is the - distinctive ID of the object - [See: 9.1 Distinct ID of Objects]. -

        -
        • -
      -

      Implementers should note that pruning need not take place after all other steps. As - long as all above criteria are respected, pruning can happen at any time, and doing - so is a likely performance and memory overhead improvement.

      -

      Tools MUST reorder the output catalog into canonical order - [See: 9.2.4 Order of objects in serialization], except where this specification provides different ordering requirements. -

      -
      -
      -
      - -

      9 Items of Note

      -       -
      - -

      9.1 Distinct ID of Objects

      -       -

      Whenever this specification refers to - distinctiveness, it MUST be interpreted as is defined in this section with regards to the object - in question. -

      -

      control,param,group - distinctiveness is defined by the value of the - idchild object. -

      -

      resource - distinctiveness is defined by the value of the - uuid - [See: 8.1 Backmatter Resolution]. -

      -
      -
      - -

      9.2 Dealing with Multiple Formats

      -       -

      Profile Resolution tools SHOULD be able to handle source profiles, imported catalogs, - and imported profiles that are serialized in XML, JSON, or YAML. A different serialization - format of any given input MUST NOT result in a differing output catalog.

      -

      In order to help bootstrap this format management, the following resources are provided - for implementers:

      -
        -
      • -

        . - -

        -
        • -
      -

      The following sections provide additional requirements and guidance for each format.

      -
      - -

      9.2.1 Requirements and Guidance for XML Output

      -       -

      See - the complete XML referencefor model requirements. -

      -
      -
      - -

      9.2.2 Requirements and Guidance for JSON Output

      -       -

      See the - complete JSON referencefor model requirements. -

      -

      The JSON format, in general use, does not require the preservation of order of fields. - As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order - [See: 9.2.4 Order of objects in serialization]when outputting a catalog in JSON. -

      -
      -
      - -

      9.2.3 Requirements and Guidance for YAML Output

      -       -

      YAML is considered a simple variation on the JSON format. Beyond cosmetic differences - there are no differences in the information structure between these formats. Therefore, - the - complete JSON referenceprovides model requirements. -

      -

      The YAML format, in general use, does not require the preservation of order of fields. - As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order - [See: 9.2.4 Order of objects in serialization]when outputting a catalog in YAML. -

      -
      -
      - -

      9.2.4 Order of objects in serialization

      -       -

      In OSCAL, order of top level objects (those that are direct children of the root element) - is considered important only when the XML format is used. To facilitate this, OSCAL - provides the concept of - canonical order. This order is provided by the OSCAL Metaschema files for a given document type (see - an overview of Metaschema. -

      -

      When the output format is XML, tools MUST use the OSCAL canonical order as described - above. When using the YAML or JSON formats, order conveys no meaning, and is not considered - important.

      -
      -
      - -

      9.2.5 Comments in result documents

      -       -

      In an XML-based profile resolution, XML comments are one straightforward way for a - processor to record events or conditions without affecting the output's nominal semantics. - To support this, while two processors are obliged to return the same catalog XML for - the same profile XML inputs, they are not required to match one another's comments, - white space usage, attribute order, or processing instructions, only each other's - objects, attributes and data content.

      -

      One consequence of this is that processes intended to compare two profile resolutions - may have to accommodate differences in comments, considering them as insignificant - along with other differences in serialization.

      -
      -
      -
      -
      - - \ No newline at end of file diff --git a/src/specifications/profile-resolution/profile-resolution-specml-102.xml b/src/specifications/profile-resolution/profile-resolution-specml-102.xml deleted file mode 100644 index 5fcffde022..0000000000 --- a/src/specifications/profile-resolution/profile-resolution-specml-102.xml +++ /dev/null @@ -1,1538 +0,0 @@ - - - - - - - OSCAL Profile Resolution -
      - Notice of Draft Status -

      Please note that this specification is currently a work in progress and is subject to change. If you have any feedback or comments, please create an issue at the NIST OSCAL Github Repository: github.com/usnistgov/OSCAL.

      -
      -
      - Abstract -

      This specification provides the minimal requirements for processing an OSCAL Profile to create a new OSCAL Catalog Document. This process of applying a profile to a catalog to create a new catalog is called - Profile Resolution. Not all OSCAL Profiles will be resolved, nor are expected to be; however, the resolution requirements in this document are crucial to understanding the intended functionality of any given OSCAL Profile. - This specification is intended for software developers who intend to develop an OSCAL Profile Resolver, or for OSCAL Profile authors who want a more in-depth understanding of profile resolution. -

      -
      -
      - Introduction -
      - Purpose -

      - Information systems are implemented against a baseline of security controls. An OSCAL Profile defines the selection and potential alterations to a control catalog that are needed to establish a baseline. However, the OSCAL implementation layer depends on having an OSCAL Catalog that represents the baseline of controls to be implemented. Profile Resolution allows for computing an effective catalog based on an OSCAL Profile. For a given OSCAL Profile, the Profile Resolution process needs to result in the same OSCAL Catalog when executed by different tools on different endpoints. The requirements for resolution must therefore be well-defined and deterministic, enabling tool developers and parties exchanging OSCAL Profiles to work from a common understanding. This document defines the normative requirements for an OSCAL Profile Resolver. -

      - -

      No requirements are placed on implementation-level details, instead, requirements are laid out as what the output of resolution must look like given a certain input. - By adhering to these requirements OSCAL producers, OSCAL consumers, and any other members of the OSCAL ecosystem can create and resolve profiles deterministically, - with repeatable results, regardless of the tool used.

      -
      -
      -
      - Reading This Document -
      - - Terminology -

      Many core OSCAL concepts are defined on the OSCAL Terminology Page. The most important are repeated in this document, but readers should verify their understanding of all core OSCAL terms before reading this document.

      -

      Additionally, many terms in the wider domain have overloaded definitions. Unless defined otherwise by OSCAL or explicitly in this document, terms are to be understood as defined in the NIST CSRC Glossary.

      -
        -
      • -

        - profile- an OSCAL Profile Document. Defines a set of inclusions, modifications, and transformations against a - catalog. See - OSCAL Profile Model. -

        -
        • -
      • -

        - catalog- an OSCAL Catalog Document. Contains a well-defined set of - controls. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - control- an individual item in an OSCAL Catalog. See - NIST Special Publication 800-53r5for a more in-depth definition. -

        -
        • -
      • -

        - profile resolution- The process of consuming one or more OSCAL Profiles and the OSCAL Catalogs that they reference to produce a new tailored - catalog. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - source- refers to the profile document that is input into the profile resolution processor. This is the profile being resolved. In this document, when referring to objects from the - sourcedocument, the following style is used: - source-object. -

        -
        • -
      • -

        - target- the intended output of the transformation, a catalog document. In this document, when referring to objects of a - targetdocument, the following style is used: - target-object. -

        -
        • -
      • -

        - directive- refers to an object or combination of objects in source documents, which is designed to affect a particular outcome in the target catalog. For the most part, directives are in the source profile document – for example, a - set-parameterobject in a source profile is a directive to set a parameter value in the target catalog. -

        -
        • -
      • -

        - original order- the order of objects as presented in the - sourcedocument(s). See XYZ. -

        -
        • -
      • -

        - canonical order- the order of objects as required in the appropriate OSCAL Model (Profile, Catalog, etc.). This can differ from the above order when converting between "ordered" formats (ex. XML), and "non-ordered" formats (ex. JSON). -

        -
        • -
      -
      -
      - Requirement Keywords -

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in - BCP 14 - [RFC2119] - [RFC8174]when, and only when, they appear in all capitals, as shown here. -

      -
      -
      - Use of YAML -

      OSCAL supports a variety of serialization formats, each of which having it's own benefits and drawbacks. In this document, YAML (YAML Ain't Markup Language) is used to represent the various objects of the - sourceand - target. All examples and in-line references will be represented using - YAML 1.2. -

      -

      YAML maps cleanly to JSON, thus allowing easy use of existing JSON/XML transformers where needed. With that in mind, the - OSCAL Complete JSON Referenceis a valuable resource for understanding the YAML-based information structures used in this document. All JSON properties and objects defined in the reference equate to a YAML mapping, list, or dictionary. -

      -
      -
      - Reading YAML Examples -

      YAML is a particularly human-readable format. For those unfamiliar with the format, the basics:

      -
        -
      • -

        Each line is a key-value pair, presented as - key:value, or as - key:with any number of list items on the following lines. -

        -
        • -
      • -

        Indentation, spacing, and white space matters. Items below a key and indented one level in are members (or children) of that key.

        -
        • -
      • -

        List items are represented with a preceding dash - - listitemkey:value. -

        -
        • -
      -

      The YAML specification is freely available here: - YAML 1.2. -

      -

      Additionally, in order to unambiguously express information, this specification uses additional conventions, as described below.

      -

      There are some objects whose values must be determined dynamically at processing time. The most common example of this is timestamping output as it is processed. In this case, and any other dynamic-value cases, the expression - ${{ }}is used. -

      -

      For example:

      - last-modified: ${{ timestamp }} -

      Indicates the - last-modifiedobject should be produced with contents generated appropriately, in this case, the timestamp at the time of processing. -

      -

      Some examples may elide content to enhance readability or save space. In these cases, a YAML comment (any line that starts with - #) will be used to explain the elision. -

      -

      Finally, although examples are syntactically faithful to OSCAL, they are not necessarily always formally valid in every respect. For example, OSCAL defines allowed property names ( - props) and values, and those rules may not be observed here. Examples are given for purposes of illustrating profile resolution semantics only, and should not be taken as normative for any actual use. -

      -
      -
      - Document Layout -

      The specification is broken into the following major sections:

      -
        -
      • -

        - Phases of Profile Resolution- Lays out the necessary steps and phases of profile resolution. As each phase executes, the processor is understood to be creating and editing an intermediate representation of the output. There is one section for each of the three main phases. -

        -
        • -
      • -

        - Target Catalog Structure- Provides the requirements for structuring the final output from the intermediate representation generated throughout the previous section. -

        -
        • -
      -

      - Please note: As referenced in the Purpose section - , this specification makes no hard requirements on the specifics of implementation. It is feasible for an implementation to use no intermediate representation, and to directly and iteratively build the output. As long as all processing and output requirements are satisfied, any approach is allowed. With that said, the specification has been laid out to aid in implementation by providing a clear organization as a sequence of distinct operations. -

      -
      -
      - The Intermediate and Implementation Guidance -

      The overall intent of this document, in addition to defining strict requirements, is to provide rough guidelines on implementing an OSCAL Profile Resolution Tool. To this end, each phase of resolution will be framed as a series of transformations applied to an internal data structure that is persistent throughout the process. We call this "the intermediate".

      -

      Any examples that are labelled as "Intermediate" are pseudo-code, designed to represent how this data structure might look as we apply different operations to it. The example intermediates are often not valid OSCAL, and are not to be taken as guidance, but rather a useful visualization tool for implementers.

      -

      The authors believe that applying the steps of resolution in order against this intermediate representation is the simplest way to achieve full compliance with the specification. However, there is no requirement to implement profile resolution in this way. Requirements are given as rules on the output of resolution, and as such, tools can operate any way they would like internally.

      -
      -
      -
      - Phases of Profile Processing -

      An OSCAL Profile has three major sections, each which correspond to a phase of profile resolution. In order to complete the profile resolution process, each section must be fully parsed and a catalog output created.

      -

      It is strongly RECOMMENDED that implementations execute the following steps in the order that they are provided here (import, merge, modify). While it is possible to achieve compliance with a non-standard approach, the iterative nature of profile resolution lends itself to linear processing.

      -

      The three steps are - import; - merge; and - modify. In brief: -

      -
        -
      • -

        - import- identifies one or more control sources (catalogs or profiles) and defines the controls within them to be included in the result catalog. If nothing is imported, no resulting catalog is produced. Invoked by - importdirectives in source profiles; -

        -
        • -
      • -

        - merge- designates the rules for how controls will be organized (ordered and/or grouped) and merged (addressing conflicts or ambiguities) in the result catalog. Controlled by the - mergedirective in source profiles; if none are included, default merge rules are used; -

        -
        • -
      • -

        - modify- indicates how controls and their parameters in the underlying catalog are to be altered, edited, amended or added in the final result catalog. Logical evaluation and parameter constraints provide advanced processing. Controlled by the - modifydirective in source profiles. If a - modifydirective is not provided, no changes will be made to the controls that have been imported/merged. -

        -
        • -
      -

      As described in the previous section, when resolved, an OSCAL Profile takes the form of an OSCAL Catalog. The phases described below will produce outputs conforming to the catalog model.

      -
      -
      - Import Phase -

      A profile begins by listing a set of catalogs and/or profiles to be imported. Each is represented by a resolvable resource URI and a directive specifying which controls to import from that resource. These resources may be available as static resources, or they may be produced dynamically on request; such as is the case when a profile is imported. Imports are given in sequence after the metadata:

      - - - -

      In an import directive, the reference to the resource to be imported appears on an - hrefchild object. It takes either of two forms, external or internal: -

      -

      An external reference appears as an absolute or relative URL:

      - - - - https://github.com/usnistgov/oscal-content/tree - /master/nist.gov/SP800-53/rev4/yaml/NIST_SP-800-53_rev4_catalog.yaml - include-controls: ${{ list of selected controls }} - - href: "../../NIST_SP-800-53_rev5_catalog.yaml" - include-controls: ${{ list of selected controls }} ]]> - -

      While an internal reference appears as below (see - ): -

      - - - -

      All import directives will contain either - include-all: ~or - include-controls. These directives indicate which controls from the imported document are explicitly selected - . -

      -

      The following section contains requirements for processing the - import child of a source - profile -

      -
      - Import href Requirements -
      - Import URI Resolution -

      Tools MUST resolve URIs by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be resolved as defined in - . -

      -
      -
      - Import Resource Acquisition -

      Tools MUST acquire resources at the resolved URI by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be acquired as defined in - . -

      -

      For the purposes of resolving URIs using the above specification, the Base URI MUST be considered to be the absolute URI of the containing profile.

      -

      In the case that acquiring a resource fails, the tool MUST cease processing and provide an error. In order to ensure profile resolution results in the same catalog regardless of which tool resolves it, all imports must successfully resolve. While this may cause inconvenience if resources are frequently not available, it ensures interoperability.

      -

      Note that receiving a cached version of an import, or resolving an import that is otherwise unavailable through some other (but automatic) means still satisfies the above requirement. This specification does not put requirements on the precise function of the import, as long as the correct document is retrieved.

      -
      -
      - Internal References -

      URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of #{{objectID}}. For example, the URI Fragment #param1 is referencing the Parameter with unique ID param1.

      -

      In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the resources section of the source. When tools encounter such a reference, they MUST locate the object in resources with the matching UUID value, and resolve the resource. - By OSCAL model requirements, a given resource can have zero to many rlink objects and zero to one base64 objects; however, it must have at least one of the two present. Tools can assume that any of these each resolves to the same underlying OSCAL object, although potentially in different serialization formats. - For deterministic resolution of these backmatter OSCAL objects, tools need to adhere to the following requirements: -

      -
        -

      • Tools MAY use any of the rlink or base64 objects present in the resource.

        • -

      • Tools MAY verify that each above objects resolves to the same underlying OSCAL object. If there are OSCAL Model content differences between the resolved objects, the tool SHOULD provide a warning.

        • -

      • When a rlink is encountered and is to be resolved, it MUST be resolved by using a HTTP request to retrieve a byte stream.

        • -

      • When a base64 is encountered and is to be resolved, it MUST be considered a Byte Stream.

        • -

      • Regardless of its source, the Byte Stream MUST be decoded based on the algorithm defined in Section 4 RFC 4648.

        • -
      - - - -

      If the object fetched cannot be found or is not a valid OSCAL object, the tool MUST cease processing and provide an error.

      - - - - https://github.com/usnistgov/oscal-content/tree - /master/nist.gov/SP800-53/rev4/xml/NIST_SP-800-53_rev5_catalog.xml ]]> - -
      -
      - Resolving Imports of Profiles -

      If the resource acquired is an OSCAL Profile, the tool MUST apply this specification to resolve it, then continue processing having imported the resulting catalog.

      -

      When a profile imports a profile, the subordinate profile SHOULD be resolved first into a catalog using this specification, before it is imported. This presents the possibility of circular imports, when a profile is directed to import itself either directly or indirectly.

      -

      A - circular import occurs when a profile imports an already imported profile, which was called at an earlier place in the import hierarchy. For example, if profile A imports profile B, and profile B imports profile A, the second import is circular. (An import at the top can only be circular if a profile tries to import itself.) If A imports B, B imports C and C imports A, C’s import is circular. -

      -

      Note that an import can only be circular within the context of processing a particular profile. In the last example, C’s import would not be circular if invoked in the context of resolving B by itself.

      -

      If a processor encounters a - circular import as described above (self-imports are inherently circular), the processor MUST cease processing and generate an error. -

      - -

      A profile identified as - home_profile.yamlimports another one identified as - circular_profile.yaml: -

      - - - -

      In turn this file invokes - home_profile.xml: -

      - - - -

      Once detected, this circular import will result in an error and no further processing will take place.

      - - - -       -
      -
      - Multiple imports -

      Each import directive is processed to produce a set of controls. Note that this occurs even if the same catalog is imported multiple times: each distinct import collects controls into a separate - selection: -

      - - - - - - -

      The control inclusions are combined and collapsed in the next phase of processing, - merge(see ) . -

      -

      Multiple imports against the same resource are allowed, and would most commonly occur when the profile author is using to create very specific output. - Multiple imports may result in outputs with clashing control IDs if mapping or the merge directive is not set correctly.

      -
      -
      - Mapping Controls -

      The optional - mapping child of a given - import provides a simple ID remapping for objects included from that specific import. This provides the means for profile authors to proactively avoid clashing IDs of controls and other objects. -

      -

      The Mapping section consists of 5 optional subsections, each covering a particular type of object. Each subsection is a list of ID mappings to be applied for objects that are the parent object type.

      -

      When encountering a given mapping instruction, processors:

      -
        -
      • -

        MUST change the distinctive ID of that object to be equal to the value of the - to object. -

        -
        • -
      • -

        MUST update all known references to the old ID in other included content, allowing the new ID to be used in subsequent profile sections.

        -
        • -
      -

      Since mapping is a self contained process inside each import, the rest of this specification will continue to reference IDs with the assumption that mapping has already been applied if it was present. Since mapping is most commonly used to avoid clashing IDs, processors should take care to not handle duplicate IDs until after mapping is complete.

      -

      Below is a simple example of mapping. The second - import included controls from a different catalog whose ID values happen to collide. Knowing this, the profile author has remapped those IDs to new values. -

      - - - -

      Using the intermediate approach, an internal data structure resembling the following would result from the above profile:

      - - - -
      -
      -
      - Including Controls -

      Each import contains directives on which controls from the imported catalog are to be fetched and used for further processing. Throughout the rest of the document we will refer to this as "inclusion". - If a control is included, and the source profile makes no other changes to it, it will be present in the output. Exclusion directives in this section, as well as directives in the following two major sections (merge and modify), - may make changes to an included control or group that could cause it to appear differently, or not at all, in the output. Using the intermediate implementation approach, any control(s) that are included would be extracted from the referenced catalogs, any applicable mappings would be applied, then the controls(s) would be stored.

      -
      - include-all -

      When an import provides the - include-all directive, ALL controls and groups in the referenced document (including nested controls) MUST be included. -

      - include-all: ~ -
      -
      - include-controls plus with-id -

      When an import provides the - include-controls directive, with a - with-id child, all controls in the referenced document whose - id match one of the listed - id values MUST be included. -

      - - - -
      -
      - include-controls plus matching -

      Controls may also be included using match patterns against their IDs. This is useful because related controls (either in a hierarchy, or together in a group) frequently have related IDs as well.

      -

      When an import provides the - include-controls directive, with a - matching child, all controls in the referenced document whose - id matches one of the listed - pattern values (Glob matching) MUST be included. -

      -

      If a - matching object is provided with no - pattern, it MUST be treated as matching nothing. While not providing a pattern is technically valid, resolution tool implementers should be aware that it is generally undesirable, and warnings or notices to the user may be appropriate. -

      - - - -
      -
      - Dealing with Nested Controls and Groups -

      In OSCAL, controls may contain child controls. For instance, in SP 800-53 many controls are supplemented with control enhancements; in OSCAL these are represented as child controls within parent controls. So parent AC-2 (in a given catalog) has children AC-2(1) through AC-2(13), for example.

      -

      By default, inclusion of a control also causes any of that control's ancestors (or parents) to also be included. By default, inclusion of a control DOES NOT cause the inclusion of any descendants (or children) of that control to be included. This applies to both controls and groups.

      -

      This default behavior can be modified by the following two optional children of the - include-controls object. -

      -
      - with-child-controls -

      Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the with-child-controls option. with-child-controls appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.

      -

      A - with-child-controls: yes directive on an - include-controls indicates that - all descendant controls of the included control MUST also be included. -

      -

      A - with-child-controls: no directive on an - include-controls indicates that ONLY the matching control is included, any descendant children MUST NOT be included. -

      -

      If no - with-child-controls is provided, the processor MUST consider the directive as being equivalent to one having - with-child-controls:no. -

      -
      -
      - with-parent-controls -

      Although similar to the above - with-child-controls, the optional - with-parent-controls applies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they should use an exclude directive that lists all of the undesired parents. As a shortcut for this, - with-parent-controls provides the following functionality: -

      -

      A - with-parent-controls: yes directive on an - include-controls indicates that - all parent controls of the included control MUST also be included. -

      -

      A - with-parent-controls: no directive on an - include-controls indicates that ONLY the matching control is included, any parent MUST NOT be included. -

      -

      If no - with-parent-controls is provided, the processor MUST consider the directive as being equivalent to one having - with-parent-controls:yes. -

      -
      -
      -
      - exclude-controls -

      Exclusions work the same way as inclusions, except with the opposite effect - the indicated control(s) do not appear in the target catalog.

      -

      Any control designated to be both included and excluded, MUST be excluded. This holds irrespective of the specificity of the selection for inclusion or exclusion. For example, if AC-1 is included by id - ac-1 and excluded by matching - ac.*, it is excluded. -

      -

      When - exclude-controls has at least one - with-ids or - matching directive, the processor MUST follow the same rules as defined in the relevant sections above for these directives, but exclude instead of include any controls. All optional features (with-child-controls, etc.) also apply to exclusion directives. -

      -
      -
      - Redundant Inclusions and Exclusions -

      A given - import may have any number of inclusion statements and any number of exclusion statements. Their effect is cumulative; any control that is included (or excluded) more than once MUST be considered to be included (or excluded) only once. In other words, a given control being included or excluded more than once has no effect. Exclusion still takes priority over inclusion (see above). -

      -

      Note that this requirement only applies to controls included within the context of a single import. Controls with duplicate IDs included under a different - import are not discarded. Also note that this redundancy pruning happens after any relevant mappings have been applied. -

      -
      -
      - Handling Params -

      Any - paramthat is not directly under a control is referred to as a - looseparam. -

      -

      All loose params from both imported documents and the profile source MUST be included. These params will be kept in the final output if the document contains any references to them, and discarded otherwise. See - . Since new references can be created during the - modify phase, tools should be careful not to prune params without fully understanding the final state of the output document. -

      -
      -
      - Handling Groups -

      Some source catalogs use - group objects to place controls into arbitrary groupings. Tools will need to be aware of these groups when executing the "merge" phase below, as they will duplicated into the output under the "as-is" mode and can be referenced in "custom" mode. The naïve intermediate approach would keep all groups until all other phases are complete, but implementations may find it more performant to look ahead and prune unused groups early. -

      -

      Group objects that have a child prop object with name:keep and value:always MUST NOT be pruned (see . Additional details on handling the final outputting of these groups can be found in the "merge" phase below.

      -
      -
      - Avoiding Implementation Pitfalls -

      In order to ensure that implementers have as much flexibility as possible, requirements in this section have purposefully been kept minimal. Below are some common issues for implementers to be aware of:

      -
        -

      • The ordering and hierarchical organization of included controls as they were present in the original catalog may be used later in the resolution process. - Specifically, if the profile is using the "as-is" structuring directive, the ordering and organziation of the output should match the source catalog as closely as possible. - Implementations may want to track this information, or look ahead to see what structuring mode is being used. Note that "as-is" also requires implementations to replicate any use of the group element.

        -
        • -
      -
      -
      -
      - Wrapping up the Import Phase -

      At this point all requirements for content importing and control inclusion have been covered. If using the intermediate approach, the processor should have an intermediate that contains: a set of included controls and all of their child informational (non-control, non-group) objects, any relevant - group objects and their informational content, and a set of included "loose params" - (zero to many). The general structure of the intermediate would match that of the imported catalogs (i.e. nested controls remain nested, grouped controls remain grouped). -

      -
      -
      -
      - Merge Phase -

      Profiles may contain a - mergesection, where directives are given to instruct the processor how to combine the set of included objects collected during the Import Phase. - mergehas two parts: a "combine" directive, and a "structuring" directive. -

      -

      It is RECOMMENDED that tools apply the "combine" directive to the intermediate generated by the Import phase first, then apply the "structuring" directive.

      -

      The following section contains requirements for processing the - merge child of a source profile. -

      -
      - The "combine" Directive -

      - combineis an optional child of - mergethat provides the rules for dealing with objects that have duplicate (or clashing) distinct IDs - . -

      -

      There are two valid combination methods provided by OSCAL, provided by the - methodchild of - combine: -

      -
        -
      • -

        use-first: Use the first definition - the first control with a given ID is used; subsequent ones are discarded

        -
        • -
      • -

        keep: Keep - controls with the same ID are kept, retaining the clash

        -
        • -
      -

      Note that "merge: combine" is deprecated, and MUST be considered undefined behavior when encountered.

      -

      In order to apply the combination method, IDs of each control explicitly included are compared against one another. As IDs are unique across entire OSCAL documents, different imports or any groupings have no bearing on collision. Processing requirements for each method are described below.

      -
      - No Combine Directive -

      If no - merge directive is given in the profile, or if a - merge is given without a - combine, merge conflicts MUST be treated as if - method: keep was given. For example, a profile with no - merge directive: -

      - - - -

      is the same as

      - - - -
      -
      - - method:keep - -

      When a merge is indicated by - method:keep, or when no merge directive is given, the - keepcombination rule is used. Any control with the same distinctive ID - MUST NOT not merged. (They are kept.) -

      - - - -

      Under this directive, colliding controls will result in invalid results, as they will both appear in the results with the same ID. Accordingly, this setting may be useful in ensuring integrity of references to controls as given in the profile: if any included control is called only once, clashing controls will not be produced and validation will succeed.

      - - - -

      In the intermediate (showing control inclusions):

      - - - -

      In this case, downstream errors should be expected: the two - ac-1 controls clash with each other, as do the two - ac-2 controls. -

      -

      Processors SHOULD provide a warning under the merge:keep directive when duplicate controls are detected. The processor MAY throw an error and cease processing (short-circuiting a certain future error) when duplicate controls are detected under the merge:keep directive.

      -
      -
      - - method:use-first - - - - -

      When the - "use-first"combination rule is applied, and controls that share a distinctive ID are found, the first control encountered MUST be kept, the rest MUST be discarded. - "First" MUST be determined by a top-down, depth-first traversal of the source profile's import hierarchy. -

      - - - - -

      In the intermediate(showing control inclusions):

      - - - -       -
      -
      - - method:merge - -

      Deprecated, unspecified behavior.

      -
      -
      -
      - The "structuring" Directive -

      This section describes how a profile may dictate the structure of the target - catalog, apart from its - metadata or - back-matter. Optionally, one of three "structuring" directives can be included as a child of - merge: - flat, - as-isand - custom. When one of these appears, it is the selected structuring directive. If more than one appears, processors MUST generate an error and cease processing. Processing requirements for each are given below: -

      -
      - No Structuring Directive -

      If no - merge directive is given in the profile, or if a - merge is given without a structuring directive, structuring the output MUST be treated as if the structuring directive - flat was given. For example, a profile with no - merge directive: -

      - - - -

      is the same as

      - - - -
      -
      - "flat" -

      Profiles with the "flat" merge directive MUST be resolved as unstructured catalogs, with no grouping or nesting of controls.

      -

      Unstructured catalog output MUST be produced by adhering to the following requirements:

      -
        -
      • -

        All included controls are output to the target as a flat list directly under "catalog".

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under "catalog".

        -
        • -

      • Any groups are discarded.

        • -
      -

      An example of flat structuring is provided below

      - - - - - - - - - -
      -
      - - as-is - -

      An - as-is directive is used to reproduce the structure of the source documents in the target catalog. -

      -

      Processors MUST handle the - as-is directive by adhering to the following requirements: -

      -
        -
      • -

        All included controls are output to the target, keeping the structure of the groups and nested controls. Any group that holds an included control MUST appear in the output with all of its non-control children intact. - If an included control has a parent control that was not included, that control's output location is "up-leveled", or made equal to the non-included parent. This applies recursively until the control is directly under either "catalog" or another included control.

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under "catalog".

        -
        • -
      -

      Example:

      - - - - - - - - - -
      -
      - - custom - -

      The - customdirective provides the target catalog with a custom structure. A one-to-one mapping of the desired structure of the target catalog is defined alongside control matching instructions, resulting in a strictly controlled output catalog. -

      -
      - Creating Custom Groups -

      A - groupobject given under - custom MUST result in a - group with the exact same content (excluding - insert-controls) in the target catalog. -

      -

      If the ID of the group matches the ID of a group that has been included during the import phase, all contents inside the group, including - title, - param, - prop and - part objects MUST be copied into the target, appearing in the same order as in the source. -

      -

      Note that groups defined in - custom may vary from fully featured to minimally instantiated. This includes arbitrary nesting of such groups inside of one another. No groups other than those explicitly declared should appear in the output catalog. -

      -
      -
      - Inserting Controls -

      The - insert-controls directive may appear anywhere under - custom, whether as a direct child or inside any of the defined groups. Inside insert-controls, - include-controls and - include-all from the Import Phase - are used with the same basic behavior to configure which controls are selected and inserted at the current location. -

      -

      In order to provide clarity, controls that match the various conditions of these inclusion directives inside the - custom object will be referred to as "selected" instead of "included". Only directly selected controls will appear in the target catalog. -

      -

      When processing the control selection of a custom element, the behavior defined in this section MUST be followed to generate the output.

      -

      A - insert-controls with an - include-controls child results in the following behavior: -

      -
        -
      • -

        - with-idresults in selecting and inserting, at that point inside the new grouping, the included controls with the - idgiven by - with-id. They should be given in the same order as they appear in the control selection(s). -

        -
        • -
      • -

        A - matchingdirective results in selecting and inserting, at that point inside the new grouping, all included controls whose - idmatch, as a Glob expression, the pattern given in the - pattern. They are given in the same order as they appear in the input control selection(s). -

        -
        • -
      -

      An - insert-controls with an - include-all child results in all included controls being selected and inserted. They are given in the same order as they appeared in the input control selection(s). -

      -

      - insert-controls can also indicate the order that the selected controls are to be emitted in the result catalog using an - order child. Three values MUST be supported and handled as specified below: -

      -
        -
      • -

        - ascendingwill sort all selected controls into ascending alphanumeric order by their ID. -

        -
        • -
      • -

        - descendingwill sort all selected controls into descending alphanumeric order by their ID. -

        -
        • -
      • -

        - keepindicates that controls should be inserted in the order of their appearance, using a depth-first traversal of the source profile's imports. -

        -
        • -
      -

      In the case that a control selection matches none of the included controls, it MUST be ignored. In the case that a control selection matches none of the included controls, a warning SHOULD be provided. If a control that was included by the Import Phase is never selected, no error occurs. That control simply does not appear in the output catalog.

      -
      -
      -
      -
      - Wrapping up the Merge Phase -

      After the merge phase, the intermediate should now closely resemble the content and structure of the final output catalog. Controls and groups have been included, remapped, de-duplicated, then placed into their final location within the output's structure. Note: there is still an opportunity for included controls or groups to become referenced; and therefore, not eligible for pruning - in the next phase. -

      -

      Regardless of any merge directives, there also likely remains "loose params" that have been propagated forward; these too must be persisted.

      -
      -
      -
      - Modify Phase -

      There are two ways profiles may further modify the results of profile resolution: setting parameters and altering controls. These activities are defined as two child objects inside the third step of profile resolution, the Modify Phase.

      -

      The following section contains requirements for processing the - modify child of a source profile. -

      -
      - Setting Parameters -

      Modification of parameter settings is indicated using the - set-parameter object under - modify. For this section, a given - set-parameter object will be referred to as the - source. -

      -

      Profile Resolution Tools MUST adhere to the following requirements for processing "set-parameter":

      -
        -
      • -

        First, the list of included params (among "loose params" and remaining included controls and groups) is searched for a param who has an "id" equal to this object's "param-id". This is the "target". If no such parameter is found, a warning SHOULD be issued. If no such parameter is found, processing MUST still continue.

        -
        • -
      • -

        For the following objects inside the source: class, depends-on, label, usage, values, select; the object MUST be copied into the target from the source, first removing any existing objects with the same name.

        -
        • -
      • -

        For the following objects inside the source: props, links, constraints, guidelines; the contents of the object MUST be added to the contents of the target object of the same name. If no such object exists in the target, it is created.

        -
        • -

      • For the following objects inside the source: prop, link; the object MUST be copied into the target from the source, first removing any existing objects with the same distinctive ID. ().

        • -
      • -

        If more than one - set-parameter directive is given for the same parameter, all MUST BE applied, in the sequence given in the profile. -

        -
        • -
      -
      -
      - Altering controls -

      A control can be altered by an - alterobject inside "modify". The - control-idchild object under the - alterindicates the control to which the alteration is applied. -

      -
      - Adding contents to controls -

      Contents may be added to controls using an add directive inside an alter directive. There are two forms of alteration: with implicit and explicit bindings.

      -
      - Implicit binding -

      An - add directive with no - by-id child MUST be considered an implicit binding, and will apply to the control as a whole. -

      -

      The contents of an implicitly bound add directive MUST be added to the control contents in the target, either after its - title when - position is - starting, or at the end if its position is - ending, or if no valid position is given. -

      -

      When an add directive is implicitly bound, the - position values - before and - after MUST be treated like - starting and - ending, respectively. -

      -

      Control contents in catalogs must appear in the order - title, param, prop, link, part, control per the OSCAL model documentation. After processing an implicitly bound add directive, the control contents MUST be sorted to appear in the required order: a new - prop appears after any - prop already in the control, when - position is - ending, or not given, or before any - prop in the control when - position is - starting. -

      - - -

      An addition operating on a control with implicit binding and position - starting -

      - - - - - - - - - -

      Position is - startingbut the new - partis added after the existing - prop, because - propobjects must always occur first. -

      -       - -

      An addition operating on a control with implicit binding and position - ending -

      - - - - - - - - - -

      The - positionis - endingso the new - propappears after the existing - prop. -

      -       -
      -
      - Explicit binding -

      An explicit binding on an addition permits inserting new contents anywhere in a control, not only at the top level. An - add directive with a - by-id child MUST be considered an explicit binding, and applies to only a single object inside the control. When an add directive is explicitly bound, the value of the - by-id child MUST correspond to the value of an - id on an object inside the control, and not the control itself. If - by-id does not correspond to such a value, the - add directive MUST be considered inoperative and ignored. An inoperative add directive MAY result in a warning. -

      -

      The object with - id equal to the value of - by-id is considered the - target of the addition. -

      -

      When - position has a value of - startingor - ending, the contents of the source MUST be added inside the target, either at the start or end of its contents, respectively. -

      -

      When - position has a value of - before or after, the contents of the source MUST be added outside the target, either directly before or after it, respectively. -

      - -

      An addition operating on a control with explicit binding and position - after -

      - - - -

      Note that the - adddirective identifies the object with - id - a1.b1as its target. -

      - - - - - - -

      The - positionis - afterso both objects inside - addare added after (not inside) the target object. Since the target object is inside another - partin the control, the new additions appear there as well. -

      -

      Note that the result in this case will be schema-invalid since a - propmay not occur directly following a - part. A better result can be obtained (a better target may be defined) by using two - adddirectives, to insert the new - propseparately before any - partobjects in the target. -

      -       -
      -
      - Modifying controls inside controls - -

      OSCAL supports controls inside controls in the form of - control objects inside - control objects. Because the semantics of the - add and remove directives target any (object) contents of controls, they can be used to target these child controls for modification as well as other contents. Profile resolution tools MUST be able to correctly handle add directives targetting nested controls. This includes directives that target a child control as well as directives that target a parent control and modify the child.

      -
      -
      -
      - Removing contents from controls -

      Contents inside controls can be removed from them in catalog targets. In combination with adding new contents, this feature can be used to edit controls as well as amend them.

      -

      A - removedirective inside an - alter directive identifies an object or set of objects inside a control to be removed. It does this using any of five child objects. -

      -

      An object inside the control MUST be removed from the output if and only if it meets all of the criteria given by the child objects of the remove directive. When more than one child appears under the remove directive, an object would need to match all of them, otherwise it is not removed.

      -
        -
      • -

        - The remove directive criteria by-id MUST match an object if and only if its value is identical to the id value of that object. Because - id values are unique, this criteria will result in the remove directive removing only a single object. -

        -
        • -
      • -

        - The remove directive criteria name-ref MUST match an object if and only if its value is identical to the value of that object's name child. -

        -
        • -
      • -

        The remove directive criteria ns-ref MUST match an object if and only if its value is identical to the value of that object's ns child.

        -
        • -
      • -

        The remove directive criteria class-ref MUST match an object if and only if its value is identical to the value of that object's class child.

        -
        • -
      • -

        The remove directive criteria item-name MUST match an object if and only if its value is identical to the value of that object's serialized name. For example, - remove:item-name:prop has the effect of removing all - propobjects from inside the control. -

        -

        In serialization formats that use arrays of objects in the OSCAL model, an object's name MUST be referenced as singular form of its containing parent array. For example, in the JSON format, remove:item-name:link would remove all of the objects inside of the links array.

        -
        • -
      -
      -
      -
      -
      - Final Operations -
      - Backmatter Resolution -

      - back-matter in the result is produced by combining all objects within - back-matter in all source catalogs, with the - back-matter in the input profile. -

      -
        -

      • The output's backmatter MUST be generated by copying in each resource object from the backmatters of the imported catalogs/profiles in top-to-bottom order, then by copying in each resource object from the backmatter of the source profile itself. These objects MUST be processed in the order they are defined in each respective document.

        • -
      • -

        If a given - resource has the same - uuid as a resource that has already been added, the previous resource MUST be removed, and the more recent one added, unless superseded by other requirements. -

        -
        • -
      • -

        A resource with a child prop of name:keep and value:always MUST NOT be replaced by the addition of another resource, unless the new resource also has a child prop of name:keep and value:always.

        -
        • -
      -

      Tools MAY check for pruning conditions - as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition. -

      -

      Placing the keep always prop on a resource in a catalog has the effect of ensuring it will always appear in the output produced by any profile importing that catalog, even if nothing links to the resource. This version of the resource will also be the one copied, unless a later-imported catalog or importing profile offers its own version marked to keep always.

      -
      -
      - Metadata Resolution -

      The following requirements MUST be followed with regards to the Metadata section of the output catalog:

      -
        -
      • -

        The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid). This UUID MAY be generated as seen fit by the tool, as long as it is reasonable to assume it is globally unique. It is RECOMMENDED that tools use a Version 4 UUID as specified in Section 4 of RFC 4122. -

        -
        • -
      • -

        The value of metadata:version in the target MUST be set with a string that identifies the version of that document. The metadata:version SHOULD be used to track updates to this specific output document.

        -
        • -
      • -

        The value of metadata:oscal-version in the target MUST be set with a string that identifies the version of OSCAL used by this tool to resolve the profile (ex. 1.0.0). This value MUST be determined by compiling the oscal-versions from each imported document and the source profile, and taking the most recent minor version. If this version is more recent than what the resolution tool is using, then the value of oscal-version MUST be the version that the tool used internally. If any of the above OSCAL versions (imported document versions, source profile version, tool version) are of a different major version (the first digit differs), the tool SHOULD provide an error and cease processing.

        -
        • -
      • -

        The value of metadata:last-modified in the target MUST be set with a valid timestamp representing the time the profile resolution completed.

        -
        • -
      • -

        A child prop object with name:source-profile MUST be created. The value object of this prop SHOULD be set with a valid URI that points to the profile that resulted in this catalog. - If there are privacy or security concerns, the value object of this prop MAY be set to anything, in which case the simple existence of the source-profile property indicates that this is a resolved profile.

        -
        • -
      • -

        A child prop object with name:resolution-tool SHOULD be created. The value object of this prop in the target SHOULD be set with a string that represents the tool that was used to resolve this catalog.

        -
        • -

      • For any metadata:roles or metadata:parties that exist in the source catalogs, if they have a prop child with name:keep and value:always, they are to be copied as is into the output metadata.

        • -
      -

      Beyond these requirements, tools are free to use any and all of the objects inside metadata to provide additional information downstream.

      -

      Because of options in producing metadata and especially the requirement for a timestamp, developers and users should note that two different resolutions of the same profile will not, ordinarily, be identical inside - metadata. -

      -
      -
      - Pruning and Ordering -

      The processor SHOULD prune the resulting output catalog by removing unused objects.

      -
        -
      • -

        Any object that has a child prop with a name of "keep" and a value of "always" MUST NOT be pruned.

        -
        • -
      • -

        If an object was explicitly included in the - , it MUST NOT be pruned. -

        -
        • -
      • -

        If an object was referenced in a custom section of the source profile, it MUST NOT be pruned.

        -
        • -
      • -

        If an object was referenced in the modify section of the source profile, it MUST NOT be pruned. Any objects removed in that section are still removed.

        -
        • -
      • -

        If the object appears in a reference anywhere in the final result catalog, except in other objects that also meet all other pruning criteria, it MUST NOT be removed. A reference to a given object exists if #{distinctiveID} appears anywhere, where {distinctiveID} is the distinctive ID of the object - . -

        -
        • -
      -

      Implementers should note that pruning need not take place after all other steps. As long as all above criteria are respected, pruning can happen at any time, and doing so is a likely performance and memory overhead improvement.

      -

      Tools MUST reorder the output catalog into canonical order - , except where this specification provides different ordering requirements. -

      -
      -
      -
      - Items of Note -
      - Distinct ID of Objects -

      Whenever this specification refers to - "distinctiveness", it is to be interpreted as is defined in this section with regards to the object in question. -

      -

      For the objects control, param, and group, distinctiveness MUST be determined by the value of the - "id" child object. -

      -

      For the object resource, distinctiveness MUST be determined by the value of the - "uuid" - . -

      -
      -
      - Dealing with Multiple Formats -

      Profile Resolution tools SHOULD be able to handle source profiles, imported catalogs, and imported profiles that are serialized in XML, JSON, or YAML. A different serialization format of any given input MUST NOT result in a differing output catalog.

      -

      In order to help bootstrap this format management, the following resources are provided for implementers:

      -
        -
      • -

        . - -

        -
        • -
      -

      The following sections provide additional requirements and guidance for each format.

      -
      - Requirements and Guidance for XML Output -

      The final Catalog output, if using XML, MUST be valid as defined by the XML model documentation for the OSCAL Catalog. See - the complete XML reference for model requirements. -

      -
      -
      - Requirements and Guidance for JSON Output -

      The final Catalog output, if using JSON, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. See the - complete JSON reference for model requirements. -

      -

      The JSON format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, tools SHOULD adhere to the canonical OSCAL order - when outputting a catalog in JSON. -

      -
      -
      - Requirements and Guidance for YAML Output -

      The final Catalog output, if using YAML, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. YAML is considered a simple variation on the JSON format. Beyond cosmetic differences there are no differences in the information structure between these formats. Therefore, the - complete JSON reference provides model requirements. -

      -

      The YAML format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, tools SHOULD adhere to the canonical OSCAL order - when outputting a catalog in YAML. -

      -
      -
      - Order of objects in serialization -

      In OSCAL, order of top level objects (those that are direct children of the root element) is considered important only when the XML format is used. To facilitate this, OSCAL provides the concept of - canonical order. This order is provided by the OSCAL Metaschema files for a given document type (see - an overview of Metaschema. -

      -

      When the output format is XML, tools MUST use the OSCAL canonical order as described above. When using the YAML or JSON formats, order conveys no meaning, and is not considered important.

      -
      -
      - Comments in result documents -

      In an XML-based profile resolution, XML comments are one straightforward way for a processor to record events or conditions without affecting the output's nominal semantics. To support this, while two processors are obliged to return the same catalog XML for the same profile XML inputs, they are not required to match one another's comments, white space usage, attribute order, or processing instructions, only each other's objects, attributes and data content.

      -

      One consequence of this is that processes intended to compare two profile resolutions may have to accommodate differences in comments, considering them as insignificant along with other differences in serialization.

      -
      -
      -
      -       - diff --git a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml b/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml deleted file mode 100644 index 3ac7a77564..0000000000 --- a/src/specifications/profile-resolution/profile-resolution-specml-102plus.xml +++ /dev/null @@ -1,1602 +0,0 @@ - - - - - - - - - OSCAL Profile Resolution -
      - Notice of Draft Status -

      Please note that this specification is currently a work in progress and is subject to change. If you have any feedback or comments, please create an issue at the NIST OSCAL Github Repository: github.com/usnistgov/OSCAL.

      -
      -
      - Abstract -

      This specification provides the minimal requirements for processing an OSCAL Profile to create a new OSCAL Catalog Document. This process of applying a profile to a catalog to create a new catalog is called - Profile Resolution. Not all OSCAL Profiles will be resolved, nor are expected to be; however, the resolution requirements in this document are crucial to understanding the intended functionality of any given OSCAL Profile. - This specification is intended for software developers who intend to develop an OSCAL Profile Resolver, or for OSCAL Profile authors who want a more in-depth understanding of profile resolution. -

      -
      -
      - Introduction -
      - Purpose -

      - Information systems are implemented against a baseline of security controls. An OSCAL Profile defines the selection and potential alterations to a control catalog that are needed to establish a baseline. However, the OSCAL implementation layer depends on having an OSCAL Catalog that represents the baseline of controls to be implemented. Profile Resolution allows for computing an effective catalog based on an OSCAL Profile. For a given OSCAL Profile, the Profile Resolution process needs to result in the same OSCAL Catalog when executed by different tools on different endpoints. The requirements for resolution must therefore be well-defined and deterministic, enabling tool developers and parties exchanging OSCAL Profiles to work from a common understanding. This document defines the normative requirements for an OSCAL Profile Resolver. -

      - -

      No requirements are placed on implementation-level details, instead, requirements are laid out as what the output of resolution must look like given a certain input. - By adhering to these requirements OSCAL producers, OSCAL consumers, and any other members of the OSCAL ecosystem can create and resolve profiles deterministically, - with repeatable results, regardless of the tool used.

      -
      -
      -
      - Reading This Document -
      - - Terminology -

      Many core OSCAL concepts are defined on the OSCAL Terminology Page. The most important are repeated in this document, but readers should verify their understanding of all core OSCAL terms before reading this document.

      -

      Additionally, many terms in the wider domain have overloaded definitions. Unless defined otherwise by OSCAL or explicitly in this document, terms are to be understood as defined in the NIST CSRC Glossary.

      -
        -
      • -

        - profile- an OSCAL Profile Document. Defines a set of inclusions, modifications, and transformations against a - catalog. See - OSCAL Profile Model. -

        -
        • -
      • -

        - catalog- an OSCAL Catalog Document. Contains a well-defined set of - controls. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - control- an individual item in an OSCAL Catalog. See - NIST Special Publication 800-53r5for a more in-depth definition. -

        -
        • -
      • -

        - profile resolution- The process of consuming one or more OSCAL Profiles and the OSCAL Catalogs that they reference to produce a new tailored - catalog. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - source- refers to the profile document that is input into the profile resolution processor. This is the profile being resolved. In this document, when referring to objects from the - sourcedocument, the following style is used: - source-object. -

        -
        • -
      • -

        - target- the intended output of the transformation, a catalog document. In this document, when referring to objects of a - targetdocument, the following style is used: - target-object. -

        -
        • -
      • -

        - directive- refers to an object or combination of objects in source documents, which is designed to affect a particular outcome in the target catalog. For the most part, directives are in the source profile document – for example, a - set-parameterobject in a source profile is a directive to set a parameter value in the target catalog. -

        -
        • -
      • -

        - original order- the order of objects as presented in the - sourcedocument(s). See XYZ. -

        -
        • -
      • -

        - canonical order- the order of objects as required in the appropriate OSCAL Model (Profile, Catalog, etc.). This can differ from the above order when converting between "ordered" formats (ex. XML), and "non-ordered" formats (ex. JSON). -

        -
        • -
      -
      -
      - Requirement Keywords -

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in - BCP 14 - [RFC2119] - [RFC8174]when, and only when, they appear in all capitals, as shown here. -

      -
      -
      - Use of YAML -

      OSCAL supports a variety of serialization formats, each of which having it's own benefits and drawbacks. In this document, YAML (YAML Ain't Markup Language) is used to represent the various objects of the - sourceand - target. All examples and in-line references will be represented using - YAML 1.2. -

      -

      YAML maps cleanly to JSON, thus allowing easy use of existing JSON/XML transformers where needed. With that in mind, the - OSCAL Complete JSON Referenceis a valuable resource for understanding the YAML-based information structures used in this document. All JSON properties and objects defined in the reference equate to a YAML mapping, list, or dictionary. -

      -
      -
      - Reading YAML Examples -

      YAML is a particularly human-readable format. For those unfamiliar with the format, the basics:

      -
        -
      • -

        Each line is a key-value pair, presented as - key:value, or as - key:with any number of list items on the following lines. -

        -
        • -
      • -

        Indentation, spacing, and white space matters. Items below a key and indented one level in are members (or children) of that key.

        -
        • -
      • -

        List items are represented with a preceding dash - - listitemkey:value. -

        -
        • -
      -

      The YAML specification is freely available here: - YAML 1.2. -

      -

      Additionally, in order to unambiguously express information, this specification uses additional conventions, as described below.

      -

      There are some objects whose values must be determined dynamically at processing time. The most common example of this is timestamping output as it is processed. In this case, and any other dynamic-value cases, the expression - ${{ }}is used. -

      -

      For example:

      - last-modified: ${{ timestamp }} -

      Indicates the - last-modifiedobject should be produced with contents generated appropriately, in this case, the timestamp at the time of processing. -

      -

      Some examples may elide content to enhance readability or save space. In these cases, a YAML comment (any line that starts with - #) will be used to explain the elision. -

      -

      Finally, although examples are syntactically faithful to OSCAL, they are not necessarily always formally valid in every respect. For example, OSCAL defines allowed property names ( - props) and values, and those rules may not be observed here. Examples are given for purposes of illustrating profile resolution semantics only, and should not be taken as normative for any actual use. -

      -
      -
      - Document Layout -

      The specification is broken into the following major sections:

      -
        -
      • -

        - Phases of Profile Resolution- Lays out the necessary steps and phases of profile resolution. As each phase executes, the processor is understood to be creating and editing an intermediate representation of the output. There is one section for each of the three main phases. -

        -
        • -
      • -

        - Target Catalog Structure- Provides the requirements for structuring the final output from the intermediate representation generated throughout the previous section. -

        -
        • -
      -

      - Please note: As referenced in the Purpose section - , this specification makes no hard requirements on the specifics of implementation. It is feasible for an implementation to use no intermediate representation, and to directly and iteratively build the output. As long as all processing and output requirements are satisfied, any approach is allowed. With that said, the specification has been laid out to aid in implementation by providing a clear organization as a sequence of distinct operations. -

      -
      -
      - The Intermediate and Implementation Guidance -

      The overall intent of this document, in addition to defining strict requirements, is to provide rough guidelines on implementing an OSCAL Profile Resolution Tool. To this end, each phase of resolution will be framed as a series of transformations applied to an internal data structure that is persistent throughout the process. We call this "the intermediate".

      -

      Any examples that are labelled as "Intermediate" are pseudo-code, designed to represent how this data structure might look as we apply different operations to it. The example intermediates are often not valid OSCAL, and are not to be taken as guidance, but rather a useful visualization tool for implementers.

      -

      The authors believe that applying the steps of resolution in order against this intermediate representation is the simplest way to achieve full compliance with the specification. However, there is no requirement to implement profile resolution in this way. Requirements are given as rules on the output of resolution, and as such, tools can operate any way they would like internally.

      -
      -
      -
      - Phases of Profile Processing -

      An OSCAL Profile has three major sections, each which correspond to a phase of profile resolution. In order to complete the profile resolution process, each section must be fully parsed and a catalog output created.

      -

      PENDING test designIt is strongly RECOMMENDED - that implementations execute the following steps in the order that they are provided here - (import, merge, modify). While it is possible to achieve compliance with a - non-standard approach, the iterative nature of profile resolution lends itself to linear - processing.

      -

      The three steps are - import; - merge; and - modify. In brief: -

      -
        -
      • -

        - import- identifies one or more control sources (catalogs or profiles) and defines the controls within them to be included in the result catalog. If nothing is imported, no resulting catalog is produced. Invoked by - importdirectives in source profiles; -

        -
        • -
      • -

        - merge- designates the rules for how controls will be organized (ordered and/or grouped) and merged (addressing conflicts or ambiguities) in the result catalog. Controlled by the - mergedirective in source profiles; if none are included, default merge rules are used; -

        -
        • -
      • -

        - modify- indicates how controls and their parameters in the underlying catalog are to be altered, edited, amended or added in the final result catalog. Logical evaluation and parameter constraints provide advanced processing. Controlled by the - modifydirective in source profiles. If a - modifydirective is not provided, no changes will be made to the controls that have been imported/merged. -

        -
        • -
      -

      As described in the previous section, when resolved, an OSCAL Profile takes the form of an OSCAL Catalog. The phases described below will produce outputs conforming to the catalog model.

      -
      -
      - Import Phase -

      A profile begins by listing a set of catalogs and/or profiles to be imported. Each is represented by a resolvable resource URI and a directive specifying which controls to import from that resource. These resources may be available as static resources, or they may be produced dynamically on request; such as is the case when a profile is imported. Imports are given in sequence after the metadata:

      - - - -

      In an import directive, the reference to the resource to be imported appears on an - hrefchild object. It takes either of two forms, external or internal: -

      -

      An external reference appears as an absolute or relative URL:

      - - - - https://github.com/usnistgov/oscal-content/tree - /master/nist.gov/SP800-53/rev4/yaml/NIST_SP-800-53_rev4_catalog.yaml - include-controls: ${{ list of selected controls }} - - href: "../../NIST_SP-800-53_rev5_catalog.yaml" - include-controls: ${{ list of selected controls }} ]]> - -

      While an internal reference appears as below (see - ): -

      - - - -

      All import directives will contain either - include-all: ~or - include-controls. These directives indicate which controls from the imported document are explicitly selected - . -

      -

      The following section contains requirements for processing the - import child of a source - profile -

      -
      - Import href Requirements -
      - Import URI Resolution -

      relative URITools MUST resolve - URIs by following Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with - "#"). URI Fragments MUST instead be resolved as defined in . -

      -
      -
      - Import Resource Acquisition -

      via internal reference to - resource/rlinkTools MUST acquire resources at the resolved URI by following Section 5 of - RFC3986, with the exception of URI Fragments (URIs that start with "#"). - URI Fragments MUST instead be acquired as defined in . -

      -

      URI base corresponds to document URIFor the purposes of resolving URIs - using the above specification, the Base URI MUST be considered to be the absolute URI of - the containing profile.

      -

      PENDING rebase over latest from galtm missing resourceIn the case - that acquiring a resource fails, the tool MUST cease processing and provide an error. In - order to ensure profile resolution results in the same catalog regardless of which tool - resolves it, all imports must successfully resolve. While this may cause inconvenience - if resources are frequently not available, it ensures interoperability.

      -

      Note that receiving a cached version of an import, or resolving an import that is otherwise unavailable through some other (but automatic) means still satisfies the above requirement. This specification does not put requirements on the precise function of the import, as long as the correct document is retrieved.

      -
      -
      - Internal References -

      URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of #{{objectID}}. For example, the URI Fragment #param1 is referencing the Parameter with unique ID param1.

      -

      In the context of the Import Phase, - internal references will only appear as a reference to a profile or catalog that is in - the resources section of the source. When tools encounter such a reference, - they MUST locate the object in resources with the matching UUID value, and - resolve the resource. By OSCAL model requirements, a given resource can have - zero to many rlink objects and zero to one base64 objects; - however, it must have at least one of the two present. Tools can assume that any of - these each resolves to the same underlying OSCAL object, although potentially in - different serialization formats. For deterministic resolution of these backmatter OSCAL - objects, tools need to adhere to the following requirements:

      -
        -

      • PENDING test design (support for either/both base64 - and rlink)Tools MAY use any of the rlink or base64 - objects present in the resource.

        • -

      • PENDING test design (correspondence of base64 and - rlink-nominated objects)Tools MAY verify that each above objects resolves to - the same underlying OSCAL object. If there are OSCAL Model content differences - between the resolved objects, the tool SHOULD provide a warning.

        • -

      • PENDING test design (retrieval)When a - rlink is encountered and is to be resolved, it MUST be resolved by - using a HTTP request to retrieve a byte stream.

        • -

      • PENDING test design (base64 integrity)When - a base64 is encountered and is to be resolved, it MUST be considered a - Byte Stream. -

        • -

      • PENDING test design (base64 - integrity)Regardless of its source, the Byte Stream MUST be decoded based on - the algorithm defined in - Section 4 RFC 4648.

        • -
      - - - -

      PENDING rebase over latest from galtmPENDING rebase over latest from galtmIf the object fetched cannot be found - or is not a valid OSCAL object, the tool MUST cease processing and provide an - error.

      - - - - https://github.com/usnistgov/oscal-content/tree - /master/nist.gov/SP800-53/rev4/xml/NIST_SP-800-53_rev5_catalog.xml ]]> - -
      -
      - Resolving Imports of Profiles -

      PENDING chained profilesIf the resource acquired is an OSCAL Profile, the tool - MUST apply this specification to resolve it, then continue processing having imported - the resulting catalog.

      -

      PENDING chained profilesPENDING [bug repair] chained profile - merged with controls from its own source catalogWhen a profile imports a profile, - the subordinate profile SHOULD be resolved first into a catalog using this - specification, before it is imported. This presents the possibility of circular - imports, when a profile is directed to import itself either directly or indirectly.

      -

      A - circular import occurs when a profile imports an already imported profile, which was called at an earlier place in the import hierarchy. For example, if profile A imports profile B, and profile B imports profile A, the second import is circular. (An import at the top can only be circular if a profile tries to import itself.) If A imports B, B imports C and C imports A, C’s import is circular. -

      -

      Note that an import can only be circular within the context of processing a particular profile. In the last example, C’s import would not be circular if invoked in the context of resolving B by itself.

      -

      PENDING circular import detectionIf a processor encounters a circular - import as described above (self-imports are inherently circular), the processor - MUST cease processing and generate an error.

      - -

      A profile identified as home_profile.yamlimports another one identified as - circular_profile.yaml:

      - - - -

      In turn this file invokes home_profile.xml:

      - - - -

      Once detected, this circular import will result in an error and no further processing - will take place.

      - - - -       -
      -
      - Multiple imports -

      Each import directive is processed to produce a set of controls. PENDING - chained profilesNote that this occurs even if the same catalog is imported - multiple times: each distinct import collects controls into a separate - selection:

      - - - - - - -

      PENDING - chained profilesThe control inclusions are combined and collapsed in the next - phase of processing, merge(see ) .

      -

      Multiple imports against the same resource are allowed, and would most commonly occur when the profile author is using to create very specific output. - Multiple imports may result in outputs with clashing control IDs if mapping or the merge directive is not set correctly.

      -
      -
      - Mapping Controls -

      The optional - mapping child of a given - import provides a simple ID remapping for objects included from that specific import. This provides the means for profile authors to proactively avoid clashing IDs of controls and other objects. -

      -

      The Mapping section consists of 5 optional subsections, each covering a particular type of object. Each subsection is a list of ID mappings to be applied for objects that are the parent object type.

      -

      When encountering a given mapping instruction, processors:

      -
        -
      • -

        MUST change the distinctive ID of that object to be equal to the value of the - to object. -

        -
        • -
      • -

        MUST update all known references to the old ID in other included content, allowing the new ID to be used in subsequent profile sections.

        -
        • -
      -

      Since mapping is a self contained process inside each import, the rest of this specification will continue to reference IDs with the assumption that mapping has already been applied if it was present. Since mapping is most commonly used to avoid clashing IDs, processors should take care to not handle duplicate IDs until after mapping is complete.

      -

      Below is a simple example of mapping. The second - import included controls from a different catalog whose ID values happen to collide. Knowing this, the profile author has remapped those IDs to new values. -

      - - - -

      Using the intermediate approach, an internal data structure resembling the following would result from the above profile:

      - - - -
      -
      -
      - Including Controls -

      Each import contains directives on which controls from the imported catalog are to be fetched and used for further processing. Throughout the rest of the document we will refer to this as "inclusion". - If a control is included, and the source profile makes no other changes to it, it will be present in the output. Exclusion directives in this section, as well as directives in the following two major sections (merge and modify), - may make changes to an included control or group that could cause it to appear differently, or not at all, in the output. Using the intermediate implementation approach, any control(s) that are included would be extracted from the referenced catalogs, any applicable mappings would be applied, then the controls(s) would be stored.

      -
      - include-all -

      - When - an import provides the include-all directive, ALL controls and groups in the - referenced document (including nested controls) MUST be included.

      - include-all: ~ -
      -
      - include-controls plus with-id -

      When an import provides the - include-controls directive, with a with-id child, all controls - in the referenced document whose id match one of the listed id - values MUST be included.

      - - - -
      -
      - include-controls plus matching -

      Controls may also be included using match patterns against their IDs. This is useful because related controls (either in a hierarchy, or together in a group) frequently have related IDs as well.

      -

      When an import provides the - include-controls directive, with a - matching child, all controls in the referenced document whose - id matches one of the listed - pattern values (Glob matching) MUST be included. -

      -

      If a - matching object is provided with no - pattern, it MUST be treated as matching nothing. While not providing a pattern is technically valid, resolution tool implementers should be aware that it is generally undesirable, and warnings or notices to the user may be appropriate. -

      - - - -
      -
      - Dealing with Nested Controls and Groups -

      In OSCAL, controls may contain child controls. For instance, in SP 800-53 many controls are supplemented with control enhancements; in OSCAL these are represented as child controls within parent controls. So parent AC-2 (in a given catalog) has children AC-2(1) through AC-2(13), for example.

      -

      By default, inclusion of a control also causes any of that control's ancestors (or parents) to also be included. By default, inclusion of a control DOES NOT cause the inclusion of any descendants (or children) of that control to be included. This applies to both controls and groups.

      -

      This default behavior can be modified by the following two optional children of the - include-controls object. -

      -
      - with-child-controls -

      Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the with-child-controls option. with-child-controls appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.

      -

      A with-child-controls: - yes directive on an include-controls indicates that all - descendant controls of the included control MUST also be included.

      -

      A with-child-controls: - no directive on an include-controls indicates that ONLY the - matching control is included, any descendant children MUST NOT be included.

      -

      If no - with-child-controls is provided, the processor MUST consider the - directive as being equivalent to one having with-child-controls:no. -

      -
      -
      - with-parent-controls -

      Although similar to the above - with-child-controls, the optional - with-parent-controls applies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they should use an exclude directive that lists all of the undesired parents. As a shortcut for this, - with-parent-controls provides the following functionality: -

      -

      PR - https://github.com/usnistgov/OSCAL/pull/1207PR - https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: - yes directive on an include-controls indicates that all parent - controls of the included control MUST also be included.

      -

      PENDING PR - https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: - no directive on an include-controls indicates that ONLY the - matching control is included, any parent MUST NOT be included.

      -

      Neither setting is - givenIf no with-parent-controls is provided, the processor MUST - consider the directive as being equivalent to one having - with-parent-controls:yes.

      -
      -
      -
      - exclude-controls -

      Exclusions work the same way as inclusions, except with the opposite effect - the indicated control(s) do not appear in the target catalog.

      -

      Any control designated to be both - included and excluded, MUST be excluded. This holds irrespective of the specificity of - the selection for inclusion or exclusion. For example, if AC-1 is included by id - ac-1 and excluded by matching ac*, it is excluded.

      -

      When exclude-controls - has at least one with-ids or matching directive, the processor - MUST follow the same rules as defined in the relevant sections above for these - directives, but exclude instead of include any controls. All optional features - (with-child-controls, etc.) also apply to exclusion directives.

      -
      -
      - Redundant Inclusions and Exclusions -

      A given import may have - any number of inclusion statements and any number of exclusion statements. Their effect - is cumulative; any control that is included (or excluded) more than once MUST be - considered to be included (or excluded) only once. In other words, a given control being - included or excluded more than once has no effect. Exclusion still takes priority over - inclusion (see above).

      -

      Note that this requirement only applies to controls included within the context of a single import. Controls with duplicate IDs included under a different - import are not discarded. Also note that this redundancy pruning happens after any relevant mappings have been applied. -

      -
      -
      - Handling Params -

      Any - paramthat is not directly under a control is referred to as a - looseparam. -

      -

      All loose params from both imported documents and the profile source MUST be included. These params will be kept in the final output if the document contains any references to them, and discarded otherwise. See - . Since new references can be created during the - modify phase, tools should be careful not to prune params without fully understanding the final state of the output document. -

      -
      -
      - Handling Groups -

      Some source catalogs use - group objects to place controls into arbitrary groupings. Tools will need to be aware of these groups when executing the "merge" phase below, as they will duplicated into the output under the "as-is" mode and can be referenced in "custom" mode. The naïve intermediate approach would keep all groups until all other phases are complete, but implementations may find it more performant to look ahead and prune unused groups early. -

      -

      Group objects that have a child prop object with name:keep and value:always MUST NOT be pruned (see . Additional details on handling the final outputting of these groups can be found in the "merge" phase below.

      -
      -
      - Avoiding Implementation Pitfalls -

      In order to ensure that implementers have as much flexibility as possible, requirements in this section have purposefully been kept minimal. Below are some common issues for implementers to be aware of:

      -
        -

      • The ordering and hierarchical organization of included controls as they were present in the original catalog may be used later in the resolution process. - Specifically, if the profile is using the "as-is" structuring directive, the ordering and organziation of the output should match the source catalog as closely as possible. - Implementations may want to track this information, or look ahead to see what structuring mode is being used. Note that "as-is" also requires implementations to replicate any use of the group element.

        -
        • -
      -
      -
      -
      - Wrapping up the Import Phase -

      At this point all requirements for content importing and control inclusion have been covered. If using the intermediate approach, the processor should have an intermediate that contains: a set of included controls and all of their child informational (non-control, non-group) objects, any relevant - group objects and their informational content, and a set of included "loose params" - (zero to many). The general structure of the intermediate would match that of the imported catalogs (i.e. nested controls remain nested, grouped controls remain grouped). -

      -
      -
      -
      - Merge Phase -

      Profiles may contain a - mergesection, where directives are given to instruct the processor how to combine the set of included objects collected during the Import Phase. - mergehas two parts: a "combine" directive, and a "structuring" directive. -

      -

      PENDING is this testable?It is RECOMMENDED that tools apply the - "combine" directive to the intermediate generated by the Import phase first, then - apply the "structuring" directive.

      -

      The following section contains requirements for processing the - merge child of a source profile. -

      -
      - The "combine" Directive -

      - combineis an optional child of - mergethat provides the rules for dealing with objects that have duplicate (or clashing) distinct IDs - . -

      -

      There are two valid combination methods provided by OSCAL, provided by the - methodchild of - combine: -

      -
        -
      • -

        use-first: Use the first definition - the first control with a given ID is used; subsequent ones are discarded

        -
        • -
      • -

        keep: Keep - controls with the same ID are kept, retaining the clash

        -
        • -
      -

      PENDING specificationNote that "merge: - combine" is deprecated, and MUST be considered undefined behavior when - encountered.

      -

      In order to apply the combination method, IDs of each control explicitly included are compared against one another. As IDs are unique across entire OSCAL documents, different imports or any groupings have no bearing on collision. Processing requirements for each method are described below.

      -
      - No Combine Directive -

      - If no merge directive - is given in the profile, or if a merge is given without a combine, - merge conflicts MUST be treated as if method: keep was given. For - example, a profile with no merge directive:

      - - - -

      is the same as

      - - - -
      -
      - - method:keep - -

      When a merge is indicated by - method:keep, or when no merge directive is given, the - keepcombination rule is used. Any control with the same distinctive ID - MUST NOT not merged. (They are kept.) -

      - - - -

      Under this directive, colliding controls will result in invalid results, as they will both appear in the results with the same ID. Accordingly, this setting may be useful in ensuring integrity of references to controls as given in the profile: if any included control is called only once, clashing controls will not be produced and validation will succeed.

      - - - -

      In the intermediate (showing control inclusions):

      - - - -

      In this case, downstream errors should be expected: the two - ac-1 controls clash with each other, as do the two - ac-2 controls. -

      -

      Processors SHOULD provide a warning under the merge:keep directive when duplicate controls are detected. The processor MAY throw an error and cease processing (short-circuiting a certain future error) when duplicate controls are detected under the merge:keep directive.

      -
      -
      - - method:use-first - - - - -

      When the - "use-first"combination rule is applied, and controls that share a distinctive ID are found, the first control encountered MUST be kept, the rest MUST be discarded. - "First" MUST be determined by a top-down, depth-first traversal of the source profile's import hierarchy. -

      - - - - -

      In the intermediate(showing control inclusions):

      - - - -       -
      -
      - - method:merge - -

      Deprecated, unspecified behavior.

      -
      -
      -
      - The "structuring" Directive -

      This section describes how a profile may dictate the structure of the target - catalog, apart from its - metadata or - back-matter. Optionally, one of three "structuring" directives can be included as a child of - merge: - flat, - as-isand - custom. When one of these appears, it is the selected structuring directive. If more than one appears, processors MUST generate an error and cease processing. Processing requirements for each are given below: -

      -
      - No Structuring Directive -

      If no - merge directive is given in the profile, or if a - merge is given without a structuring directive, structuring the output MUST be treated as if the structuring directive - flat was given. For example, a profile with no - merge directive: -

      - - - -

      is the same as

      - - - -
      -
      - "flat" -

      Profiles with the "flat" merge directive MUST be resolved as unstructured catalogs, with no grouping or nesting of controls.

      -

      Unstructured catalog output MUST be produced by adhering to the following requirements:

      -
        -
      • -

        All included controls are output to the target as a flat list directly under "catalog".

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under "catalog".

        -
        • -

      • Any groups are discarded.

        • -
      -

      An example of flat structuring is provided below

      - - - - - - - - - -
      -
      - - as-is - -

      An - as-is directive is used to reproduce the structure of the source documents in the target catalog. -

      -

      Processors MUST handle the - as-is directive by adhering to the following requirements: -

      -
        -
      • -

        All included controls are output to the target, keeping the structure of the groups and nested controls. Any group that holds an included control MUST appear in the output with all of its non-control children intact. - If an included control has a parent control that was not included, that control's output location is "up-leveled", or made equal to the non-included parent. This applies recursively until the control is directly under either "catalog" or another included control.

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under "catalog".

        -
        • -
      -

      Example:

      - - - - - - - - - -
      -
      - - custom - -

      The - customdirective provides the target catalog with a custom structure. A one-to-one mapping of the desired structure of the target catalog is defined alongside control matching instructions, resulting in a strictly controlled output catalog. -

      -
      - Creating Custom Groups -

      A - groupobject given under - custom MUST result in a - group with the exact same content (excluding - insert-controls) in the target catalog. -

      -

      If the ID of the group matches the ID of a group that has been included during the import phase, all contents inside the group, including - title, - param, - prop and - part objects MUST be copied into the target, appearing in the same order as in the source. -

      -

      Note that groups defined in - custom may vary from fully featured to minimally instantiated. This includes arbitrary nesting of such groups inside of one another. No groups other than those explicitly declared should appear in the output catalog. -

      -
      -
      - Inserting Controls -

      The - insert-controls directive may appear anywhere under - custom, whether as a direct child or inside any of the defined groups. Inside insert-controls, - include-controls and - include-all from the Import Phase - are used with the same basic behavior to configure which controls are selected and inserted at the current location. -

      -

      In order to provide clarity, controls that match the various conditions of these inclusion directives inside the - custom object will be referred to as "selected" instead of "included". Only directly selected controls will appear in the target catalog. -

      -

      When processing the control selection of a custom element, the behavior defined in this section MUST be followed to generate the output.

      -

      A - insert-controls with an - include-controls child results in the following behavior: -

      -
        -
      • -

        - with-idresults in selecting and inserting, at that point inside the new grouping, the included controls with the - idgiven by - with-id. They should be given in the same order as they appear in the control selection(s). -

        -
        • -
      • -

        A - matchingdirective results in selecting and inserting, at that point inside the new grouping, all included controls whose - idmatch, as a Glob expression, the pattern given in the - pattern. They are given in the same order as they appear in the input control selection(s). -

        -
        • -
      -

      An - insert-controls with an - include-all child results in all included controls being selected and inserted. They are given in the same order as they appeared in the input control selection(s). -

      -

      - insert-controls can also indicate the order that the selected controls are to be emitted in the result catalog using an - order child. Three values MUST be supported and handled as specified below: -

      -
        -
      • -

        - ascendingwill sort all selected controls into ascending alphanumeric order by their ID. -

        -
        • -
      • -

        - descendingwill sort all selected controls into descending alphanumeric order by their ID. -

        -
        • -
      • -

        - keepindicates that controls should be inserted in the order of their appearance, using a depth-first traversal of the source profile's imports. -

        -
        • -
      -

      In the case that a control selection matches none of the included controls, it MUST be ignored. In the case that a control selection matches none of the included controls, a warning SHOULD be provided. If a control that was included by the Import Phase is never selected, no error occurs. That control simply does not appear in the output catalog.

      -
      -
      -
      -
      - Wrapping up the Merge Phase -

      After the merge phase, the intermediate should now closely resemble the content and structure of the final output catalog. Controls and groups have been included, remapped, de-duplicated, then placed into their final location within the output's structure. Note: there is still an opportunity for included controls or groups to become referenced; and therefore, not eligible for pruning - in the next phase. -

      -

      Regardless of any merge directives, there also likely remains "loose params" that have been propagated forward; these too must be persisted.

      -
      -
      -
      - Modify Phase -

      There are two ways profiles may further modify the results of profile resolution: setting parameters and altering controls. These activities are defined as two child objects inside the third step of profile resolution, the Modify Phase.

      -

      The following section contains requirements for processing the - modify child of a source profile. -

      -
      - Setting Parameters -

      Modification of parameter settings is indicated using the - set-parameter object under - modify. For this section, a given - set-parameter object will be referred to as the - source. -

      -

      Profile Resolution Tools MUST adhere to the following requirements for processing "set-parameter":

      -
        -
      • -

        First, the list of included params (among "loose params" and remaining included controls and groups) is searched for a param who has an "id" equal to this object's "param-id". This is the "target". If no such parameter is found, a warning SHOULD be issued. If no such parameter is found, processing MUST still continue.

        -
        • -
      • -

        For the following objects inside the source: class, depends-on, label, usage, values, select; the object MUST be copied into the target from the source, first removing any existing objects with the same name.

        -
        • -
      • -

        For the following objects inside the source: props, links, constraints, guidelines; the contents of the object MUST be added to the contents of the target object of the same name. If no such object exists in the target, it is created.

        -
        • -

      • For the following objects inside the source: prop, link; the object MUST be copied into the target from the source, first removing any existing objects with the same distinctive ID. ().

        • -
      • -

        If more than one - set-parameter directive is given for the same parameter, all MUST BE applied, in the sequence given in the profile. -

        -
        • -
      -
      -
      - Altering controls -

      A control can be altered by an - alterobject inside "modify". The - control-idchild object under the - alterindicates the control to which the alteration is applied. -

      -
      - Adding contents to controls -

      Contents may be added to controls using an add directive inside an alter directive. There are two forms of alteration: with implicit and explicit bindings.

      -
      - Implicit binding -

      An - add directive with no - by-id child MUST be considered an implicit binding, and will apply to the control as a whole. -

      -

      The contents of an implicitly bound add directive MUST be added to the control contents in the target, either after its - title when - position is - starting, or at the end if its position is - ending, or if no valid position is given. -

      -

      When an add directive is implicitly bound, the - position values - before and - after MUST be treated like - starting and - ending, respectively. -

      -

      Control contents in catalogs must appear in the order - title, param, prop, link, part, control per the OSCAL model documentation. After processing an implicitly bound add directive, the control contents MUST be sorted to appear in the required order: a new - prop appears after any - prop already in the control, when - position is - ending, or not given, or before any - prop in the control when - position is - starting. -

      - - -

      An addition operating on a control with implicit binding and position - starting -

      - - - - - - - - - -

      Position is - startingbut the new - partis added after the existing - prop, because - propobjects must always occur first. -

      -       - -

      An addition operating on a control with implicit binding and position - ending -

      - - - - - - - - - -

      The - positionis - endingso the new - propappears after the existing - prop. -

      -       -
      -
      - Explicit binding -

      An explicit binding on an addition permits inserting new contents anywhere in a control, not only at the top level. An - add directive with a - by-id child MUST be considered an explicit binding, and applies to only a single object inside the control. When an add directive is explicitly bound, the value of the - by-id child MUST correspond to the value of an - id on an object inside the control, and not the control itself. If - by-id does not correspond to such a value, the - add directive MUST be considered inoperative and ignored. An inoperative add directive MAY result in a warning. -

      -

      The object with - id equal to the value of - by-id is considered the - target of the addition. -

      -

      When - position has a value of - startingor - ending, the contents of the source MUST be added inside the target, either at the start or end of its contents, respectively. -

      -

      When - position has a value of - before or after, the contents of the source MUST be added outside the target, either directly before or after it, respectively. -

      - -

      An addition operating on a control with explicit binding and position - after -

      - - - -

      Note that the - adddirective identifies the object with - id - a1.b1as its target. -

      - - - - - - -

      The - positionis - afterso both objects inside - addare added after (not inside) the target object. Since the target object is inside another - partin the control, the new additions appear there as well. -

      -

      Note that the result in this case will be schema-invalid since a - propmay not occur directly following a - part. A better result can be obtained (a better target may be defined) by using two - adddirectives, to insert the new - propseparately before any - partobjects in the target. -

      -       -
      -
      - Modifying controls inside controls - -

      OSCAL supports controls inside controls in the form of - control objects inside - control objects. Because the semantics of the - add and remove directives target any (object) contents of controls, they can be used to target these child controls for modification as well as other contents. Profile resolution tools MUST be able to correctly handle add directives targetting nested controls. This includes directives that target a child control as well as directives that target a parent control and modify the child.

      -
      -
      -
      - Removing contents from controls -

      Contents inside controls can be removed from them in catalog targets. In combination with adding new contents, this feature can be used to edit controls as well as amend them.

      -

      A - removedirective inside an - alter directive identifies an object or set of objects inside a control to be removed. It does this using any of five child objects. -

      -

      An object inside the control MUST be removed from the output if and only if it meets all of the criteria given by the child objects of the remove directive. When more than one child appears under the remove directive, an object would need to match all of them, otherwise it is not removed.

      -
        -
      • -

        - The remove directive criteria by-id MUST match an object if and only if its value is identical to the id value of that object. Because - id values are unique, this criteria will result in the remove directive removing only a single object. -

        -
        • -
      • -

        - The remove directive criteria name-ref MUST match an object if and only if its value is identical to the value of that object's name child. -

        -
        • -
      • -

        The remove directive criteria ns-ref MUST match an object if and only if its value is identical to the value of that object's ns child.

        -
        • -
      • -

        The remove directive criteria class-ref MUST match an object if and only if its value is identical to the value of that object's class child.

        -
        • -
      • -

        The remove directive criteria item-name MUST match an object if and only if its value is identical to the value of that object's serialized name. For example, - remove:item-name:prop has the effect of removing all - propobjects from inside the control. -

        -

        In serialization formats that use arrays of objects in the OSCAL model, an object's name MUST be referenced as singular form of its containing parent array. For example, in the JSON format, remove:item-name:link would remove all of the objects inside of the links array.

        -
        • -
      -
      -
      -
      -
      - Final Operations -
      - Backmatter Resolution -

      - back-matter in the result is produced by combining all objects within - back-matter in all source catalogs, with the - back-matter in the input profile. -

      -
        -

      • The output's backmatter MUST be generated by copying in each resource object from the backmatters of the imported catalogs/profiles in top-to-bottom order, then by copying in each resource object from the backmatter of the source profile itself. These objects MUST be processed in the order they are defined in each respective document.

        • -
      • -

        If a given - resource has the same - uuid as a resource that has already been added, the previous resource MUST be removed, and the more recent one added, unless superseded by other requirements. -

        -
        • -
      • -

        A resource with a child prop of name:keep and value:always MUST NOT be replaced by the addition of another resource, unless the new resource also has a child prop of name:keep and value:always.

        -
        • -
      -

      Tools MAY check for pruning conditions - as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition. -

      -

      Placing the keep always prop on a resource in a catalog has the effect of ensuring it will always appear in the output produced by any profile importing that catalog, even if nothing links to the resource. This version of the resource will also be the one copied, unless a later-imported catalog or importing profile offers its own version marked to keep always.

      -
      -
      - Metadata Resolution -

      The following requirements MUST be followed with regards to the Metadata section of the output catalog:

      -
        -
      • -

        The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid). This UUID MAY be generated as seen fit by the tool, as long as it is reasonable to assume it is globally unique. It is RECOMMENDED that tools use a Version 4 UUID as specified in Section 4 of RFC 4122. -

        -
        • -
      • -

        The value of metadata:version in the target MUST be set with a string that identifies the version of that document. The metadata:version SHOULD be used to track updates to this specific output document.

        -
        • -
      • -

        The value of metadata:oscal-version in the target MUST be set with a string that identifies the version of OSCAL used by this tool to resolve the profile (ex. 1.0.0). This value MUST be determined by compiling the oscal-versions from each imported document and the source profile, and taking the most recent minor version. If this version is more recent than what the resolution tool is using, then the value of oscal-version MUST be the version that the tool used internally. If any of the above OSCAL versions (imported document versions, source profile version, tool version) are of a different major version (the first digit differs), the tool SHOULD provide an error and cease processing.

        -
        • -
      • -

        The value of metadata:last-modified in the target MUST be set with a valid timestamp representing the time the profile resolution completed.

        -
        • -
      • -

        A child prop object with name:source-profile MUST be created. The value object of this prop SHOULD be set with a valid URI that points to the profile that resulted in this catalog. - If there are privacy or security concerns, the value object of this prop MAY be set to anything, in which case the simple existence of the source-profile property indicates that this is a resolved profile.

        -
        • -
      • -

        A child prop object with name:resolution-tool SHOULD be created. The value object of this prop in the target SHOULD be set with a string that represents the tool that was used to resolve this catalog.

        -
        • -

      • For any metadata:roles or metadata:parties that exist in the source catalogs, if they have a prop child with name:keep and value:always, they are to be copied as is into the output metadata.

        • -
      -

      Beyond these requirements, tools are free to use any and all of the objects inside metadata to provide additional information downstream.

      -

      Because of options in producing metadata and especially the requirement for a timestamp, developers and users should note that two different resolutions of the same profile will not, ordinarily, be identical inside - metadata. -

      -
      -
      - Pruning and Ordering -

      The processor SHOULD prune the resulting output catalog by removing unused objects.

      -
        -
      • -

        Any object that has a child prop with a name of "keep" and a value of "always" MUST NOT be pruned.

        -
        • -
      • -

        If an object was explicitly included in the - , it MUST NOT be pruned. -

        -
        • -
      • -

        If an object was referenced in a custom section of the source profile, it MUST NOT be pruned.

        -
        • -
      • -

        If an object was referenced in the modify section of the source profile, it MUST NOT be pruned. Any objects removed in that section are still removed.

        -
        • -
      • -

        If the object appears in a reference anywhere in the final result catalog, except in other objects that also meet all other pruning criteria, it MUST NOT be removed. A reference to a given object exists if #{distinctiveID} appears anywhere, where {distinctiveID} is the distinctive ID of the object - . -

        -
        • -
      -

      Implementers should note that pruning need not take place after all other steps. As long as all above criteria are respected, pruning can happen at any time, and doing so is a likely performance and memory overhead improvement.

      -

      Tools MUST reorder the output catalog into canonical order - , except where this specification provides different ordering requirements. -

      -
      -
      -
      - Items of Note -
      - Distinct ID of Objects -

      Whenever this specification refers to - "distinctiveness", it is to be interpreted as is defined in this section with regards to the object in question. -

      -

      For the objects control, param, and group, distinctiveness MUST be determined by the value of the - "id" child object. -

      -

      For the object resource, distinctiveness MUST be determined by the value of the - "uuid" - . -

      -
      -
      - Dealing with Multiple Formats -

      Profile Resolution tools SHOULD be able to handle source profiles, imported catalogs, and imported profiles that are serialized in XML, JSON, or YAML. A different serialization format of any given input MUST NOT result in a differing output catalog.

      -

      In order to help bootstrap this format management, the following resources are provided for implementers:

      -
        -
      • -

        . - -

        -
        • -
      -

      The following sections provide additional requirements and guidance for each format.

      -
      - Requirements and Guidance for XML Output -

      The final Catalog output, if using XML, MUST be valid as defined by the XML model documentation for the OSCAL Catalog. See - the complete XML reference for model requirements. -

      -
      -
      - Requirements and Guidance for JSON Output -

      The final Catalog output, if using JSON, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. See the - complete JSON reference for model requirements. -

      -

      The JSON format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, tools SHOULD adhere to the canonical OSCAL order - when outputting a catalog in JSON. -

      -
      -
      - Requirements and Guidance for YAML Output -

      The final Catalog output, if using YAML, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. YAML is considered a simple variation on the JSON format. Beyond cosmetic differences there are no differences in the information structure between these formats. Therefore, the - complete JSON reference provides model requirements. -

      -

      The YAML format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, tools SHOULD adhere to the canonical OSCAL order - when outputting a catalog in YAML. -

      -
      -
      - Order of objects in serialization -

      In OSCAL, order of top level objects (those that are direct children of the root element) is considered important only when the XML format is used. To facilitate this, OSCAL provides the concept of - canonical order. This order is provided by the OSCAL Metaschema files for a given document type (see - an overview of Metaschema. -

      -

      When the output format is XML, tools MUST use the OSCAL canonical order as described above. When using the YAML or JSON formats, order conveys no meaning, and is not considered important.

      -
      -
      - Comments in result documents -

      In an XML-based profile resolution, XML comments are one straightforward way for a processor to record events or conditions without affecting the output's nominal semantics. To support this, while two processors are obliged to return the same catalog XML for the same profile XML inputs, they are not required to match one another's comments, white space usage, attribute order, or processing instructions, only each other's objects, attributes and data content.

      -

      One consequence of this is that processes intended to compare two profile resolutions may have to accommodate differences in comments, considering them as insignificant along with other differences in serialization.

      -
      -
      -
      -       - diff --git a/src/specifications/profile-resolution/profile-resolution-specml-64f22b.xml b/src/specifications/profile-resolution/profile-resolution-specml-64f22b.xml deleted file mode 100644 index 6024066d6f..0000000000 --- a/src/specifications/profile-resolution/profile-resolution-specml-64f22b.xml +++ /dev/null @@ -1,1524 +0,0 @@ - - - - - OSCAL Profile Resolution -
      - Notice of Draft Status -

      Please note that this specification is currently a work in progress and is subject to change. If you have any feedback or comments, please create an issue at the NIST OSCAL Github Repository: .

      -
      -
      - Abstract -

      This specification provides the minimal requirements for processing an OSCAL Profile to create a new OSCAL Catalog Document. This process of applying a profile to a catalog to create a new catalog is called - Profile Resolution. Not all OSCAL Profiles will be resolved, nor are expected to be; however, the resolution requirements in this document are crucial to understanding the intended functionality of any given OSCAL Profile. - This specification is intended for software developers who intend to develop an OSCAL Profile Resolver, or for OSCAL Profile authors who want a more in-depth understanding of profile resolution. -

      -
      -
      - Introduction -
      - Purpose -

      This document defines the normative requirements for an OSCAL Profile Resolver. Profile resolution is core to addressing a fundamental OSCAL requirement: - the representation of baselines separately from the control catalogs on which they depend). The requirements for resolution must therefore be well-defined and deterministic, - enabling tool developers and parties exchanging OSCAL Profiles can work from a common understanding.

      - -

      No requirements are placed on implementation-level details, instead, requirements are laid out as what the output of resolution must look like given a certain input. - By adhering to these requirements OSCAL producers, OSCAL consumers, and any other members of the OSCAL ecosystem can create and resolve profiles deterministically, - with repeatable results, regardless of the tool used.

      -
      -
      -
      - Reading This Document -
      - - Terminology -

      Many core OSCAL concepts are defined on the OSCAL Terminology Page. The most important are repeated in this document, but readers should verify their understanding of all core OSCAL terms before reading this document.

      -

      Additionally, many terms in the wider domain have overloaded definitions. Unless defined otherwise by OSCAL or explicitly in this document, terms are to be understood as defined in the NIST CSRC Glossary.

      -
        -
      • -

        - profile- an OSCAL Profile Document. Defines a set of inclusions, modifications, and transformations against a - catalog. See - OSCAL Profile Model. -

        -
        • -
      • -

        - catalog- an OSCAL Catalog Document. Contains a well-defined set of - controls. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - control- an individual item in an OSCAL Catalog. See - NIST Special Publication 800-53r5for a more in-depth definition. -

        -
        • -
      • -

        - profile resolution- The process of consuming one or more OSCAL Profiles and the OSCAL Catalogs that they reference to produce a new tailored - catalog. See - OSCAL Catalog Model. -

        -
        • -
      • -

        - source- refers to the profile document that is input into the profile resolution processor. This is the profile being resolved. In this document, when referring to objects from the - sourcedocument, the following style is used: - source-object. -

        -
        • -
      • -

        - target- the intended output of the transformation, a catalog document. In this document, when referring to objects of a - targetdocument, the following style is used: - target-object. -

        -
        • -
      • -

        - directive- refers to an object or combination of objects in source documents, which is designed to affect a particular outcome in the target catalog. For the most part, directives are in the source profile document – for example, a - set-parameterobject in a source profile is a directive to set a parameter value in the target catalog. -

        -
        • -
      • -

        - original order- the order of objects as presented in the - sourcedocument(s). See XYZ. -

        -
        • -
      • -

        - canonical order- the order of objects as required in the appropriate OSCAL Model (Profile, Catalog, etc.). This can differ from the above order when converting between "ordered" formats (ex. XML), and "non-ordered" formats (ex. JSON). -

        -
        • -
      -
      -
      - Requirement Keywords -

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in - BCP 14 - [RFC2119] - [RFC8174]when, and only when, they appear in all capitals, as shown here. -

      -
      -
      - Use of YAML -

      OSCAL supports a variety of serialization formats, each of which having it's own benefits and drawbacks. In this document, YAML (YAML Ain't Markup Language) is used to represent the various objects of the - sourceand - target. All examples and in-line references will be represented using - YAML 1.2. -

      -

      YAML maps cleanly to JSON, thus allowing easy use of existing JSON/XML transformers where needed. With that in mind, the - OSCAL Complete JSON Referenceis a valuable resource for understanding the YAML-based information structures used in this document. All JSON properties and objects defined in the reference equate to a YAML mapping, list, or dictionary. -

      -
      -
      - Reading YAML Examples -

      YAML is a particularly human-readable format. For those unfamiliar with the format, the basics:

      -
        -
      • -

        Each line is a key-value pair, presented as - key:value, or as - key:with any number of list items on the following lines. -

        -
        • -
      • -

        Indentation, spacing, and white space matters. Items below a key and indented one level in are members (or children) of that key.

        -
        • -
      • -

        List items are represented with a preceding dash - - listitemkey:value. -

        -
        • -
      -

      The YAML specification is freely available here: - YAML 1.2. -

      -

      Additionally, in order to unambiguously express information, this specification uses additional conventions, as described below.

      -

      There are some objects whose values must be determined dynamically at processing time. The most common example of this is timestamping output as it is processed. In this case, and any other dynamic-value cases, the expression - ${{ }}is used. -

      -

      For example:

      - last-modified: ${{ timestamp }} -

      Indicates the - last-modifiedobject should be produced with contents generated appropriately, in this case, the timestamp at the time of processing. -

      -

      Some examples may elide content to enhance readability or save space. In these cases, a YAML comment (any line that starts with - #) will be used to explain the elision. -

      -

      Finally, although examples are syntactically faithful to OSCAL, they are not necessarily always formally valid in every respect. For example, OSCAL defines allowed property names ( - props) and values, and those rules may not be observed here. Examples are given for purposes of illustrating profile resolution semantics only, and should not be taken as normative for any actual use. -

      -
      -
      - Document Layout -

      The specification is broken into the following major sections:

      -
        -
      • -

        - Phases of Profile Resolution- Lays out the necessary steps and phases of profile resolution. As each phase executes, the processor is understood to be creating and editing an intermediate representation of the output. There is one section for each of the three main phases. -

        -
        • -
      • -

        - Target Catalog Structure- Provides the requirements for structuring the final output from the intermediate representation generated throughout the previous section. -

        -
        • -
      -

      - Please note: As referenced in the Purpose section - , this specification makes no hard requirements on the specifics of implementation. It is feasible for an implementation to use no intermediate representation, and to directly and iteratively build the output. As long as all processing and output requirements are satisfied, any approach is allowed. With that said, the specification has been laid out to aid in implementation by providing a clear organization as a sequence of distinct operations. -

      -
      -
      - The Intermediate and Implementation Guidance -

      The overall intent of this document, in addition to defining strict requirements, is to provide rough guidelines on implementing an OSCAL Profile Resolution Tool. To this end, each phase of resolution will be framed as a series of transformations applied to an internal data structure that is persistent throughout the process. We call this "the intermediate".

      -

      Any examples that are labelled as "Intermediate" are pseudo-code, designed to represent how this data structure might look as we apply different operations to it. The example intermediates are often not valid OSCAL, and are not to be taken as guidance, but rather a useful visualization tool for implementers.

      -

      The authors believe that applying the steps of resolution in order against this intermediate representation is the simplest way to achieve full compliance with the specification. However, there is no requirement to implement profile resolution in this way. Requirements are given as rules on the output of resolution, and as such, tools can operate any way they would like internally.

      -
      -
      -
      - Phases of Profile Processing -

      An OSCAL Profile has three major sections, each which correspond to a phase of profile resolution. In order to complete the profile resolution process, each section must be fully parsed and a catalog output created.

      -

      It is strongly RECOMMENDED that implementations execute the following steps in the order that they are provided here (import, merge, modify). While it is possible to achieve compliance with a non-standard approach, the iterative nature of profile resolution lends itself to linear processing.

      -

      The three steps are - import; - merge; and - modify. In brief: -

      -
        -
      • -

        - import- identifies one or more control sources (catalogs or profiles) and defines the controls within them to be included in the result catalog. If nothing is imported, no resulting catalog is produced. Invoked by - importdirectives in source profiles; -

        -
        • -
      • -

        - merge- designates the rules for how controls will be organized (ordered and/or grouped) and merged (addressing conflicts or ambiguities) in the result catalog. Controlled by the - mergedirective in source profiles; if none are included, default merge rules are used; -

        -
        • -
      • -

        - modify- indicates how controls and their parameters in the underlying catalog are to be altered, edited, amended or added in the final result catalog. Logical evaluation and parameter constraints provide advanced processing. Controlled by the - modifydirective in source profiles. If a - modifydirective is not provided, no changes will be made to the controls that have been imported/merged. -

        -
        • -
      -

      As described in the previous section, when resolved, an OSCAL Profile takes the form of an OSCAL Catalog. The phases described below will produce outputs conforming to the catalog model.

      -
      -
      - Import Phase -

      A profile begins by listing a set of catalogs and/or profiles to be imported. Each is represented by a resolvable resource URI and a directive specifying which controls to import from that resource. These resources may be available as static resources, or they may be produced dynamically on request; such as is the case when a profile is imported. Imports are given in sequence after the metadata:

      - - - -

      In an import directive, the reference to the resource to be imported appears on an - hrefchild object. It takes either of two forms, external or internal: -

      -

      An external reference appears as an absolute or relative URL:

      - - - - https://github.com/usnistgov/oscal-content/tree - /master/nist.gov/SP800-53/rev4/yaml/NIST_SP-800-53_rev4_catalog.yaml - include-controls: ${{ list of selected controls }} - - href: "../../NIST_SP-800-53_rev5_catalog.yaml" - include-controls: ${{ list of selected controls }} ]]> - -

      While an internal reference appears as below (see - ): -

      - - - -

      All import directives will contain either - include-all: ~or - include-controls. These directives indicate which controls from the imported document are explicitly selected - . -

      -

      The following section contains requirements for processing the - importchild of a source - profile -

      -
      - Import href Requirements -
      - Import URI Resolution -

      Tools MUST resolve URIs by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be resolved as defined in - . -

      -
      -
      - Import Resource Acquisition -

      Tools MUST acquire resources at the resolved URI by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be acquired as defined in - . -

      -

      For the purposes of resolving URIs using the above specification, the Base URI MUST be considered to be the absolute URI of the containing profile.

      -

      In the case that acquiring a resource fails, the tool MUST cease processing and provide an error. In order to ensure profile resolution results in the same catalog regardless of which tool resolves it, all imports must successfully resolve. While this may cause inconvenience if resources are frequently not available, it ensures interoperability.

      -

      Note that receiving a cached version of an import, or resolving an import that is otherwise unavailable through some other (but automatic) means still satisfies the above requirement. This specification does not put requirements on the precise function of the import, as long as the correct document is retrieved.

      -
      -
      - Internal References -

      URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of "#{{objectID}}". For example, the URI Fragment "#param1" is referencing the Parameter with unique ID "param1".

      -

      In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the resources section of the source. When tools encounter such a reference, they MUST locate the object in resources with the matching ID value, and resolve the import using the - rlinkURI and the above resolution requirements. -

      -

      If the object fetched cannot be found or is not a valid OSCAL object, the tool MUST cease processing and provide an error.

      - - - - https://github.com/usnistgov/oscal-content/tree - /master/nist.gov/SP800-53/rev4/xml/NIST_SP-800-53_rev5_catalog.xml ]]> - -
      -
      - Resolving Imports of Profiles -

      If the resource acquired is an OSCAL Profile, the tool MUST apply this specification to resolve it, then continue processing having imported the resulting catalog.

      -

      When a profile imports a profile, the subordinate profile SHOULD be resolved first into a catalog using this specification, before it is imported. This presents the possibility of circular imports, when a profile is directed to import itself either directly or indirectly.

      -

      A - circular importoccurs when a profile imports an already imported profile, which was called at an earlier place in the import hierarchy. For example, if profile A imports profile B, and profile B imports profile A, the second import is circular. (An import at the top can only be circular if a profile tries to import itself.) If A imports B, B imports C and C imports A, C’s import is circular. -

      -

      Note that an import can only be circular within the context of processing a particular profile. In the last example, C’s import would not be circular if invoked in the context of resolving B by itself.

      -

      If a processor encounters a - circular importas described above (self-imports are inherently circular), the processor MUST cease processing and generate an error. -

      - -

      A profile identified as - home_profile.yamlimports another one identified as - circular_profile.yaml: -

      - - - -

      In turn this file invokes - home_profile.xml: -

      - - - -

      Once detected, this circular import will result in an error and no further processing will take place.

      - - - -       -
      -
      - Multiple imports -

      Each import directive is processed to produce a set of controls. Note that this occurs even if the same catalog is imported multiple times: each distinct import collects controls into a separate - selection: -

      - - - - - - -

      The control inclusions are combined and collapsed in the next phase of processing, - merge(see ) . -

      -

      Multiple imports against the same resource are allowed, and would most commonly occur when the profile author is using to create very specific output. - Multiple imports may result in outputs with clashing control IDs if mapping or the merge directive is not set correctly.

      -
      -
      - Mapping Controls -

      The optional - mappingchild of a given - importprovides a simple ID remapping for objects included from that specific import. This provides the means for profile authors to proactively avoid clashing IDs of controls and other objects. -

      -

      The Mapping section consists of 5 optional subsections, each covering a particular type of object. Each subsection is a list of ID mappings to be applied for objects that are the parent object type.

      -

      When encountering a given mapping instruction, processors:

      -
        -
      • -

        MUST change the distinctive ID of that object to be equal to the value of the - toobject. -

        -
        • -
      • -

        MUST update all known references to the old ID in other included content, allowing the new ID to be used in subsequent profile sections.

        -
        • -
      -

      Since mapping is a self contained process inside each import, the rest of this specification will continue to reference IDs with the assumption that mapping has already been applied if it was present. Since mapping is most commonly used to avoid clashing IDs, processors should take care to not handle duplicate IDs until after mapping is complete.

      -

      Below is a simple example of mapping. The second - importis included controls from a different catalog whose ID values happen to collide. Knowing this, the profile author has remapped those IDs to new values. -

      - - - -

      Using the intermediate approach, an internal data structure resembling the following would result from the above profile:

      - - - -
      -
      -
      - Including Controls -

      Each import contains directives on which controls from the imported catalog are to be fetched and used for further processing. Throughout the rest of the document we will refer to this as "inclusion". - If a control is included, and the source profile makes no other changes to it, it will be present in the output. Exclusion directives in this section, as well as directives in the following two major sections (merge and modify), - may make changes to an included control or group that could cause it to appear differently, or not at all, in the output. Using the intermediate implementation approach, any control(s) that are included would be extracted from the referenced catalogs, any applicable mappings would be applied, then the controls(s) would be stored.

      -
      - include-all -

      When an import provides the - include-alldirective, ALL controls and groups in the referenced document (including nested controls) MUST be included. -

      - include-all: ~ -
      -
      - include-controls plus with-id -

      When an import provides the - include-controlsdirective, with a - with-idchild, all controls in the referenced document whose - idmatch one of the listed - idvalues MUST be included. -

      - - - -
      -
      - include-controls plus matching -

      Controls may also be included using match patterns against their IDs. This is useful because related controls (either in a hierarchy, or together in a group) frequently have related IDs as well.

      -

      When an import provides the - include-controlsdirective, with a - matchingchild, all controls in the referenced document whose - idmatches one of the listed - patternvalues (Glob matching) MUST be included. -

      -

      If a - matchingobject is provided with no - pattern, it MUST be treated as matching nothing. While not providing a pattern is technically valid, resolution tool implementers should be aware that it is generally undesirable, and warnings or notices to the user may be appropriate. -

      - - - -
      -
      - Dealing with Nested Controls and Groups -

      In OSCAL, controls may contain child controls. For instance, in SP 800-53 many controls are supplemented with control enhancements; in OSCAL these are represented as child controls within parent controls. So parent AC-2 (in a given catalog) has children AC-2(1) through AC-2(13), for example.

      -

      By default, inclusion of a control also causes any of that control's ancestors (or parents) to also be included. By default, inclusion of a control DOES NOT cause the inclusion of any descendants (or children) of that control to be included. This applies to both controls and groups.

      -

      This default behavior can be modified by the following two optional children of the - include-controlsobject. -

      -
      - with-child-controls -

      Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the "with-child-controls" option. "with-child-controls" appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.

      -

      A - with-child-controls: yesdirective on an - include-controlsindicates that - all descendant controlsof the included control MUST also be included. -

      -

      A - with-child-controls: nodirective on an - include-controlsindicates that ONLY the matching control is included, any descendant children MUST NOT be included. -

      -

      If no - with-child-controlsis provided, the processor MUST consider the directive as being equivalent to one having - with-child-controls:no. -

      -
      -
      - with-parent-controls -

      Although similar to the above - with-child-controls, the optional - with-parent-controlsapplies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they could use an exclude directive that lists all of the undesired parents. As a shortcut for this, - with-parent-controlsprovides the following functionality: -

      -

      A - with-parent-controls: yesdirective on an - include-controlsindicates that - all parent controlsof the included control MUST also be included. -

      -

      A - with-parent-controls: nodirective on an - include-controlsindicates that ONLY the matching control is included, any parents MUST NOT be included. -

      -

      If no - with-parent-controlsis provided, the processor MUST consider the directive as being equivalent to one having - with-parent-controls:yes. -

      -
      -
      -
      - exclude-controls -

      Exclusions work the same way as inclusions, except with the opposite effect - the indicated control(s) do not appear in the target catalog.

      -

      Any control designated to be both included and excluded, MUST be excluded. This holds irrespective of the specificity of the selection for inclusion or exclusion. For example, if AC-1 is included by id - ac-1and excluded by matching - ac.*, it is excluded. -

      -

      When - exclude-controlshas at least one - with-idsor - matchingdirective, the processor MUST follow the same rules as defined in the relevant sections above for these directives, but exclude instead of include any controls. All optional features (with-child-controls, etc.) also apply to exclusion directives. -

      -
      -
      - Redundant Inclusions and Exclusions -

      A given - importmay have any number of inclusion statements and any number of exclusion statements. Their effect is cumulative; any control that is included (or excluded) more than once MUST be considered to be included (or excluded) only once. In other words, a given control being included or excluded more than once has no effect. Exclusion still takes priority over inclusion (see above). -

      -

      Note that this requirement only applies to controls included within the context of a single import. Controls with duplicate IDs included under a different - importare not discarded. Also note that this redundancy pruning happens after any relevant mappings have been applied. -

      -
      -
      - Handling Params -

      Any - paramthat is not directly under a control is referred to as a - looseparam. -

      -

      All loose params from both imported documents and the profile source MUST be included. These params will be kept in the final output if document contains any references to them, and discarded otherwise. See - . Since new references can be created during the - modifyphase, tools should be careful not to prune params without fully understanding the final state of the output document. -

      -
      -
      - Handling Groups -

      Some source catalogs use - groupobjects to place controls into arbitrary groupings. Tools will need to be aware of these groups when executing the "merge" phase below, as they will duplicated into the output under the "as-is" mode and can be referenced in "custom" mode. The naïve intermediate approach would keep all groups until all other phases are complete, but implementations may find it more performant to look ahead and prune unused groups early. -

      -
      -
      - Avoiding Implementation Pitfalls -

      In order to ensure that implementers have as much flexibility as possible, requirements in this section have purposefully been kept minimal. Below are some common issues for implementers to be aware of:

      -
        -

      • The ordering and hierarchical organization of included controls as they were present in the original catalog may be used later in the resolution process. - Specifically, if the profile is using the "as-is" structuring directive, the ordering and organziation of the output should match the source catalog as closely as possible. - Implementations may want to track this information, or look ahead to see what structuring mode is being used. Note that "as-is" also requires implementations to replicate any use of the group element.

        -
        • -
      -
      -
      -
      - Wrapping up the Import Phase -

      At this point all requirements for content importing and control inclusion have been covered. If using the intermediate approach, the processor should have an intermediate that contains: a set of included controls and all of their child informational (non-control, non-group) objects, any relevant - groupobjects and their informational content, and a set of included "loose params" - (zero to many). The general structure of the intermediate would match that of the imported catalogs (i.e. Nested controls remain nested, grouped controls remain grouped). -

      -
      -
      -
      - Merge Phase -

      Profiles may contain a - mergesection, where directives are given to instruct the processor how to combine the set of included objects collected during the Import Phase. - mergehas two parts: a "combine" directive, and a "structuring" directive. -

      -

      It is RECOMMENDED that tools apply the "combine" directive to the intermediate generated by the Import phase first, then apply the "structuring" directive.

      -

      The following section contains requirements for processing the - mergechild of a source profile. -

      -
      - The "combine" Directive -

      - combineis an optional child of - mergethat provides the rules for dealing with objects that have duplicate (or clashing) distinct IDs - . -

      -

      There are two valid combination methods provided by OSCAL, provided by the - methodchild of - combine: -

      -
        -
      • -

        use-first: Use the first definition - the first control with a given ID is used; subsequent ones are discarded

        -
        • -
      • -

        keep: Keep - controls with the same ID are kept, retaining the clash

        -
        • -
      -

      Note that "merge: combine" is deprecated, and MUST be considered undefined behavior when encountered.

      -

      In order to apply the combination method, IDs of each control explicitly included are compared against one another. As IDs are unique across entire OSCAL documents, different imports or any groupings have no bearing on collision. Processing requirements for each method are described below.

      -
      - No Combine Directive -

      If no - mergedirective is given in the profile, or if a - mergeis given without a - combine, merge conflicts MUST be treated as if - method: keepwas given. For example, a profile with no - mergedirective: -

      - - - -

      is the same as

      - - - -
      -
      - - method:keep - -

      When a merge is indicated by - method:keep, or when no merge directive is given, the - keepcombination rule is used. Any controls with the same distinctive ID - MUST NOT not merged. (They are kept.) -

      - - - -

      Under this directive, colliding controls will result in invalid results, as they will both appear in the results with the same ID. Accordingly, this setting may be useful in ensuring integrity of references to controls as given in the profile: if any included control is called only once, clashing controls will not be produced and validation will succeed.

      - - - -

      In the intermediate (showing control inclusions):

      - - - -

      In this case, downstream errors should be expected: the two - ac-1controls clash with each other, as do the two - ac-2controls. -

      -

      Processors SHOULD provide a warning under the merge:keep directive when duplicate controls are detected. The processor MAY throw an error and cease processing (short-circuiting a certain future error) when duplicate controls are detected under the merge:keep directive.

      -
      -
      - - method:use-first - - - - -

      When the - use-firstcombination rule is applied, and controls that share a distinctive ID are found, the first control encountered MUST be kept, the rest MUST be discarded. - FirstMUST be determined by a top-down, depth-first traversal of the source profile's import hierarchy. -

      - - - - -

      In the intermediate(showing control inclusions):

      - - - -       -
      -
      - - method:merge - -

      Deprecated, unspecified behavior.

      -
      -
      -
      - The "structuring" Directive -

      This section describes how a profile may dictate the structure of the target - catalog, apart from its - metadataor - back-matter. Optionally, one of three "structuring" directives can be included as a child of - merge: - flat, - as-isand - custom. When one of these appears, it is the selected structuring directive. If more than one appears, processors MUST generate an error and cease processing. Processing requirements for each are given below: -

      -
      - No Structuring Directive -

      If no - mergedirective is given in the profile, or if a - mergeis given without a structuring directive, structuring the output MUST be treated as if the structuring directive - flatwas given. For example, a profile with no - mergedirective: -

      - - - -

      is the same as

      - - - -
      -
      - "flat" -

      Profiles with the "flat" merge directive MUST be resolved as unstructured catalogs, with no grouping or nesting of controls.

      -

      Unstructured catalog output MUST be produced by adhering to the following requirements:

      -
        -
      • -

        All included controls are output to the target as a flat list directly under "catalog".

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under "catalog".

        -
        • -

      • Any groups are discarded.

        • -
      -

      An example of flat structuring is provided below

      - - - - - - - - - -
      -
      - - as-is - -

      An - as-isdirective is used to reproduce the structure of the source documents in the target catalog. -

      -

      Processors MUST handle the - as-isdirective by adhering to the following requirements: -

      -
        -
      • -

        All included controls are output to the target, keeping the structure of the groups and nested controls. Any group that holds an included control MUST appear in the output with all of its non-control children intact. - If an included control has a parent control that was not included, that control's output location is "up-leveled", or made equal to the non-included parent. This applies recursively until the control is directly under either "catalog" or another included control.

        -
        • -
      • -

        Any included "loose params" are output to the target as a flat list directly under "catalog".

        -
        • -
      -

      Example:

      - - - - - - - - - -
      -
      - - custom - -

      The - customdirective provides the target catalog with a custom structure. A one-to-one mapping of the desired structure of the target catalog is defined alongside control matching instructions, resulting in a strictly controlled output catalog. -

      -
      - Creating Custom Groups -

      A - groupobject given under - customMUST result in a - groupwith the exact same content (excluding - insert-controls) in the target catalog. -

      -

      If the ID of the group matches the ID of a group that has been included during the import phase, all contents inside the group, including - title, - param, - propand - partobjects MUST be copied into the target, appearing in the same order as in the source. -

      -

      Note that groups defined in - custommay vary from fully featured to minimally instantiated. This includes arbitrary nesting of such groups inside of one another. No groups other than those explicitly declared should appear in the output catalog. -

      -
      -
      - Inserting Controls -

      The - insert-controlsdirective may appear anywhere under - custom, whether as a direct child or inside any of the defined groups. Inside insert-controls, - include-controlsand - include-allfrom the Import Phase - are used with the same basic behavior to configure which controls are selected and inserted at the current location. -

      -

      In order to provide clarity, controls that match the various conditions of these inclusion directives inside the - customobject will be referred to as "selected" instead of "included". Only directly selected controls will appear in the target catalog. -

      -

      When processing the control selection of a custom element, the behavior defined in this section MUST be followed to generate the output.

      -

      A - insert-controlswith an - include-controlschild results in the following behavior: -

      -
        -
      • -

        - with-idresults in selecting and inserting, at that point inside the new grouping, the included controls with the - idgiven by - with-id. They should be given in the same order as they appear in the control selection(s). -

        -
        • -
      • -

        A - matchingdirective results in selecting and inserting, at that point inside the new grouping, all included controls whose - idmatch, as a Glob expression, the pattern given in the - pattern. They are given in the same order as they appear in the input control selection(s). -

        -
        • -
      -

      An - insert-controlswith an - include-allchild results in all included controls being selected and inserted. They are given in the same order as they appear in the input control selection(s). -

      -

      - insert-controlscan also indicate the order that the selected controls are to be emitted in the result catalog using an - orderchild. Three values MUST be supported and handled as specified below: -

      -
        -
      • -

        - ascendingwill sort all selected controls into ascending alphanumeric order by their ID. -

        -
        • -
      • -

        - descendingwill sort all selected controls into descending alphanumeric order by their ID. -

        -
        • -
      • -

        - keepindicates that controls should be inserted in the order of their appearance, using a depth-first traversal of the source profile's imports. -

        -
        • -
      -

      In the case that a control selection matches none of the included controls, it MUST be ignored. In the case that a control selection matches none of the included controls, a warning SHOULD be provided. If a control that was included by the Import Phase is never selected, no error occurs, that control simply does not appear in the output catalog.

      -
      -
      -
      -
      - Wrapping up the Merge Phase -

      After the merge phase, the intermediate should now closely resemble the content and structure of the final output catalog. Controls and groups have been included, remapped, de-duplicated, then placed into their final location within the output's structure. Note: there is still an opportunity for included controls or groups to become referenced; and therefore, not eligible for pruning - in the next phase. -

      -

      Regardless of any merge directives, there also likely remains "loose params" that have been propagated forward; these too must be persisted.

      -
      -
      -
      - Modify Phase -

      There are two ways profiles may further modify the results of profile resolution: setting parameters, and altering controls. These activities are defined as two child objects inside the third step of profile resolution, the Modify Phase.

      -

      The following section contains requirements for processing the - modifychild of a source profile. -

      -
      - Setting Parameters -

      Modification of parameter settings is indicated using the - set-parameterobject under - modify. For this section, a given - set-parameterobject will be referred to as the - source. -

      -

      Profile Resolution Tools MUST adhere to the following requirements for processing "set-parameter":

      -
        -
      • -

        First, the list of included params (among "loose params" and remaining included controls and groups) is searched for a param who has an "id" equal to this object's "param-id". This is the "target". If no such parameter is found, a warning SHOULD be issued. If no such parameter is found, processing MUST still continue.

        -
        • -
      • -

        For the following objects inside the source: class, depends-on, label, usage, values, select; the object MUST be copied into the target from the source, first removing any existing objects with the same name.

        -
        • -
      • -

        For the following objects inside the source: props, links, constraints, guidelines; the contents of the object MUST be added to the contents of the target object of the same name. If no such object exists in the target, it is created.

        -
        • -

      • For the following objects inside the source: prop, link; the object MUST be copied into the target from the source, first removing any existing objects with the same distinctive ID. ().

        • -
      • -

        If more than one - set-parameterdirective is given for the same parameter, all MUST BE applied, in the sequence given in the profile. -

        -
        • -
      -
      -
      - Altering controls -

      A control can be altered by an - alterobject inside "modify". The - control-idchild object under the - alterindicates the control to which the alteration is applied. -

      -
      - Adding contents to controls -

      Contents may be added to controls using an add directive inside an alter directive. There are two forms of alteration: with implicit and explicit bindings.

      -
      - Implicit binding -

      An - adddirective with no - by-id child MUST be considered an implicit binding, and will apply to the control as a whole. -

      -

      The contents of an implicitly bound add directive MUST be added to the control contents in the target, either after its - titlewhen - positionis - starting, or at the end if its position is - ending, or if no valid poisition is given. -

      -

      When an add directive is implicitly bound, the - positionvalues - beforeand - afterMUST be treated like - startingand - ending, respectively. -

      -

      Control contents in catalogs must appear in the order - title, param, prop, link, part, control per the OSCAL model documentation. After processing an implicitly bound add directive, the control contents MUST be sorted to appear in the required order: a new - propappears after any - propalready in the control, when - positionis - ending, or not given, or before any - propin the control when - positionis - starting. -

      - - -

      An addition operating on a control with implicit binding and position - starting -

      - - - - - - - - - -

      Position is - startingbut the new - partis added after the existing - prop, because - propobjects must always occur first. -

      -       - -

      An addition operating on a control with implicit binding and position - ending -

      - - - - - - - - - -

      The - positionis - endingso the new - propappears after the existing - prop. -

      -       -
      -
      - Explicit binding -

      An explicit binding on an addition permits inserting new contents anywhere in a control, not only at the top level. An - adddirective with a - by-id child MUST be considered an explicit binding, and applies to only a single object inside the control. When an add directive is explitly bound, the value of the - by-id child MUST correspond to the value of an - idon an object inside the control, and not the control itself. If - by-iddoes not correspond to such a value, the - adddirective MUST be considered inoperative and ignored. An inoperative add directive MAY result in a warning. -

      -

      The object with - idequal to the value of - by-idis considered the - targetof the addition. -

      -

      When - position has a value of - startingor - ending, the contents of the source MUST be added inside the target, either at the start or end of its contents, respectively. -

      -

      When - position has a value of - before or after, the contents of the source MUST be added outside the target, either directly before or after it, respectively. -

      - -

      An addition operating on a control with explicit binding and position - after -

      - - - -

      Note that the - adddirective identifies the object with - id - a1.b1as its target. -

      - - - - - - -

      The - positionis - afterso both objects inside - addare added after (not inside) the target object. Since the target object is inside another - partin the control, the new additions appear there as well. -

      -

      Note that the result in this case will be schema-invalid since a - propmay not occur directly following a - part. A better result can be obtained (a better target may be defined) by using two - adddirectives, to insert the new - propseparately before any - partobjects in the target. -

      -       -
      -
      - Modifying controls inside controls - -

      OSCAL supports controls inside controls in the form of - controlobjects inside - controlobjects. Because the semantics of the - add and remove directives target any (object) contents of controls, they can be used to target these child controls for modification as well as other contents. Profile Resolution tools MUST be able to correctly handle add directives targetting nested controls. This includes directives that target a child control as well as directives that target a parent control and modify the child.

      -
      -
      -
      - Removing contents from controls -

      Contents inside controls can be removed from them in catalog targets. In combination with adding new contents, this feature can be used to edit controls as well as amend them.

      -

      A - removedirective inside an - alterdirective identifies an object or set of objects inside a control to be removed. It does this using any of five child objects. -

      -

      An object inside the control MUST be removed from the output if and only if it meets all of the criteria given by the child objects of the remove directive. When more than one child appears under the remove directive, an object would need to match all of them, otherwise it is not removed.

      -
        -
      • -

        - The remove directive criteria by-id MUST match an object if and only its value is identical to the id value of that object. Because - idvalues are unique, this criteria will result in the remove directive removing only a single object. -

        -
        • -
      • -

        - The remove directive criteria name-ref MUST match an object if and only its value is identical to the value of that object's name child. -

        -
        • -
      • -

        The remove directive criteria ns-ref MUST match an object if and only its value is identical to the value of that object's ns child.

        -
        • -
      • -

        The remove directive criteria class-ref MUST match an object if and only its value is identical to the value of that object's class child.

        -
        • -
      • -

        The remove directive criteria item-name MUST match an object if and only its value is identical to the value of that object's serialized name. For example, - remove:item-name:prophas the effect of removing all - propobjects from inside the control. -

        -

        In serialization formats that use arrays of objects in the OSCAL model, an object's name MUST be considered the singular form of its containing parent array. For example, in the JSON format, remove:item-name:link would remove all of the objects inside of the links array.

        -
        • -
      -
      -
      -
      -
      - Final Operations -
      - Backmatter Resolution -

      - back-matterin the result is produced by combining all objects within - back-matterin all source catalogs, with the - back-matterin the input profile. -

      -
        -

      • The output's backmatter MUST be generated by copying in each resource object from the backmatters of the imported catalogs/profiles in top-to-bottom order, then by copying in each resource object from the backmatter of the source profile itself. These objects MUST be processed in the order they are given in their respective documents.

        • -
      • -

        If a given - resourcehas the same - uuidas a resource that has already been added, the previous resource MUST be removed, and the more recent one added, unless superceded by other requirements. -

        -
        • -
      • -

        A resource with a child prop of name:keep and value:always MUST NOT be replaced by the addition of another resource, unless the new resource also has a child prop of name:keep and value:always.

        -
        • -
      -

      Tools MAY check for pruning conditions - as resources are added as long as the final result is the same as if the pruning had taken place at the end of all resource addition. -

      -

      Placing the keep always prop on a resource in a catalog has the effect of ensuring it will always appear in the output produced by any profile importing that catalog, even if nothing links to the resource. This version of the resource will also be the one copied, unless a later-imported catalog or importing profile offers its own version marked to keep always.

      -
      -
      - Metadata Resolution -

      The following requirements MUST be followed with regards to the Metadata section of the output catalog:

      -
        -
      • -

        The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid). This UUID may be generated as seen fit by the tool, as long as it is reasonable to assume it is globally unique. It is RECOMMENDED that tools use a combination of meaningful text and a uniquely generated value (Ex. - {{sourceprofilename}}-RESOLVED-{{GUIDv5}}). -

        -
        • -
      • -

        The value of metadata:version in the target MUST be set with a string that identifies the version of that document. The metadata:version SHOULD be used to track updates to this specific output document.

        -
        • -
      • -

        The value of metadata:oscal-version in the target MUST be set with a string that identifies the version of OSCAL used by this tool to resolve the profile (ex. 1.0.0). This value MUST be determined by compiling the oscal-versions from each imported document and the source profile, and taking the most recent minor version. If this version is more recent than what the resolution tool is using, then the value of the output oscal-version MUST be the version that the tool used internally. If any of the above OSCAL versions (imported document versions, source profile version, tool version) are of a different major version (the first digit differs), the tool SHOULD provide an error and cease processing.

        -
        • -
      • -

        The value of metadata:last-modified in the target MUST be set with a valid timestamp representing the time the profile resolution completed.

        -
        • -
      • -

        The value of metadata:source-profile in the target SHOULD be set with a valid URI that points to the profile that resulted in this catalog. If there are privacy or security concerns, the value of metadata:source-profile MAY be set to anything, in which case the simple existence of the source-profile property indicates that this is a resolved profile.

        -
        • -
      • -

        The value of metadata:resolution-tool in the target SHOULD be set with a string that represents the tool that was used to resolve this catalog.

        -
        • -

      • For any metadata:roles or metadata:parties that exist in the source catalogs, if they have a prop child with name:keep and value:always, they are to be copied as is into the output metadata.

        • -
      -

      Beyond these requirements, tools are free to use any and all of the objects inside metadata to provide additional information downstream.

      -

      Because of options in producing metadata and especially the requirement for a timestamp, developers and users should note that two different resolutions of the same profile will not, ordinarily, be identical inside - metadata. -

      -
      -
      - Pruning and Ordering -

      The processor SHOULD prune the resulting output catalog by removing unused objects.

      -
        -
      • -

        Any object that has a child prop with a name of "keep" and a value of "always" MUST NOT be pruned.

        -
        • -
      • -

        If an object was explicitly included in the - , it MUST NOT be pruned. -

        -
        • -
      • -

        If an object was referenced in a custom section of the source profile, it MUST NOT be pruned.

        -
        • -
      • -

        If an object was referenced in the modify section of the source profile, it MUST NOT be pruned. Any objects removed in that section are still removed.

        -
        • -
      • -

        If the object appears in a reference anywhere in the final result catalog, except in other objects that also meet all other pruning criteria, it MUST NOT be removed. A reference to a given object exists if "#{distinctiveID}" appears anywhere, where {distinctiveID} is the distinctive ID of the object - . -

        -
        • -
      -

      Implementers should note that pruning need not take place after all other steps. As long as all above criteria are respected, pruning can happen at any time, and doing so is a likely performance and memory overhead improvement.

      -

      Tools MUST reorder the output catalog into canonical order - , except where this specification provides different ordering requirements. -

      -
      -
      -
      - Items of Note -
      - Distinct ID of Objects -

      Whenever this specification refers to - distinctiveness, it is to be interpreted as is defined in this section with regards to the object in question. -

      -

      For the objects control, param, and group, distinctiveness MUST be determined by the value of the - idchild object. -

      -

      For the object resource, distinctiveness MUST be determined by the value of the - uuid - . -

      -
      -
      - Dealing with Multiple Formats -

      Profile Resolution tools SHOULD be able to handle source profiles, imported catalogs, and imported profiles that are serialized in XML, JSON, or YAML. A different serialization format of any given input MUST NOT result in a differing output catalog.

      -

      In order to help bootstrap this format management, the following resources are provided for implementers:

      -
        -
      • -

        . - -

        -
        • -
      -

      The following sections provide additional requirements and guidance for each format.

      -
      - Requirements and Guidance for XML Output -

      The final Catalog output, if using XML, MUST be valid as defined by the XML model documentation for the OSCAL Catalog. See - the complete XML referencefor model requirements. -

      -
      -
      - Requirements and Guidance for JSON Output -

      The final Catalog output, if using JSON, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. See the - complete JSON referencefor model requirements. -

      -

      The JSON format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order - when outputting a catalog in JSON. -

      -
      -
      - Requirements and Guidance for YAML Output -

      The final Catalog output, if using YAML, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. YAML is considered a simple variation on the JSON format. Beyond cosmetic differences there are no differences in the information structure between these formats. Therefore, the - complete JSON referenceprovides model requirements. -

      -

      The YAML format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order - when outputting a catalog in YAML. -

      -
      -
      - Order of objects in serialization -

      In OSCAL, order of top level objects (those that are direct children of the root element) is considered important only when the XML format is used. To facilitate this, OSCAL provides the concept of - canonical order. This order is provided by the OSCAL Metaschema files for a given document type (see - an overview of Metaschema. -

      -

      When the output format is XML, tools MUST use the OSCAL canonical order as described above. When using the YAML or JSON formats, order conveys no meaning, and is not considered important.

      -
      -
      - Comments in result documents -

      In an XML-based profile resolution, XML comments are one straightforward way for a processor to record events or conditions without affecting the output's nominal semantics. To support this, while two processors are obliged to return the same catalog XML for the same profile XML inputs, they are not required to match one another's comments, white space usage, attribute order, or processing instructions, only each other's objects, attributes and data content.

      -

      One consequence of this is that processes intended to compare two profile resolutions may have to accommodate differences in comments, considering them as insignificant along with other differences in serialization.

      -
      -
      -
      -       - \ No newline at end of file diff --git a/src/specifications/profile-resolution/profile-resolution-specml-working-preview.html b/src/specifications/profile-resolution/profile-resolution-specml-working-preview.html deleted file mode 100644 index b08e0fde7e..0000000000 --- a/src/specifications/profile-resolution/profile-resolution-specml-working-preview.html +++ /dev/null @@ -1,2045 +0,0 @@ - - - - OSCAL Profile Resolution Specification - - - - -
      -
      - -

      1 Notice of Draft Status

      -       -

      Please note that this specification is currently a work in progress and is subject - to change. If you have any feedback or comments, please create an issue at the NIST - OSCAL Github Repository:.

      -
      -
      - -

      2 Abstract

      -       -

      This specification provides the minimal requirements for processing an OSCAL Profile - to create a new OSCAL Catalog Document. This process of applying a profile to a catalog - to create a new catalog is called Profile Resolution. Not all OSCAL Profiles will be resolved, nor are expected to be; however, the resolution - requirements in this document are crucial to understanding the intended functionality - of any given OSCAL Profile. This specification is intended for software developers - who intend to develop an OSCAL Profile Resolver, or for OSCAL Profile authors who - want a more in-depth understanding of profile resolution.

      -
      -
      - -

      3 Introduction

      -       -
      - -

      3.1 Purpose

      -       -

      This document defines the normative requirements for an OSCAL Profile Resolver. Profile - resolution is core to addressing a fundamental OSCAL requirement: the representation - of baselines separately from the control catalogs on which they depend). The requirements - for resolution must therefore be well-defined and deterministic, enabling tool developers - and parties exchanging OSCAL Profiles can work from a common understanding.

      -

      No requirements are placed on implementation-level details, instead, requirements - are laid out as what the output of resolution must look like given a certain input. - By adhering to these requirements OSCAL producers, OSCAL consumers, and any other - members of the OSCAL ecosystem can create and resolve profiles deterministically, - with repeatable results, regardless of the tool used.

      -
      -
      -
      - -

      4 Reading This Document

      -       -
      - -

      4.1 Terminology

      -       -

      Many core OSCAL concepts are defined on the OSCAL Terminology Page. The most important are repeated in this document, but readers should verify their - understanding of all core OSCAL terms before reading this document.

      -

      Additionally, many terms in the wider domain have overloaded definitions. Unless defined - otherwise by OSCAL or explicitly in this document, terms are to be understood as defined - in the NIST CSRC Glossary.

      -
        -
      • -

        profile- an OSCAL Profile Document. Defines a set of inclusions, modifications, and transformations - against a catalog. See OSCAL Profile Model.

        -
        • -
      • -

        catalog- an OSCAL Catalog Document. Contains a well-defined set of controls. See OSCAL Catalog Model.

        -
        • -
      • -

        control- an individual item in an OSCAL Catalog. See NIST Special Publication 800-53r5 for a more in-depth definition.

        -
        • -
      • -

        profile resolution- The process of consuming one or more OSCAL Profiles and the OSCAL Catalogs that - they reference to produce a new tailored catalog. See OSCAL Catalog Model.

        -
        • -
      • -

        source- refers to the profile document that is input into the profile resolution processor. - This is the profile being resolved. In this document, when referring to objects from - the source document, the following style is used:source-object.

        -
        • -
      • -

        target- the intended output of the transformation, a catalog document. In this document, - when referring to objects of a target document, the following style is used:target-object.

        -
        • -
      • -

        directive- refers to an object or combination of objects in source documents, which is designed - to affect a particular outcome in the target catalog. For the most part, directives - are in the source profile document – for example, a set-parameter object in a source profile is a directive to set a parameter value in the target - catalog.

        -
        • -
      • -

        original order- the order of objects as presented in the source document(s). See XYZ.

        -
        • -
      • -

        canonical order- the order of objects as required in the appropriate OSCAL Model (Profile, Catalog, - etc.). This can differ from the above order when converting between "ordered" formats - (ex. XML), and "non-ordered" formats (ex. JSON).

        -
        • -
      -
      -
      - -

      4.2 Requirement Keywords

      -       -

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD - NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are - to be interpreted as described in BCP 14 [RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.

      -
      -
      - -

      4.3 Use of YAML

      -       -

      OSCAL supports a variety of serialization formats, each of which having it's own benefits - and drawbacks. In this document, YAML (YAML Ain't Markup Language) is used to represent - the various objects of the source and target. All examples and in-line references will be represented using YAML 1.2.

      -

      YAML maps cleanly to JSON, thus allowing easy use of existing JSON/XML transformers - where needed. With that in mind, the OSCAL Complete JSON Reference is a valuable resource for understanding the YAML-based information structures used - in this document. All JSON properties and objects defined in the reference equate - to a YAML mapping, list, or dictionary.

      -
      -
      - -

      4.4 Reading YAML Examples

      -       -

      YAML is a particularly human-readable format. For those unfamiliar with the format, - the basics:

      -
        -
      • -

        Each line is a key-value pair, presented as key:value, or as key: with any number of list items on the following lines.

        -
        • -
      • -

        Indentation, spacing, and white space matters. Items below a key and indented one - level in are members (or children) of that key.

        -
        • -
      • -

        List items are represented with a preceding dash - listitemkey:value.

        -
        • -
      -

      The YAML specification is freely available here:YAML 1.2.

      -

      Additionally, in order to unambiguously express information, this specification uses - additional conventions, as described below.

      -

      There are some objects whose values must be determined dynamically at processing time. - The most common example of this is timestamping output as it is processed. In this - case, and any other dynamic-value cases, the expression ${{ }} is used.

      -

      For example:

      -
      -

      Target (catalog):

      - 
      -last-modified: ${{ timestamp }}
      -
      -

      Indicates the last-modified object should be produced with contents generated appropriately, in this case, the - timestamp at the time of processing.

      -

      Some examples may elide content to enhance readability or save space. In these cases, - a YAML comment (any line that starts with #) will be used to explain the elision.

      -

      Finally, although examples are syntactically faithful to OSCAL, they are not necessarily - always formally valid in every respect. For example, OSCAL defines allowed property - names (props) and values, and those rules may not be observed here. Examples are given for purposes - of illustrating profile resolution semantics only, and should not be taken as normative - for any actual use.

      -
      -
      - -

      4.5 Document Layout

      -       -

      The specification is broken into the following major sections:

      -
        -
      • -

        Phases of Profile Resolution- Lays out the necessary steps and phases of profile resolution. As each phase executes, - the processor is understood to be creating and editing an intermediate representation - of the output. There is one section for each of the three main phases.

        -
        • -
      • -

        Target Catalog Structure- Provides the requirements for structuring the final output from the intermediate - representation generated throughout the previous section.

        -
        • -
      -

      Please note: As referenced in the Purpose section [See: 3.1 Purpose], this specification makes no hard requirements on the specifics of implementation. - It is feasible for an implementation to use no intermediate representation, and to - directly and iteratively build the output. As long as all processing and output requirements - are satisfied, any approach is allowed. With that said, the specification has been - laid out to aid in implementation by providing a clear organization as a sequence - of distinct operations.

      -
      -
      - -

      4.6 The Intermediate and Implementation Guidance

      -       -

      The overall intent of this document, in addition to defining strict requirements, - is to provide rough guidelines on implementing an OSCAL Profile Resolution Tool. To - this end, each phase of resolution will be framed as a series of transformations applied - to an internal data structure that is persistent throughout the process. We call this - "the intermediate".

      -

      Any examples that are labelled as "Intermediate" are pseudo-code, designed to represent - how this data structure might look as we apply different operations to it. The example - intermediates are often not valid OSCAL, and are not to be taken as guidance, but - rather a useful visualization tool for implementers.

      -

      The authors believe that applying the steps of resolution in order against this intermediate - representation is the simplest way to achieve full compliance with the specification. - However, there is no requirement to implement profile resolution in this way. Requirements - are given as rules on the output of resolution, and as such, tools can operate any - way they would like internally.

      -
      -
      -
      - -

      5 Phases of Profile Processing

      -       -

      An OSCAL Profile has three major sections, each which correspond to a phase of profile - resolution. In order to complete the profile resolution process, each section must - be fully parsed and a catalog output created.

      -

      req-phase-orderIt is strongly RECOMMENDED that implementations execute the following steps in the - order that they are provided here (import, merge, modify). While it is possible to achieve compliance with a non-standard approach, the iterative - nature of profile resolution lends itself to linear processing.

      -

      The three steps are import;merge; and modify. In brief:

      -
        -
      • -

        import- identifies one or more control sources (catalogs or profiles) and defines the controls - within them to be included in the result catalog. If nothing is imported, no resulting - catalog is produced. Invoked by import directives in source profiles;

        -
        • -
      • -

        merge- designates the rules for how controls will be organized (ordered and/or grouped) - and merged (addressing conflicts or ambiguities) in the result catalog. Controlled - by the merge directive in source profiles; if none are included, default merge rules are used;

        -
        • -
      • -

        modify- indicates how controls and their parameters in the underlying catalog are to be - altered, edited, amended or added in the final result catalog. Logical evaluation - and parameter constraints provide advanced processing. Controlled by the modify directive in source profiles. If a modify directive is not provided, no changes will be made to the controls that have been - imported/merged.

        -
        • -
      -

      As described in the previous section, when resolved, an OSCAL Profile takes the form - of an OSCAL Catalog. The phases described below will produce outputs conforming to - the catalog model.

      -
      -
      - -

      6 Import Phase

      -       -

      A profile begins by listing a set of catalogs and/or profiles to be imported. Each - is represented by a resolvable resource URI and a directive specifying which controls - to import from that resource. These resources may be available as static resources, - or they may be produced dynamically on request; such as is the case when a profile - is imported. Imports are given in sequence after the metadata:

      -
      -

      Source (profile):

      - 
      -profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: ${{ catalog URI }}
-      include-controls: ${{ list of selected controls }}
-    - href: ${{ profile URI }}
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      In an import directive, the reference to the resource to be imported appears on an - href child object. It takes either of two forms, external or internal:

      -

      An external reference appears as an absolute or relative URL:

      -
      -

      Source (profile):

      - 
      -profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: >-
-        https://github.com/usnistgov/oscal-content/tree
-        /master/nist.gov/SP800-53/rev4/yaml/NIST_SP-800-53_rev4_catalog.yaml
-      include-controls: ${{ list of selected controls }}
-    - href: "../../NIST_SP-800-53_rev5_catalog.yaml"
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      While an internal reference appears as below (see [See: 6.1.3 Internal References]):

      -
      -

      Source (profile):

      - 
      -profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: #80052rev4
-      include-controls: ${{ list of selected controls }}
-    - href: #80052rev5
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      All import directives will contain either include-all: ~ or include-controls. These directives indicate which controls from the imported document are explicitly - selected [See: 6.2 Including Controls].

      -

      The following section contains requirements for processing the import child of a source profile

      -
      - -

      6.1 Import href Requirements

      -       -
      - -

      6.1.1 Import URI Resolution

      -       -

      req-uri-resolveTools MUST resolve URIs by following Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST - instead be resolved as defined in [See: 6.1.3 Internal References].

      -
      -
      - -

      6.1.2 Import Resource Acquisition

      -       -

      req-uri-aquireTools MUST acquire resources at the resolved URI by following Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST - instead be acquired as defined in [See: 6.1.3 Internal References].

      -

      req-uri-baseFor the purposes of resolving URIs using the above specification, the Base URI MUST - be considered to be the absolute URI of the containing profile.

      -

      req-uri-errorIn the case that acquiring a resource fails, the tool MUST cease processing and provide - an error. In order to ensure profile resolution results in the same catalog regardless - of which tool resolves it, all imports must successfully resolve. While this may cause - inconvenience if resources are frequently not available, it ensures interoperability.

      -

      Note that receiving a cached version of an import, or resolving an import that is - otherwise unavailable through some other (but automatic) means still satisfies the - above requirement. This specification does not put requirements on the precise function - of the import, as long as the correct document is retrieved.

      -
      -
      - -

      6.1.3 Internal References

      -       -

      URI Fragments in OSCAL represent internal references to other OSCAL objects in the - same document. These references follow the pattern of "#{{objectID}}". For example, - the URI Fragment "#param1" is referencing the Parameter with unique ID "param1".

      -

      req-internalIn the context of the Import Phase, internal references will only appear as a reference - to a profile or catalog that is in the resources section of the source. When tools encounter such a reference, they MUST locate the - object in resources with the matching ID value, and resolve the import using the rlink URI and the above resolution requirements.

      -

      req-internal-errorIf the object fetched cannot be found or is not a valid OSCAL object, the tool MUST - cease processing and provide an error.

      -
      -

      Source (profile):

      - 
      -profile:
-  metadata: ~
-  imports:
-    - href: "#nist-sp800-53_catalog"
-      include-controls: ${{ list of selected controls }}
-    
-  # Content Elided
-    
-  backmatter:
-    resources:
-      - uuid: "nist-sp800-53_catalog"
-        description: "NIST SP 800-53 rev5 OSCAL format, on Github."
-        rlinks:
-          - rlink:
-              href: >-
-                https://github.com/usnistgov/oscal-content/tree
-                /master/nist.gov/SP800-53/rev4/xml/NIST_SP-800-53_rev5_catalog.xml   
-
      -
      -
      -
      - -

      6.1.4 Resolving Imports of Profiles

      -       -

      req-circular-resolveIf the resource acquired is an OSCAL Profile, the tool MUST apply this specification - to resolve it, then continue processing having imported the resulting catalog.

      -

      req-circular-catalogWhen a profile imports a profile, the subordinate profile SHOULD be resolved first - into a catalog using this specification, before it is imported. This presents the possibility of circular imports, when a profile is directed to - import itself either directly or indirectly.

      -

      A circular import occurs when a profile imports an already imported profile, which was called at an - earlier place in the import hierarchy. For example, if profile A imports profile B, - and profile B imports profile A, the second import is circular. (An import at the - top can only be circular if a profile tries to import itself.) If A imports B, B imports - C and C imports A, C’s import is circular.

      -

      Note that an import can only be circular within the context of processing a particular - profile. In the last example, C’s import would not be circular if invoked in the context - of resolving B by itself.

      -

      req-circular-errorIf a processor encounters a circular import as described above (self-imports are inherently circular), the processor MUST cease - processing and generate an error.

      -

      A profile identified as home_profile.yaml imports another one identified as circular_profile.yaml:

      -
      -

      Source (profile):

      - 
      -profile:
-  id: "home_profile.yaml"
-  metadata: ~
-  imports:
-    - href: "circular_profile.yaml"
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      In turn this file invokes home_profile.xml:

      -
      -

      Source (profile):

      - 
      -profile:
-  id: "circular_profile.yaml"
-  metadata: ~
-  imports:
-    - href: "home_profile.yaml"
-      include-controls: ${{ list of selected controls }} 
-
      -
      -

      Once detected, this circular import will result in an error and no further processing - will take place.

      -
      -

      Target (catalog):

      - 
      -# Import at href: "circular_profile.yaml" failed.
-  # Reason: Error during profile import:
-  # Import at href: "home_profile.yaml" failed.
-  # Reason: Circular import 
-
      -
      -
      -
      - -

      6.1.5 Multiple imports

      -       -

      Each import directive is processed to produce a set of controls. Note that this occurs - even if the same catalog is imported multiple times: each distinct import collects - controls into a separate selection:

      -
      -

      Source (profile):

      - 
      -profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: "#catalog"
-      include-controls:
-       - with-ids:
-          - ac-1
-          - ac-2
-    - href: "#catalog"
-      include-controls:
-       - with-ids:
-          - ac-3
-          - ac-4 
-
      -
      -
      -

      Intermediate (catalog):

      - 
      -intermediate:
-  inclusions:
-    - id: ${{uuid of #catalog}}
-      included-controls:
-          - ac-1
-          - ac-2
-    - id: ${{uuid of #catalog}}
-      included-controls:
-          - ac-3
-          - ac-4 
-
      -
      -

      The control inclusions are combined and collapsed in the next phase of processing,merge(see [See: 7 Merge Phase]) .

      -

      Multiple imports against the same resource are allowed, and would most commonly occur - when the profile author is using [See: 6.1.6 Mapping Controls] to create very specific output. Multiple imports may result in outputs with clashing - control IDs if mapping or the merge directive is not set correctly.

      -
      -
      - -

      6.1.6 Mapping Controls

      -       -

      The optional mapping child of a given import provides a simple ID remapping for objects included from that specific import. This - provides the means for profile authors to proactively avoid clashing IDs of controls - and other objects.

      -

      The Mapping section consists of 5 optional subsections, each covering a particular - type of object. Each subsection is a list of ID mappings to be applied for objects - that are the parent object type.

      -

      When encountering a given mapping instruction, processors:

      -
        -
      • -

        MUST change the distinctive ID of that object to be equal to the value of the to object.

        -
        • -
      • -

        MUST update all known references to the old ID in other included content, allowing - the new ID to be used in subsequent profile sections.

        -
        • -
      -

      Since mapping is a self contained process inside each import, the rest of this specification - will continue to reference IDs with the assumption that mapping has already been applied - if it was present. Since mapping is most commonly used to avoid clashing IDs, processors - should take care to not handle duplicate IDs until after mapping is complete.

      -

      Below is a simple example of mapping. The second import is included controls from a different catalog whose ID values happen to collide. - Knowing this, the profile author has remapped those IDs to new values.

      -
      -

      Source (profile):

      - 
      -profile:
-  uuid: ~
-  metadata: ~
-  imports:
-    - href: "#catalog"
-      include-controls:
-       - with-ids:
-          - ac-1
-          - ac-2
-    - href: "#catalog2"
-      include-controls:
-       - with-ids:
-          - ac-1
-          - ac-2
-      mapping:
-       - controls:
-          - from: ac-1
-            to: map-ac-1
-          - from: ac-2
-            to: map-ac-2
-
      -
      -

      Using the intermediate approach, an internal data structure resembling the following - would result from the above profile:

      -
      -

      Intermediate (catalog):

      - 
      -intermediate:
-  metadata: ~
-  inclusions:
-    - id: ${{uuid of #catalog}}
-      included-controls:
-          - ac-1
-          - ac-2
-    - id: ${{uuid of #catalog2}}
-      included-controls:
-          - map-ac-1
-          - map-ac-2 
-
      -
      -
      -
      -
      - -

      6.2 Including Controls

      -       -

      Each import contains directives on which controls from the imported catalog are to - be fetched and used for further processing. Throughout the rest of the document we - will refer to this as "inclusion". If a control is included, and the source profile - makes no other changes to it, it will be present in the output. Exclusion directives - in this section, as well as directives in the following two major sections (merge - and modify), may make changes to an included control or group that could cause it - to appear differently, or not at all, in the output. Using the intermediate implementation - approach, any control(s) that are included would be extracted from the referenced - catalogs, any applicable mappings would be applied, then the controls(s) would be - stored.

      -
      - -

      6.2.1 include-all

      -       -

      req-include-allWhen an import provides the include-all directive, ALL controls and groups in the referenced document (including nested controls) - MUST be included.

      -
      -

      Source (profile):

      - 
      -include-all: ~
      -
      -
      -
      - -

      6.2.2 include-controls plus with-id

      -       -

      req-include-by-idWhen an import provides the include-controls directive, with a with-id child, all controls in the referenced document whose id match one of the listed id values MUST be included.

      -
      -

      Source (profile):

      - 
      -include-controls:
-  - with-ids:
-    - id: ac-1
-    - id: ac-2
-
      -
      -
      -
      - -

      6.2.3 include-controls plus matching

      -       -

      Controls may also be included using match patterns against their IDs. This is useful - because related controls (either in a hierarchy, or together in a group) frequently - have related IDs as well.

      -

      req-include-by-matchWhen an import provides the include-controls directive, with a matching child, all controls in the referenced document whose id matches one of the listed pattern values (Glob matching) MUST be included.

      -

      req-include-by-match-emptyIf a matching object is provided with no pattern, it MUST be treated as matching nothing. While not providing a pattern is technically - valid, resolution tool implementers should be aware that it is generally undesirable, - and warnings or notices to the user may be appropriate.

      -
      -

      Source (profile):

      - 
      -include-controls:
-  - matching:
-    - pattern: "ac*" 
-
      -
      -
      -
      - -

      6.2.4 Dealing with Nested Controls and Groups

      -       -

      In OSCAL, controls may contain child controls. For instance, in SP 800-53 many controls - are supplemented with control enhancements; in OSCAL these are represented as child - controls within parent controls. So parent AC-2 (in a given catalog) has children - AC-2(1) through AC-2(13), for example.

      -

      By default, inclusion of a control also causes any of that control's ancestors (or - parents) to also be included. By default, inclusion of a control DOES NOT cause the - inclusion of any descendants (or children) of that control to be included. This applies - to both controls and groups.

      -

      This default behavior can be modified by the following two optional children of the - include-controls object.

      -
      - -
      6.2.4.1 with-child-controls
      -       -

      Child controls are, for the most part, treated the same as top level controls: they - can be explicitly included using the selection directives above. As a shortcut to - manually including all of the desired descendant controls of a given control, OSCAL - provides the "with-child-controls" option. "with-child-controls" appears as a child - object under a given inclusion directive, and defines additional behavior that is - to be executed alongside the parent inclusion.

      -

      req-with-child-controls-yesA with-child-controls: yes directive on an include-controls indicates that all descendant controls of the included control MUST also be included.

      -

      req-with-child-controls-noA with-child-controls: no directive on an include-controls indicates that ONLY the matching control is included, any descendant children MUST - NOT be included.

      -

      req-with-child-controls-noneIf no with-child-controls is provided, the processor MUST consider the directive as being equivalent to one - having with-child-controls:no.

      -
      -
      - -
      6.2.4.2 with-parent-controls
      -       -

      Although similar to the above with-child-controls, the optional with-parent-controls applies to parents of the included control, and has the opposite default behavior. - In order to maintain the structure of the source catalog, profile resolution includes - all parents of an included control by default. If a profile author wants to change - this structure, they could use an exclude directive that lists all of the undesired - parents. As a shortcut for this,with-parent-controls provides the following functionality:

      -

      req-with-parent-controls-yesA with-parent-controls: yes directive on an include-controls indicates that all parent controls of the included control MUST also be included.

      -

      req-with-parent-controls-noA with-parent-controls: no directive on an include-controls indicates that ONLY the matching control is included, any parents MUST NOT be included.

      -

      req-with-parent-controls-noneIf no with-parent-controls is provided, the processor MUST consider the directive as being equivalent to one - having with-parent-controls:yes.

      -
      -
      -
      - -

      6.2.5 exclude-controls

      -       -

      Exclusions work the same way as inclusions, except with the opposite effect - the - indicated control(s) do not appear in the target catalog.

      -

      req-excludeAny control designated to be both included and excluded, MUST be excluded. This holds - irrespective of the specificity of the selection for inclusion or exclusion. For example, if AC-1 is included by id ac-1 and excluded by matching ac.*, it is excluded.

      -

      req-exclude-additionalWhen exclude-controls has at least one with-ids or matching directive, the processor MUST follow the same rules as defined in the relevant sections - above for these directives, but exclude instead of include any controls. All optional - features (with-child-controls, etc.) also apply to exclusion directives.

      -
      -
      - -

      6.2.6 Redundant Inclusions and Exclusions

      -       -

      req-redundantA given import may have any number of inclusion statements and any number of exclusion statements. - Their effect is cumulative; any control that is included (or excluded) more than once - MUST be considered to be included (or excluded) only once. In other words, a given - control being included or excluded more than once has no effect. Exclusion still takes - priority over inclusion (see above).

      -

      Note that this requirement only applies to controls included within the context of - a single import. Controls with duplicate IDs included under a different import are not discarded. Also note that this redundancy pruning happens after any relevant - mappings have been applied.

      -
      -
      - -

      6.2.7 Handling Params

      -       -

      Any param that is not directly under a control is referred to as a loose param.

      -

      req-loose-paramAll loose params from both imported documents and the profile source MUST be included. - These params will be kept in the final output if document contains any references - to them, and discarded otherwise. See [See: 9.3 Pruning and Ordering]. Since new references can be created during the modify phase, tools should be careful not to prune params without fully understanding the - final state of the output document.

      -
      -
      - -

      6.2.8 Handling Groups

      -       -

      Some source catalogs use group objects to place controls into arbitrary groupings. Tools will need to be aware of - these groups when executing the "merge" phase below, as they will duplicated into - the output under the "as-is" mode and can be referenced in "custom" mode. The naïve - intermediate approach would keep all groups until all other phases are complete, but - implementations may find it more performant to look ahead and prune unused groups - early.

      -
      -
      - -

      6.2.9 Avoiding Implementation Pitfalls

      -       -

      In order to ensure that implementers have as much flexibility as possible, requirements - in this section have purposefully been kept minimal. Below are some common issues - for implementers to be aware of:

      -
        -
      • -

        The ordering and hierarchical organization of included controls as they were present - in the original catalog may be used later in the resolution process. Specifically, - if the profile is using the "as-is" structuring directive, the ordering and organziation - of the output should match the source catalog as closely as possible. Implementations - may want to track this information, or look ahead to see what structuring mode is - being used. Note that "as-is" also requires implementations to replicate any use of - the group element.

        -
        • -
      -
      -
      -
      - -

      6.3 Wrapping up the Import Phase

      -       -

      At this point all requirements for content importing and control inclusion have been - covered. If using the intermediate approach, the processor should have an intermediate - that contains: a set of included controls and all of their child informational (non-control, - non-group) objects, any relevant group objects and their informational content, and a set of included "loose params"[See: 6.2.7 Handling Params](zero to many). The general structure of the intermediate would match that of the - imported catalogs (i.e. Nested controls remain nested, grouped controls remain grouped).

      -
      -
      -
      - -

      7 Merge Phase

      -       -

      Profiles may contain a merge section, where directives are given to instruct the processor how to combine the - set of included objects collected during the Import Phase.merge has two parts: a "combine" directive, and a "structuring" directive.

      -

      req-merge-orderIt is RECOMMENDED that tools apply the "combine" directive to the intermediate generated - by the Import phase first, then apply the "structuring" directive.

      -

      The following section contains requirements for processing the merge child of a source profile.

      -
      - -

      7.1 The "combine" Directive

      -       -

      combine is an optional child of merge that provides the rules for dealing with objects that have duplicate (or clashing) - distinct IDs [See: 10.1 Distinct ID of Objects].

      -

      There are two valid combination methods provided by OSCAL, provided by the method child of combine:

      -
        -
      • -

        use-first: Use the first definition - the first control with a given ID is used; subsequent - ones are discarded

        -
        • -
      • -

        keep: Keep - controls with the same ID are kept, retaining the clash

        -
        • -
      -

      req-merge-combineNote that "merge: combine" is deprecated, and MUST be considered undefined behavior - when encountered.

      -

      In order to apply the combination method, IDs of each control explicitly included - are compared against one another. As IDs are unique across entire OSCAL documents, - different imports or any groupings have no bearing on collision. Processing requirements - for each method are described below.

      -
      - -

      7.1.1 No Combine Directive

      -       -

      req-merge-noneIf no merge directive is given in the profile, or if a merge is given without a combine, merge conflicts MUST be treated as if method: keep was given. For example, a profile with no merge directive:

      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~ 
-
      -
      -

      is the same as

      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~
-  merge:
-    combine:
-      method: keep
-      flat: ~ 
-
      -
      -
      -
      - -

      7.1.2 method:keep

      -       -

      req-merge-keepWhen a merge is indicated by method:keep, or when no merge directive is given, the keep combination rule is used. Any controls with the same distinctive ID [See: 10.1 Distinct ID of Objects] MUST NOT not merged. (They are kept.)

      -
      -

      Source (profile):

      - 
      -merge:
-    combine:
-      method: keep 
-
      -
      -

      Under this directive, colliding controls will result in invalid results, as they will - both appear in the results with the same ID. Accordingly, this setting may be useful - in ensuring integrity of references to controls as given in the profile: if any included - control is called only once, clashing controls will not be produced and validation - will succeed.

      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-2
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-2 
-  merge:
-    combine:
-      method: keep
-
      -
      -

      In the intermediate (showing control inclusions):

      -
      -

      Intermediate (catalog):

      - 
      -intermediate:
-  inclusions:
-    - explicitly-included-controls:
-          - ac-1
-          - ac-2
-          - ac-1
-          - ac-2 
-
      -
      -

      In this case, downstream errors should be expected: the two ac-1 controls clash with each other, as do the two ac-2 controls.

      -

      req-merge-keep-warningProcessors SHOULD provide a warning under the merge:keep directive when duplicate - controls are detected. req-merge-keep-errorThe processor MAY throw an error and cease processing (short-circuiting a certain - future error) when duplicate controls are detected under the merge:keep directive.

      -
      -
      - -

      7.1.3 method:use-first

      -       -
      -

      Source (profile):

      - 
      -merge:
-    combine:
-      method: use-first 
-
      -
      -

      req-merge-use-firstWhen the use-first combination rule is applied, and controls that share a distinctive ID are found, - the first control encountered MUST be kept, the rest MUST be discarded.First MUST be determined by a top-down, depth-first traversal of the source profile's import - hierarchy.

      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-3
-    - href: #catalog1
-      include-controls:
-        - with-ids
-            id: ac-1
-            id: ac-2 
-  merge:
-    combine:
-      method: use-first
-
      -
      -

      In the intermediate(showing control inclusions):

      -
      -

      Intermediate (catalog):

      - 
      -intermediate:
-  inclusions:
-    - explicitly-included-controls:
-          - ac-1 (From catalog1)
-          - ac-3
-          - ac-2 
-
      -
      -
      -
      - -

      7.1.4 method:merge

      -       -

      Deprecated, unspecified behavior.

      -
      -
      -
      - -

      7.2 The "structuring" Directive

      -       -

      This section describes how a profile may dictate the structure of the target catalog, apart from its metadata or back-matter.req-stuctureOptionally, one of three "structuring" directives can be included as a child of merge:flat,as-is and custom. When one of these appears, it is the selected structuring directive. If more than - one appears, processors MUST generate an error and cease processing. Processing requirements for each are given below:

      -
      - -

      7.2.1 No Structuring Directive

      -       -

      req-structure-noneIf no merge directive is given in the profile, or if a merge is given without a structuring directive, structuring the output MUST be treated - as if the structuring directive flat was given. For example, a profile with no merge directive:

      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~ 
-
      -
      -

      is the same as

      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalogURI
-      include-all: ~
-  merge:
-    combine:
-      method: keep 
-      flat: ~ 
-
      -
      -
      -
      - -

      7.2.2 "flat"

      -       -

      req-merge-flatProfiles with the "flat" merge directive MUST be resolved as unstructured catalogs, - with no grouping or nesting of controls.

      -

      req-merge-flat-listUnstructured catalog output MUST be produced by adhering to the following requirements:

      - -

      An example of flat structuring is provided below

      -
      -

      Source (catalog):

      - 
      -catalog:
-  groups:
-    - groupA
-      - ac-1
-      - ac-2
-    - groupB
-      - bc-1 
-
      -
      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalogURI
-      include-controls:
-        with-ids:
-          - ac-1
-          - ac-2
-          - bc-1
-  merge:
-    combine:
-      method: keep 
-      flat: ~ 
-
      -
      -
      -

      Intermediate (catalog):

      - 
      -intermediate:
-  controls:
-    - ac-1
-    - ac-2
-    - bc-1 
-
      -
      -
      -
      - -

      7.2.3 as-is

      -       -

      An as-is directive is used to reproduce the structure of the source documents in the target - catalog.

      -

      id-structure-as-is-listProcessors MUST handle the as-is directive by adhering to the following requirements:

      -
        -
      • -

        id-structure-as-is-list-1All included controls are output to the target, keeping the structure of the groups - and nested controls. Any group that holds an included control MUST appear in the output - with all of its non-control children intact. If an included control has a parent control - that was not included, that control's output location is "up-leveled", or made equal - to the non-included parent. This applies recursively until the control is directly - under either "catalog" or another included control.

        -
        • -
      • -

        id-structure-as-is-list-2Any included "loose params" are output to the target as a flat list directly under - "catalog".

        -
        • -
      -

      Example:

      -
      -

      Source (catalog):

      - 
      -catalog:
-  groups:
-    - groupA
-      - ac-1
-      - ac-2
-    - groupB
-      - bc-1 
-
      -
      -
      -

      Source (profile):

      - 
      -profile:
-  imports:
-    - href: #catalogURI
-      include-controls:
-        with-ids:
-          - ac-1
-          - ac-2
-          - bc-1
-  merge:
-    combine:
-      method: keep 
-      as-is: ~ 
-
      -
      -
      -

      Intermediate (catalog):

      - 
      -intermediate: 
-#In this approach, the original hierarchy of the controls under the groups is stored,
-#but is not shown in this example.
-  controls:
-    - ac-1
-    - ac-2
-    - bc-1
-  groups:
-    - groupA
-    - groupB 
-
      -
      -
      -
      - -

      7.2.4 custom

      -       -

      The custom directive provides the target catalog with a custom structure. A one-to-one mapping - of the desired structure of the target catalog is defined alongside control matching - instructions, resulting in a strictly controlled output catalog.

      -
      - -
      7.2.4.1 Creating Custom Groups
      -       -

      req-custom-groupA group object given under custom MUST result in a group with the exact same content (excluding insert-controls) in the target catalog.

      -

      req-custom-group-contentsIf the ID of the group matches the ID of a group that has been included during the - import phase, all contents inside the group, including title,param,prop and part objects MUST be copied into the target, appearing in the same order as in the source.

      -

      Note that groups defined in custom may vary from fully featured to minimally instantiated. This includes arbitrary nesting - of such groups inside of one another. No groups other than those explicitly declared - should appear in the output catalog.

      -
      -
      - -
      7.2.4.2 Inserting Controls
      -       -

      The insert-controls directive may appear anywhere under custom, whether as a direct child or inside any of the defined groups. Inside insert-controls,include-controls and include-all from the Import Phase [See: 6 Import Phase] are used with the same basic behavior to configure which controls are selected and - inserted at the current location.

      -

      In order to provide clarity, controls that match the various conditions of these inclusion - directives inside the custom object will be referred to as "selected" instead of "included". Only directly selected - controls will appear in the target catalog.

      -

      req-custom-selectWhen processing the control selection of a custom element, the behavior defined in this section MUST be followed to generate the output.

      -

      A insert-controls with an include-controls child results in the following behavior:

      -
        -
      • -

        with-id results in selecting and inserting, at that point inside the new grouping, the included - controls with the id given by with-id. They should be given in the same order as they appear in the control selection(s).

        -
        • -
      • -

        A matching directive results in selecting and inserting, at that point inside the new grouping, - all included controls whose id match, as a Glob expression, the pattern given in the pattern. They are given in the same order as they appear in the input control selection(s).

        -
        • -
      -

      An insert-controls with an include-all child results in all included controls being selected and inserted. They are given - in the same order as they appear in the input control selection(s).

      -

      insert-controls can also indicate the order that the selected controls are to be emitted in the result - catalog using an order child. Three values MUST be supported and handled as specified below:

      -
        -
      • -

        ascending will sort all selected controls into ascending alphanumeric order by their ID.

        -
        • -
      • -

        descending will sort all selected controls into descending alphanumeric order by their ID.

        -
        • -
      • -

        keep indicates that controls should be inserted in the order of their appearance, using - a depth-first traversal of the source profile's imports.

        -
        • -
      -

      req-custom-select-ignoreIn the case that a control selection matches none of the included controls, it MUST - be ignored. req-custom-select-warningIn the case that a control selection matches none of the included controls, a warning - SHOULD be provided. If a control that was included by the Import Phase is never selected, no error occurs, - that control simply does not appear in the output catalog.

      -
      -
      -
      -
      - -

      7.3 Wrapping up the Merge Phase

      -       -

      After the merge phase, the intermediate should now closely resemble the content and - structure of the final output catalog. Controls and groups have been included, remapped, - de-duplicated, then placed into their final location within the output's structure. - Note: there is still an opportunity for included controls or groups to become referenced; - and therefore, not eligible for pruning [See: 9.3 Pruning and Ordering] in the next phase.

      -

      Regardless of any merge directives, there also likely remains "loose params" that - have been propagated forward; these too must be persisted.

      -
      -
      -
      - -

      8 Modify Phase

      -       -

      There are two ways profiles may further modify the results of profile resolution: - setting parameters, and altering controls. These activities are defined as two child - objects inside the third step of profile resolution, the Modify Phase.

      -

      The following section contains requirements for processing the modify child of a source profile.

      -
      - -

      8.1 Setting Parameters

      -       -

      Modification of parameter settings is indicated using the set-parameter object under modify. For this section, a given set-parameter object will be referred to as the source.

      -

      Profile Resolution Tools MUST adhere to the following requirements for processing - "set-parameter":

      -
        -
      • -

        First, the list of included params (among "loose params" and remaining included controls - and groups) is searched for a param who has an "id" equal to this object's "param-id". - This is the "target".req-modify-set-param-warningIf no such parameter is found, a warning SHOULD be issued. req-modify-set-param-id-ignoreIf no such parameter is found, processing MUST still continue.

        -
        • -
      • -

        req-modify-set-param-objects1For the following objects inside the source: class, depends-on, label, usage, values, - select; the object MUST be copied into the target from the source, first removing - any existing objects with the same name.

        -
        • -
      • -

        req-modify-set-param-objects2For the following objects inside the source: props, links, constraints, guidelines; - the contents of the object MUST be added to the contents of the target object of the - same name. If no such object exists in the target, it is created.

        -
        • -
      • -

        req-modify-set-param-objects3For the following objects inside the source: prop, link; the object MUST be copied - into the target from the source, first removing any existing objects with the same - distinctive ID. ([See: 10.1 Distinct ID of Objects]).

        -
        • -
      • -

        req-modify-param-multiIf more than one set-parameter directive is given for the same parameter, all MUST BE applied, in the sequence given - in the profile.

        -
        • -
      -
      -
      - -

      8.2 Altering controls

      -       -

      A control can be altered by an alter object inside "modify". The control-id child object under the alter indicates the control to which the alteration is applied.

      -
      - -

      8.2.1 Adding contents to controls

      -       -

      Contents may be added to controls using an add directive inside an alter directive. - There are two forms of alteration: with implicit and explicit bindings.

      -
      - -
      8.2.1.1 Implicit binding
      -       -

      req-modify-alter-add-implicitAn add directive with no by-id child MUST be considered an implicit binding, and will apply to the control as a - whole.

      -

      req-modify-alter-add-implicit0contentsThe contents of an implicitly bound add directive MUST be added to the control contents - in the target, either after its title when position is starting, or at the end if its position is ending, or if no valid poisition is given.

      -

      req-modify-alter-add-implicit-positionWhen an add directive is implicitly bound, the position values before and after MUST be treated like starting and ending, respectively.

      -

      Control contents in catalogs must appear in the order title, param, prop, link, part, control per the OSCAL model documentation.req-modify-alter-add-implicit-orderAfter processing an implicitly bound add directive, the control contents MUST be sorted - to appear in the required order: a new prop appears after any prop already in the control, when position is ending, or not given, or before any prop in the control when position is starting.

      -

      An addition operating on a control with implicit binding and position starting

      -
      -

      Source (catalog):

      - 
      -control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready 
-
      -
      -
      -

      Source (profile):

      - 
      -alter:
-  control-id: a1
-  add:
-    position: starting
-    props:
-      - name: basis
-        value: enumerated
-    parts:
-      - name: caution
-        prose: \\n\\nPending scheduled testing. 
-
      -
      -
      -

      Target (catalog):

      - 
      -control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: basis
-      value: enumerated
-    - name: status
-      value: ready
-  parts:
-    - name: caution
-      prose: \\n\\nPending scheduled testing. 
-
      -
      -

      Position is starting but the new part is added after the existing prop, because prop objects must always occur first.

      -

      An addition operating on a control with implicit binding and position ending

      -
      -

      Source (catalog):

      - 
      -control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready 
-
      -
      -
      -

      Source (profile):

      - 
      -alter:
-  control-id: a1
-  add:
-    position: starting
-    props:
-      - name: basis
-        value: enumerated
-    parts:
-      - name: caution
-        prose: \\n\\nPending scheduled testing. 
-
      -
      -
      -

      Target (catalog):

      - 
      -control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready
-    - name: basis
-      value: enumerated
-  parts:
-    - name: caution
-      prose: \\n\\nPending scheduled testing. 
-
      -
      -

      The position is ending so the new prop appears after the existing prop.

      -
      -
      - -
      8.2.1.2 Explicit binding
      -       -

      An explicit binding on an addition permits inserting new contents anywhere in a control, - not only at the top level.req-modify-alter-add-explicitAn add directive with a by-id child MUST be considered an explicit binding, and applies to only a single object - inside the control. req-modify-alter-add-explicit-idWhen an add directive is explitly bound, the value of the by-id child MUST correspond to the value of an id on an object inside the control, and not the control itself. req-modify-alter-add-explicit-id-ignoreIf by-id does not correspond to such a value, the add directive MUST be considered inoperative and ignored. req-modify-alter-add-explicit-id-warningAn inoperative add directive MAY result in a warning.

      -

      The object with id equal to the value of by-id is considered the target of the addition.

      -

      req-modify-alter-add-explicit-insideWhen position has a value of starting or ending, the contents of the source MUST be added inside the target, either at the start - or end of its contents, respectively.

      -

      req-modify-alter-add-explicit-outsideWhen position has a value of before or after, the contents of the source MUST be added outside the target, either directly before - or after it, respectively.

      -

      An addition operating on a control with explicit binding and position after

      -
      -

      Source (catalog):

      - 
      -control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready
-  parts:
-    - name: recommendations
-      id: a1.b
-      parts: 
-        - name: task1
-          id: a1.b1
-          prose: Collect recycling for pickup
-        - name: task2
-          id: a1.b2
-          prose: Sweep surfaces free of dust
-
      -
      -

      Note that the add directive identifies the object with id a1.b1 as its target.

      -
      -

      Source (profile):

      - 
      -alter:
-  control-id: a1
-  add:
-    position: after
-    by-id: a1.b1
-    props:
-      - name: basis
-        value: allocated
-    parts:
-      - name: caution
-        prose: Unavailable on weekends 
-
      -
      -
      -

      Target (catalog):

      - 
      -control:
-  id: a1
-  title: Basic precautions
-  props:
-    - name: status
-      value: ready
-  parts:
-    - name: recommendations
-      id: a1.b
-      parts: 
-        - name: task1
-          id: a1.b1
-          prose: Collect recycling for pickup
-        - name: caution
-          prose: Unavailable on weekends
-        - name: task2
-          id: a1.b2
-          prose: Sweep surfaces free of dust
-      props:
-        - name: basis
-          value: allocated
-
      -
      -

      The position is after so both objects inside add are added after (not inside) the target object. Since the target object is inside - another part in the control, the new additions appear there as well.

      -

      Note that the result in this case will be schema-invalid since a prop may not occur directly following a part. A better result can be obtained (a better target may be defined) by using two add directives, to insert the new prop separately before any part objects in the target.

      -
      -
      - -
      8.2.1.3 Modifying controls inside controls
      -       -

      OSCAL supports controls inside controls in the form of control objects inside control objects. Because the semantics of the add and remove directives target any (object) contents of controls, they can be used - to target these child controls for modification as well as other contents.req-modify-alter-add-nestedProfile Resolution tools MUST be able to correctly handle add directives targetting - nested controls. This includes directives that target a child control as well as directives - that target a parent control and modify the child.

      -
      -
      -
      - -

      8.2.2 Removing contents from controls

      -       -

      Contents inside controls can be removed from them in catalog targets. In combination - with adding new contents, this feature can be used to edit controls as well as amend - them.

      -

      A remove directive inside an alter directive identifies an object or set of objects inside a control to be removed. - It does this using any of five child objects.

      -

      req-modify-alter-remove-matchAn object inside the control MUST be removed from the output if and only if it meets - all of the criteria given by the child objects of the remove directive. When more than one child appears under the remove directive, an object would need - to match all of them, otherwise it is not removed.

      -
        -
      • -

        req-modify-alter-remove-by-idThe remove directive criteria by-id MUST match an object if and only its value is identical to the id value of that object. Because id values are unique, this criteria will result in the remove directive removing only - a single object.

        -
        • -
      • -

        req-modify-alter-remove-name-refThe remove directive criteria name-ref MUST match an object if and only its value is identical to the value of that object's - name child.

        -
        • -
      • -

        req-modify-alter-remove-ns-refThe remove directive criteria ns-ref MUST match an object if and only its value is identical to the value of that object's - ns child.

        -
        • -
      • -

        req-modify-alter-remove-class-refThe remove directive criteria class-ref MUST match an object if and only its value is identical to the value of that object's - class child.

        -
        • -
      • -

        req-modify-alter-remove-item-nameThe remove directive criteria item-name MUST match an object if and only its value is identical to the value of that object's - serialized name. For example,remove:item-name:prop has the effect of removing all prop objects from inside the control.

        -

        req-modify-alter-remove-item-name-arrayIn serialization formats that use arrays of objects in the OSCAL model, an object's - name MUST be considered the singular form of its containing parent array. For example, in the JSON format, remove:item-name:link would remove all of the objects - inside of the links array.

        -
        • -
      -
      -
      -
      -
      - -

      9 Final Operations

      -       -
      - -

      9.1 Backmatter Resolution

      -       -

      back-matter in the result is produced by combining all objects within back-matter in all source catalogs, with the back-matter in the input profile.

      -
        -
      • -

        req-backmatterThe output's backmatter MUST be generated by copying in each resource object from the backmatters of the imported catalogs/profiles in top-to-bottom order, - then by copying in each resource object from the backmatter of the source profile itself. These objects MUST be processed - in the order they are given in their respective documents.

        -
        • -
      • -

        req-backmatter-dupeIf a given resource has the same uuid as a resource that has already been added, the previous resource MUST be removed, - and the more recent one added, unless superceded by other requirements.

        -
        • -
      • -

        req-backmatter-keepA resource with a child prop of name:keep and value:always MUST NOT be replaced by the addition of another resource, unless the new resource also has a child prop of name:keep and value:always.

        -
        • -
      -

      req-backmatter-pruneTools MAY check for pruning conditions [See: 9.3 Pruning and Ordering] as resources are added as long as the final result is the same as if the pruning - had taken place at the end of all resource addition.

      -

      Placing the keep always prop on a resource in a catalog has the effect of ensuring - it will always appear in the output produced by any profile importing that catalog, - even if nothing links to the resource. This version of the resource will also be the - one copied, unless a later-imported catalog or importing profile offers its own version - marked to keep always.

      -
      -
      - -

      9.2 Metadata Resolution

      -       -

      The following requirements MUST be followed with regards to the Metadata section of - the output catalog:

      -
        -
      • -

        req-meta-uuidThe output catalog's metadata MUST have a unique top-level UUID (metadata:uuid). This - UUID may be generated as seen fit by the tool, as long as it is reasonable to assume - it is globally unique. It is RECOMMENDED that tools use a combination of meaningful - text and a uniquely generated value (Ex.{{sourceprofilename}}-RESOLVED-{{GUIDv5}}).

        -
        • -
      • -

        req-meta-versionThe value of metadata:version in the target MUST be set with a string that identifies - the version of that document. req-meta-version-trackThe metadata:version SHOULD be used to track updates to this specific output document.

        -
        • -
      • -

        req-meta-oscal-versionThe value of metadata:oscal-version in the target MUST be set with a string that identifies - the version of OSCAL used by this tool to resolve the profile (ex. 1.0.0). This value - MUST be determined by compiling the oscal-versions from each imported document and - the source profile, and taking the most recent minor version. If this version is more - recent than what the resolution tool is using, then the value of the output oscal-version - MUST be the version that the tool used internally. req-meta-oscalversion-errorIf any of the above OSCAL versions (imported document versions, source profile version, - tool version) are of a different major version (the first digit differs), the tool - SHOULD provide an error and cease processing.

        -
        • -
      • -

        req-meta-last-modifiedThe value of metadata:last-modified in the target MUST be set with a valid timestamp - representing the time the profile resolution completed.

        -
        • -
      • -

        req-meta-source-profileThe value of metadata:source-profile in the target SHOULD be set with a valid URI - that points to the profile that resulted in this catalog. req-meta-source-profile-privacyIf there are privacy or security concerns, the value of metadata:source-profile MAY - be set to anything, in which case the simple existence of the source-profile property - indicates that this is a resolved profile.

        -
        • -
      • -

        req-meta-resolution-toolThe value of metadata:resolution-tool in the target SHOULD be set with a string that - represents the tool that was used to resolve this catalog.

        -
        • -
      • -

        req-meta-keepFor any metadata:roles or metadata:parties that exist in the source catalogs, if they - have a prop child with name:keep and value:always, they are to be copied as is into the output - metadata.

        -
        • -
      -

      Beyond these requirements, tools are free to use any and all of the objects inside - metadata to provide additional information downstream.

      -

      Because of options in producing metadata and especially the requirement for a timestamp, - developers and users should note that two different resolutions of the same profile - will not, ordinarily, be identical inside metadata.

      -
      -
      - -

      9.3 Pruning and Ordering

      -       -

      req-pruneThe processor SHOULD prune the resulting output catalog by removing unused objects.

      -
        -
      • -

        req-prune-keepAny object that has a child prop with a name of "keep" and a value of "always" MUST NOT be pruned.

        -
        • -
      • -

        req-prune-includeIf an object was explicitly included in the [See: 6.2 Including Controls], it MUST NOT be pruned.

        -
        • -
      • -

        req-prune-customIf an object was referenced in a custom section of the source profile, it MUST NOT be pruned.

        -
        • -
      • -

        req-prune-modifyIf an object was referenced in the modify section of the source profile, it MUST NOT be pruned. Any objects removed in that - section are still removed.

        -
        • -
      • -

        req-prune-refIf the object appears in a reference anywhere in the final result catalog, except - in other objects that also meet all other pruning criteria, it MUST NOT be removed. - A reference to a given object exists if "#{distinctiveID}" appears anywhere, where - {distinctiveID} is the distinctive ID of the object [See: 10.1 Distinct ID of Objects].

        -
        • -
      -

      Implementers should note that pruning need not take place after all other steps. As - long as all above criteria are respected, pruning can happen at any time, and doing - so is a likely performance and memory overhead improvement.

      -

      req-reorderTools MUST reorder the output catalog into canonical order [See: 10.2.4 Order of objects in serialization], except where this specification provides different ordering requirements.

      -
      -
      -
      - -

      10 Items of Note

      -       -
      - -

      10.1 Distinct ID of Objects

      -       -

      Whenever this specification refers to distinctiveness, it is to be interpreted as is defined in this section with regards to the object - in question.

      -

      req-id-idFor the objects control, param, and group, distinctiveness MUST be determined by the - value of the id child object.

      -

      req-id-uuidFor the object resource, distinctiveness MUST be determined by the value of the uuid [See: 9.1 Backmatter Resolution].

      -
      -
      - -

      10.2 Dealing with Multiple Formats

      -       -

      req-multiformatProfile Resolution tools SHOULD be able to handle source profiles, imported catalogs, - and imported profiles that are serialized in XML, JSON, or YAML. req-multiformat-differA different serialization format of any given input MUST NOT result in a differing - output catalog.

      -

      In order to help bootstrap this format management, the following resources are provided - for implementers:

      -
        -
      • -

        .

        -
        • -
      -

      The following sections provide additional requirements and guidance for each format.

      -
      - -

      10.2.1 Requirements and Guidance for XML Output

      -       -

      req-output-xmlThe final Catalog output, if using XML, MUST be valid as defined by the XML model - documentation for the OSCAL Catalog. See the complete XML reference for model requirements.

      -
      -
      - -

      10.2.2 Requirements and Guidance for JSON Output

      -       -

      req-output-jsonThe final Catalog output, if using JSON, MUST be valid as defined by the JSON model - documentation for the OSCAL Catalog. See the complete JSON reference for model requirements.

      -

      The JSON format, in general use, does not require the preservation of order of fields. - As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order - [See: 10.2.4 Order of objects in serialization] when outputting a catalog in JSON.

      -
      -
      - -

      10.2.3 Requirements and Guidance for YAML Output

      -       -

      req-output-yamlThe final Catalog output, if using YAML, MUST be valid as defined by the JSON model - documentation for the OSCAL Catalog. YAML is considered a simple variation on the JSON format. Beyond cosmetic differences - there are no differences in the information structure between these formats. Therefore, - the complete JSON reference provides model requirements.

      -

      The YAML format, in general use, does not require the preservation of order of fields. - As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order - [See: 10.2.4 Order of objects in serialization] when outputting a catalog in YAML.

      -
      -
      - -

      10.2.4 Order of objects in serialization

      -       -

      In OSCAL, order of top level objects (those that are direct children of the root element) - is considered important only when the XML format is used. To facilitate this, OSCAL - provides the concept of canonical order. This order is provided by the OSCAL Metaschema files for a given document type (see - an overview of Metaschema.

      -

      req-orderWhen the output format is XML, tools MUST use the OSCAL canonical order as described - above. When using the YAML or JSON formats, order conveys no meaning, and is not considered - important.

      -
      -
      - -

      10.2.5 Comments in result documents

      -       -

      In an XML-based profile resolution, XML comments are one straightforward way for a - processor to record events or conditions without affecting the output's nominal semantics. - To support this, while two processors are obliged to return the same catalog XML for - the same profile XML inputs, they are not required to match one another's comments, - white space usage, attribute order, or processing instructions, only each other's - objects, attributes and data content.

      -

      One consequence of this is that processes intended to compare two profile resolutions - may have to accommodate differences in comments, considering them as insignificant - along with other differences in serialization.

      -
      -
      -
      -
      - - \ No newline at end of file diff --git a/src/specifications/profile-resolution/specml-html-preview-preview.html b/src/specifications/profile-resolution/specml-html-preview-preview.html deleted file mode 100644 index e63626a7a1..0000000000 --- a/src/specifications/profile-resolution/specml-html-preview-preview.html +++ /dev/null @@ -1,59 +0,0 @@ -{ child::head } Specification{ child::head } SpecificationRequirements 'Corbel', sans-serif - -body {{ line-height: 140%; font-family: "Cambria", serif }} - -* {{ box-sizing: border-box }} - -aside.navpanel {{ position: fixed; overflow-y: scroll; max-width: 36%; top: 1em; bottom: 0px; font-family: { $display-font } }} - -aside.navpanel div.rqrmts * {{ margin: 0em }} - -.req {{ background-color: pink; padding: 0.2em; font-size: 120%; border-top: thin solid red; border-bottom: thin solid red; margin-top: 0.2em !important }} -nav .req {{ font-size: 90% }} -.req.should {{ background-color: peachpuff; border-top: thin solid orange; border-bottom: thin solid orange }} -.req.may {{ background-color: cornsilk; border-top: thin solid gold; border-bottom: thin solid gold }} -.req.recommended {{ background-color: mintcream; border-top: thin solid blue; border-bottom: thin solid blue }} - -span.reqlabel {{ background-color: mintcream; color: forestgreen; margin-right: 0.4em; padding: 0.1em; border: thin solid green }} - -.toc ul {{ list-style: none; padding-left: 1em }} - -main {{ margin-left: 40%; max-width: 48em }} - -details {{ margin-top: 1.5em }} - -details details {{ border-left: thin solid black; padding-left: 1em }} - -summary > * {{ display: inline }} - -pre {{ white-space: pre-wrap }} - -h1, h2, h3, h4, h5, h6 {{ font-family: { $display-font } }} - -code.src {{ font-size:90%; font-weight:bold; background-color: lightsteelblue; padding: 0.2em }} -code.tgt {{ font-size:90%; font-weight:bold; background-color: lemonchiffon; padding: 0.2em }} -code.int {{ font-size:90%; font-weight:bold; background-color: pink; padding: 0.2em }} -b.term, b.xpath {{ font-family: { $display-font } }} - -.secnum {{ padding: 0.2em; color: midnightblue; font-weight: bold; font-size: 110% }} - -a {{ color: inherit }} -a.linked {{ color: inherit }} -.toc a {{ text-decoration: none }} - -span.req {{ color: royalblue }} -span.req:hover {{ background-color: beige }} - -.example {{ padding: 0.5em; border: thin dotted black; margin-top: 1em }} -.example > *:first-child {{ margin-top: 0em }} - -.example.source_profile-tagging {{ background-color: lightsteelblue }} -.example.source_catalog-tagging {{ background-color: powderblue }} -.example.target_catalog-tagging {{ background-color: lemonchiffon }} -.example.inter_catalog-tagging {{ background-color: lemonchiffon }} - -.revisit {{ font-style: italic; color: red; background-color: yellow }} - -.xref {{ font-weight: bold; font-family: { $display-font } }} - - Unit test: { . }Source data:Target (catalog):Source (catalog):Source (profile):Intermediate (catalog): \ No newline at end of file From 507f5cddc70eba3c6d445962e6a2d96f666de403 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Mon, 9 May 2022 16:36:09 -0400 Subject: [PATCH 14/15] Updates to Profile Resolution spec (with example files now tagged) and readme.md --- .../profile-resolution-specml.xml | 264 +++++++++++------- .../profile-resolution/readme.md | 1 + 2 files changed, 165 insertions(+), 100 deletions(-) diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml index 5fcffde022..3f6665c9fd 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml.xml @@ -1,8 +1,10 @@ - - - - + + + + + + OSCAL Profile Resolution
      @@ -184,7 +186,11 @@
      Phases of Profile Processing

      An OSCAL Profile has three major sections, each which correspond to a phase of profile resolution. In order to complete the profile resolution process, each section must be fully parsed and a catalog output created.

      -

      It is strongly RECOMMENDED that implementations execute the following steps in the order that they are provided here (import, merge, modify). While it is possible to achieve compliance with a non-standard approach, the iterative nature of profile resolution lends itself to linear processing.

      +

      PENDING test designIt is strongly RECOMMENDED + that implementations execute the following steps in the order that they are provided here + (import, merge, modify). While it is possible to achieve compliance with a + non-standard approach, the iterative nature of profile resolution lends itself to linear + processing.

      The three steps are import; merge; and @@ -271,39 +277,76 @@ profile: Import href Requirements

      Import URI Resolution -

      Tools MUST resolve URIs by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be resolved as defined in - . +

      relative URITools MUST resolve + URIs by following Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with + "#"). URI Fragments MUST instead be resolved as defined in .

      Import Resource Acquisition -

      Tools MUST acquire resources at the resolved URI by following - Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be acquired as defined in - . +

      via internal reference to + resource/rlinkTools MUST acquire resources at the resolved URI by following Section 5 of + RFC3986, with the exception of URI Fragments (URIs that start with "#"). + URI Fragments MUST instead be acquired as defined in .

      -

      For the purposes of resolving URIs using the above specification, the Base URI MUST be considered to be the absolute URI of the containing profile.

      -

      In the case that acquiring a resource fails, the tool MUST cease processing and provide an error. In order to ensure profile resolution results in the same catalog regardless of which tool resolves it, all imports must successfully resolve. While this may cause inconvenience if resources are frequently not available, it ensures interoperability.

      +

      URI base corresponds to document URIFor the purposes of resolving URIs + using the above specification, the Base URI MUST be considered to be the absolute URI of + the containing profile.

      +

      PENDING rebase over latest from galtm missing resourceIn the case + that acquiring a resource fails, the tool MUST cease processing and provide an error. In + order to ensure profile resolution results in the same catalog regardless of which tool + resolves it, all imports must successfully resolve. While this may cause inconvenience + if resources are frequently not available, it ensures interoperability.

      Note that receiving a cached version of an import, or resolving an import that is otherwise unavailable through some other (but automatic) means still satisfies the above requirement. This specification does not put requirements on the precise function of the import, as long as the correct document is retrieved.

      Internal References

      URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of #{{objectID}}. For example, the URI Fragment #param1 is referencing the Parameter with unique ID param1.

      -

      In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the resources section of the source. When tools encounter such a reference, they MUST locate the object in resources with the matching UUID value, and resolve the resource. - By OSCAL model requirements, a given resource can have zero to many rlink objects and zero to one base64 objects; however, it must have at least one of the two present. Tools can assume that any of these each resolves to the same underlying OSCAL object, although potentially in different serialization formats. - For deterministic resolution of these backmatter OSCAL objects, tools need to adhere to the following requirements: -

      +

      In the context of the Import Phase, + internal references will only appear as a reference to a profile or catalog that is in + the resources section of the source. When tools encounter such a reference, + they MUST locate the object in resources with the matching UUID value, and + resolve the resource. By OSCAL model requirements, a given resource can have + zero to many rlink objects and zero to one base64 objects; + however, it must have at least one of the two present. Tools can assume that any of + these each resolves to the same underlying OSCAL object, although potentially in + different serialization formats. For deterministic resolution of these backmatter OSCAL + objects, tools need to adhere to the following requirements:

        -

      • Tools MAY use any of the rlink or base64 objects present in the resource.

        • -

      • Tools MAY verify that each above objects resolves to the same underlying OSCAL object. If there are OSCAL Model content differences between the resolved objects, the tool SHOULD provide a warning.

        • -

      • When a rlink is encountered and is to be resolved, it MUST be resolved by using a HTTP request to retrieve a byte stream.

        • -

      • When a base64 is encountered and is to be resolved, it MUST be considered a Byte Stream.

        • -

      • Regardless of its source, the Byte Stream MUST be decoded based on the algorithm defined in Section 4 RFC 4648.

        • +

      • PENDING test design (support for either/both base64 + and rlink)Tools MAY use any of the rlink or base64 + objects present in the resource.

        • +

      • PENDING test design (correspondence of base64 and + rlink-nominated objects)Tools MAY verify that each above objects resolves to + the same underlying OSCAL object. If there are OSCAL Model content differences + between the resolved objects, the tool SHOULD provide a warning.

        • +

      • PENDING test design (retrieval)When a + rlink is encountered and is to be resolved, it MUST be resolved by + using a HTTP request to retrieve a byte stream.

        • +

      • PENDING test design (base64 integrity)When + a base64 is encountered and is to be resolved, it MUST be considered a + Byte Stream. +

        • +

      • PENDING test design (base64 + integrity)Regardless of its source, the Byte Stream MUST be decoded based on + the algorithm defined in + Section 4 RFC 4648.

      -

      If the object fetched cannot be found or is not a valid OSCAL object, the tool MUST cease processing and provide an error.

      +

      PENDING rebase over latest from galtmPENDING rebase over latest from galtmIf the object fetched cannot be found + or is not a valid OSCAL object, the tool MUST cease processing and provide an + error.

      Resolving Imports of Profiles -

      If the resource acquired is an OSCAL Profile, the tool MUST apply this specification to resolve it, then continue processing having imported the resulting catalog.

      -

      When a profile imports a profile, the subordinate profile SHOULD be resolved first into a catalog using this specification, before it is imported. This presents the possibility of circular imports, when a profile is directed to import itself either directly or indirectly.

      +

      PENDING chained profilesIf the resource acquired is an OSCAL Profile, the tool + MUST apply this specification to resolve it, then continue processing having imported + the resulting catalog.

      +

      PENDING chained profilesPENDING [bug repair] chained profile + merged with controls from its own source catalogWhen a profile imports a profile, + the subordinate profile SHOULD be resolved first into a catalog using this + specification, before it is imported. This presents the possibility of circular + imports, when a profile is directed to import itself either directly or indirectly.

      A circular import occurs when a profile imports an already imported profile, which was called at an earlier place in the import hierarchy. For example, if profile A imports profile B, and profile B imports profile A, the second import is circular. (An import at the top can only be circular if a profile tries to import itself.) If A imports B, B imports C and C imports A, C’s import is circular.

      Note that an import can only be circular within the context of processing a particular profile. In the last example, C’s import would not be circular if invoked in the context of resolving B by itself.

      -

      If a processor encounters a - circular import as described above (self-imports are inherently circular), the processor MUST cease processing and generate an error. -

      +

      PENDING circular import detectionIf a processor encounters a circular + import as described above (self-imports are inherently circular), the processor + MUST cease processing and generate an error.

      -

      A profile identified as - home_profile.yamlimports another one identified as - circular_profile.yaml: -

      +

      A profile identified as home_profile.yamlimports another one identified as + circular_profile.yaml:

      -

      In turn this file invokes - home_profile.xml: -

      +

      In turn this file invokes home_profile.xml:

      -

      Once detected, this circular import will result in an error and no further processing will take place.

      +

      Once detected, this circular import will result in an error and no further processing + will take place.

      Multiple imports -

      Each import directive is processed to produce a set of controls. Note that this occurs even if the same catalog is imported multiple times: each distinct import collects controls into a separate - selection: -

      +

      Each import directive is processed to produce a set of controls. PENDING + chained profilesNote that this occurs even if the same catalog is imported + multiple times: each distinct import collects controls into a separate + selection:

      -

      The control inclusions are combined and collapsed in the next phase of processing, - merge(see ) . -

      +

      PENDING + chained profilesThe control inclusions are combined and collapsed in the next + phase of processing, merge(see ) .

      Multiple imports against the same resource are allowed, and would most commonly occur when the profile author is using to create very specific output. Multiple imports may result in outputs with clashing control IDs if mapping or the merge directive is not set correctly.

      @@ -482,19 +534,18 @@ intermediate: may make changes to an included control or group that could cause it to appear differently, or not at all, in the output. Using the intermediate implementation approach, any control(s) that are included would be extracted from the referenced catalogs, any applicable mappings would be applied, then the controls(s) would be stored.

      include-all -

      When an import provides the - include-all directive, ALL controls and groups in the referenced document (including nested controls) MUST be included. -

      +

      + When + an import provides the include-all directive, ALL controls and groups in the + referenced document (including nested controls) MUST be included.

      include-all: ~
      include-controls plus with-id -

      When an import provides the - include-controls directive, with a - with-id child, all controls in the referenced document whose - id match one of the listed - id values MUST be included. -

      +

      When an import provides the + include-controls directive, with a with-id child, all controls + in the referenced document whose id match one of the listed id + values MUST be included.

      include-controls plus matching

      Controls may also be included using match patterns against their IDs. This is useful because related controls (either in a hierarchy, or together in a group) frequently have related IDs as well.

      -

      When an import provides the +

      When an import provides the include-controls directive, with a matching child, all controls in the referenced document whose id matches one of the listed pattern values (Glob matching) MUST be included.

      -

      If a +

      If a matching object is provided with no pattern, it MUST be treated as matching nothing. While not providing a pattern is technically valid, resolution tool implementers should be aware that it is generally undesirable, and warnings or notices to the user may be appropriate.

      @@ -533,18 +584,18 @@ include-controls:
      with-child-controls

      Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the with-child-controls option. with-child-controls appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.

      -

      A - with-child-controls: yes directive on an - include-controls indicates that - all descendant controls of the included control MUST also be included. -

      -

      A - with-child-controls: no directive on an - include-controls indicates that ONLY the matching control is included, any descendant children MUST NOT be included. -

      -

      If no - with-child-controls is provided, the processor MUST consider the directive as being equivalent to one having - with-child-controls:no. +

      A with-child-controls: + yes directive on an include-controls indicates that all + descendant controls of the included control MUST also be included.

      +

      A with-child-controls: + no directive on an include-controls indicates that ONLY the + matching control is included, any descendant children MUST NOT be included.

      +

      If no + with-child-controls is provided, the processor MUST consider the + directive as being equivalent to one having with-child-controls:no.

      @@ -554,39 +605,50 @@ include-controls: with-parent-controls applies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they should use an exclude directive that lists all of the undesired parents. As a shortcut for this, with-parent-controls provides the following functionality:

      -

      A - with-parent-controls: yes directive on an - include-controls indicates that - all parent controls of the included control MUST also be included. -

      -

      A - with-parent-controls: no directive on an - include-controls indicates that ONLY the matching control is included, any parent MUST NOT be included. -

      -

      If no - with-parent-controls is provided, the processor MUST consider the directive as being equivalent to one having - with-parent-controls:yes. -

      +

      PR + https://github.com/usnistgov/OSCAL/pull/1207PR + https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: + yes directive on an include-controls indicates that all parent + controls of the included control MUST also be included.

      +

      PENDING PR + https://github.com/usnistgov/OSCAL/pull/1207A with-parent-controls: + no directive on an include-controls indicates that ONLY the + matching control is included, any parent MUST NOT be included.

      +

      Neither setting is + givenIf no with-parent-controls is provided, the processor MUST + consider the directive as being equivalent to one having + with-parent-controls:yes.

      exclude-controls

      Exclusions work the same way as inclusions, except with the opposite effect - the indicated control(s) do not appear in the target catalog.

      -

      Any control designated to be both included and excluded, MUST be excluded. This holds irrespective of the specificity of the selection for inclusion or exclusion. For example, if AC-1 is included by id - ac-1 and excluded by matching - ac.*, it is excluded. -

      -

      When - exclude-controls has at least one - with-ids or - matching directive, the processor MUST follow the same rules as defined in the relevant sections above for these directives, but exclude instead of include any controls. All optional features (with-child-controls, etc.) also apply to exclusion directives. -

      +

      Any control designated to be both + included and excluded, MUST be excluded. This holds irrespective of the specificity of + the selection for inclusion or exclusion. For example, if AC-1 is included by id + ac-1 and excluded by matching ac*, it is excluded.

      +

      When exclude-controls + has at least one with-ids or matching directive, the processor + MUST follow the same rules as defined in the relevant sections above for these + directives, but exclude instead of include any controls. All optional features + (with-child-controls, etc.) also apply to exclusion directives.

      Redundant Inclusions and Exclusions -

      A given - import may have any number of inclusion statements and any number of exclusion statements. Their effect is cumulative; any control that is included (or excluded) more than once MUST be considered to be included (or excluded) only once. In other words, a given control being included or excluded more than once has no effect. Exclusion still takes priority over inclusion (see above). -

      +

      A given import may have + any number of inclusion statements and any number of exclusion statements. Their effect + is cumulative; any control that is included (or excluded) more than once MUST be + considered to be included (or excluded) only once. In other words, a given control being + included or excluded more than once has no effect. Exclusion still takes priority over + inclusion (see above).

      Note that this requirement only applies to controls included within the context of a single import. Controls with duplicate IDs included under a different import are not discarded. Also note that this redundancy pruning happens after any relevant mappings have been applied.

      @@ -634,7 +696,9 @@ include-controls: mergesection, where directives are given to instruct the processor how to combine the set of included objects collected during the Import Phase. mergehas two parts: a "combine" directive, and a "structuring" directive.

      -

      It is RECOMMENDED that tools apply the "combine" directive to the intermediate generated by the Import phase first, then apply the "structuring" directive.

      +

      PENDING is this testable?It is RECOMMENDED that tools apply the + "combine" directive to the intermediate generated by the Import phase first, then + apply the "structuring" directive.

      The following section contains requirements for processing the merge child of a source profile.

      @@ -657,17 +721,17 @@ include-controls:

      keep: Keep - controls with the same ID are kept, retaining the clash

    -

    Note that "merge: combine" is deprecated, and MUST be considered undefined behavior when encountered.

    +

    PENDING specificationNote that "merge: + combine" is deprecated, and MUST be considered undefined behavior when + encountered.

    In order to apply the combination method, IDs of each control explicitly included are compared against one another. As IDs are unique across entire OSCAL documents, different imports or any groupings have no bearing on collision. Processing requirements for each method are described below.

    No Combine Directive -

    If no - merge directive is given in the profile, or if a - merge is given without a - combine, merge conflicts MUST be treated as if - method: keep was given. For example, a profile with no - merge directive: -

    +

    + If no merge directive + is given in the profile, or if a merge is given without a combine, + merge conflicts MUST be treated as if method: keep was given. For + example, a profile with no merge directive:

    No Structuring Directive -

    If no +

    If no merge directive is given in the profile, or if a merge is given without a structuring directive, structuring the output MUST be treated as if the structuring directive flat was given. For example, a profile with no diff --git a/src/specifications/profile-resolution/readme.md b/src/specifications/profile-resolution/readme.md index 295fa1dc29..26a54cd0fd 100644 --- a/src/specifications/profile-resolution/readme.md +++ b/src/specifications/profile-resolution/readme.md @@ -1,3 +1,4 @@ + ## Providing feedback on this specification The OSCAL team welcomes feedback on the work in progress in this subdirectory, whether it be questions, points for clarification, critiques or suggestions. A rendered version of the Profile Resolution specification maintained here [appears](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/) on the OSCAL web site. From 819367c70e0e97893ce077f6b26b51f81feec9c6 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Mon, 9 May 2022 16:45:40 -0400 Subject: [PATCH 15/15] Updated profile resolution (spec) readme with clarification regarding unit testing --- src/specifications/profile-resolution/readme.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/specifications/profile-resolution/readme.md b/src/specifications/profile-resolution/readme.md index 26a54cd0fd..e3a32f2055 100644 --- a/src/specifications/profile-resolution/readme.md +++ b/src/specifications/profile-resolution/readme.md @@ -1,3 +1,4 @@ +# Profile Resolution Specification and Testing ## Providing feedback on this specification @@ -7,7 +8,15 @@ Please post Issues in Github or questions to the OSCAL mailing list, or ask abou The specifications are being edited in an ad-hoc XML back end format, a lightweight extension to HTML tagging. If you wish to edit the files directly, we have stylesheets for presentation and HTML conversion along with Schematron for validation (runtime or at check points); please contact us. -### Capabilities +## Profile Resolution Unit Tests + +Profile resolution unit tests are maintained here and bound to the specification via markup embedded with the specifications, for convenience in alignment. Formal test scenario files can be generated dynamically from markup when needed. + +In this subdirectory, the folder `profile-resolution-examples` includes old tests kept here for potential future use/reuse while we complete a common test set. + +The comment test set we are developing can be found in folder `requirement-tests`. + +## SpecML Capabilities - XML authoring of specifications - HTML previews with ToC / requirements index @@ -39,14 +48,13 @@ The `@href` is the file instance for the example. The text is a qualifying descr Presently all `eg` are inside `req` so there is an implicit relation there (no examples are named apart from stated requirements). -### Unit tests +### Unit test scenario generation Based on markup in the SpecML document, XSpec unit test sheets can be generated framing the unit test held in this subdirectory, to be executed in any (current) XSpec implementation. #### Requirements listing Broken out by requirement - corresponding line by line to //req in the Spec document source. - This XSpec is generated by applying the XSLT `lib/build-reqs-xspec.xsl` to the SpecML source document (marked with `req` and `eg` tags). #### File listing