Profile Resolution 1.0.2 Updates (usnistgov#1172)

* Specification changes, usnistgov#1141 usnistgov#1142 usnistgov#1155
* Mapping documentation, UUID RFC reference
* Apply suggestions from AJ's review

Co-authored-by: Stephen Banghart <stephen.banghart@outlook.com>
Co-authored-by: Alexander Stein <alexander.stein@nist.gov>

src/metaschema/oscal_profile_metaschema.xml

@@ -42,15 +42,15 @@
       </define-assembly>
       <define-assembly name="import">
             <formal-name>Import resource</formal-name>
-            <description>The <code>import</code> designates a catalog, profile, or other resource to be included (referenced and potentially modified) by this profile. The import also identifies which controls to select using the <code>include-all</code>, <code>include-controls</code>, and <code>exclude-controls</code> directives.</description>
+            <description>The <code>import</code> designates a catalog or profile to be included (referenced and potentially modified) by this profile. The import also identifies which controls to select using the <code>include-all</code>, <code>include-controls</code>, and <code>exclude-controls</code> directives.</description>
             <define-flag name="href" as-type="uri-reference" required="yes">
                   <formal-name>Catalog or Profile Reference</formal-name>
                   <description>A resolvable URL reference to the base catalog or profile that this profile is tailoring.</description>
                   <remarks>
-                        <p>The value of the <code>href</code> can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a <code>back-matter</code>
+                        <p>The value of the <code>href</code> can be an internet resource, or an internal reference using a fragment e.g. #fragment that points to a <code>back-matter</code>
                               <code>resource</code> in the same document.</p>
                         <!-- TODO: Add a link to "within the scope of the containing OSCAL document" to point to documentation of identification scopes" -->
-                        <p>If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified <code>resource</code> in the document's <code>back-matter</code> or another object that is within the scope of the containing OSCAL document.</p>
+                        <p>If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the <code>uuid</code> value of a <code>resource</code> in the document's <code>back-matter</code>.</p>
                         <p>If an internet resource is used, the <code>href</code> value will be an absolute or relative URL pointing to the location of the referenced resource. A relative URL will be resolved relative to the location of the document containing the link.</p>
                   </remarks>
             </define-flag>
@@ -93,7 +93,7 @@
             <model>
                   <define-assembly name="combine">
                         <formal-name>Combination rule</formal-name>
-                        <description>A Combine element defines whether and how to combine multiple (competing) versions of the same control</description>
+                        <description>A Combine element defines how to combine multiple (competing) versions of the same control.</description>
                         <define-flag name="method" as-type="string">
                               <formal-name>Combination method</formal-name>
                               <description>How clashing controls should be handled</description>
@@ -110,7 +110,8 @@
                         </constraint>
                         <remarks>
                               <p>Whenever combining controls from multiple (import) pathways, an issue arises of what to do with clashing invocations (multiple competing versions of a control). </p>
-                              <p>This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile, such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.</p>
+                              <p>This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (e.g. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.</p>
+                              <p>If no <code>combine</code> element appears, it is considered equivalent to providing a <code>combine</code> element with a <code>method</code> of value <q>keep</q>. </p>
                         </remarks>
                   </define-assembly>
                   <choice>

src/specifications/profile-resolution/profile-resolution-specml.xml

@@ -20,9 +20,9 @@
     <head>Introduction</head>
     <section id="purpose">
       <head>Purpose</head>
-      <p>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.</p>
+      <p>
+        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.
+</p>
 
       <p>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, 
@@ -289,9 +289,20 @@ profile:
       <section id="internalref">
         <head>Internal References</head>
         <p>URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of <code>#{{objectID}}</code>. For example, the URI Fragment <code>#param1</code> is referencing the Parameter with unique ID <code>param1</code>.</p>
-        <p><req level="must" id="req-internal">In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the <src>resources</src> section of the source. When tools encounter such a reference, they MUST locate the object in <src>resources</src> with the matching ID value, and resolve the import using the
-          <src>rlink</src> URI and the above resolution requirements.
+        <p><req level="must" id="req-internal">In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the <src>resources</src> section of the source. When tools encounter such a reference, they MUST locate the object in <src>resources</src> with the matching UUID value, and resolve the resource. 
+          By OSCAL model requirements, a given <src>resource</src> can have zero to many <src>rlink</src> objects and zero to one <src>base64</src> 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:
         </req></p>
+        <ul>
+          <li><p><req level="may" id="req-internal-resolve1">Tools MAY use any of the <src>rlink</src> or <src>base64</src> objects present in the <src>resource</src>.</req> </p> </li>
+          <li><p><req level="may" id="req-internal-resolve2">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. </req></p> </li>
+          <li><p><req level="must" id="req-internal-resolve3">When a <src>rlink</src> is encountered and is to be resolved, it MUST be resolved by using a HTTP request to retrieve a byte stream. </req></p> </li>
+          <li><p><req level="must" id="req-internal-resolve4">When a <src>base64</src> is encountered and is to be resolved, it MUST be considered a Byte Stream.</req> </p> </li>
+          <li><p><req level="must" id="req-internal-resolve5">Regardless of its source, the Byte Stream MUST be decoded based on the algorithm defined in <a href="https://datatracker.ietf.org/doc/html/rfc4648"> Section 4 RFC 4648</a>. </req></p> </li>
+        </ul>
+
+
+
         <p><req level="must" id="req-internal-error">If the object fetched cannot be found or is not a valid OSCAL object, the tool MUST cease processing and provide an error.</req></p>
         <tagging whose="source_profile">
           <![CDATA[
@@ -596,6 +607,7 @@ include-controls:
         <p>Some source catalogs use
           <src>group</src> 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.
         </p>
+        <p>Group objects that have a child <src>prop</src> object with name:keep and value:always MUST NOT be pruned (see <xref rid="cleanup"/>. Additional details on handling the final outputting of these groups can be found in the "merge" phase below.</p>
       </section>
       <section id="import-pitfalls">
         <head>Avoiding Implementation Pitfalls</head>
@@ -1370,8 +1382,7 @@ control:
       <p>The following requirements MUST be followed with regards to the Metadata section of the output catalog:</p>
       <ul>
         <li>
-          <p><req level="must" id="req-meta-uuid">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.
-            <code>{{sourceprofilename}}-RESOLVED-{{GUIDv5}}</code>).
+          <p><req level="must" id="req-meta-uuid">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 <a href="https://datatracker.ietf.org/doc/html/rfc4122">Section 4 of RFC 4122</a>.
           </req></p>
         </li>
         <li>
@@ -1384,10 +1395,11 @@ control:
           <p><req level="must" id="req-meta-last-modified">The value of metadata:last-modified in the target MUST be set with a valid timestamp representing the time the profile resolution completed.</req></p>
         </li>
         <li>
-          <p><req level="should" id="req-meta-source-profile">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. </req> <req level="may" id="req-meta-source-profile-privacy"> 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.</req></p>
+          <p><req level="should" id="req-meta-source-profile">A child <src>prop</src> object with <src>name:source-profile</src> MUST be created. The <src>value</src> object of this <src>prop</src> SHOULD be set with a valid URI that points to the profile that resulted in this catalog. </req> 
+            <req level="may" id="req-meta-source-profile-privacy"> If there are privacy or security concerns, the <src>value</src> object of this <src>prop</src> MAY be set to anything, in which case the simple existence of the source-profile property indicates that this is a resolved profile.</req></p>
         </li>
         <li>
-          <p><req level="should" id="req-meta-resolution-tool">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.</req></p> <!-- TODO: Should this be generalized? -->
+          <p><req level="should" id="req-meta-resolution-tool">A child <src>prop</src> object with <src>name:resolution-tool</src> SHOULD be created. The <src>value</src> object of this <src>prop</src> in the target SHOULD be set with a string that represents the tool that was used to resolve this catalog.</req></p>
         </li>
         <li><p><req level="must" id="req-meta-keep">For any metadata:roles or metadata:parties that exist in the source catalogs, if they have a <src>prop</src> child with name:keep and value:always, they are to be copied as is into the output metadata.</req></p></li>
       </ul>
@@ -1457,25 +1469,25 @@ control:
         <head>Requirements and Guidance for XML Output</head>
         <p><req level="must" id="req-output-xml">The final Catalog output, if using XML, MUST be valid as defined by the XML model documentation for the OSCAL Catalog. See
           <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/xml-definitions/">the complete XML reference</a> for model requirements.</req>
-        </p> <!-- TODO: Add Namespace --> <!-- TODO: Consult XML Wizards on namespacing and other XML requirements -->
+        </p> 
       </section>
       <section id="jsonrequirements">
         <head>Requirements and Guidance for JSON Output</head>
         <p><req level="must" id="req-output-json">The final Catalog output, if using JSON, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. See the
           <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a> for model requirements. </req>
         </p>
-        <p>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
+        <p>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
           <xref rid="order" /> when outputting a catalog in JSON.
-        </p> <!-- TODO: Add Namespace (BaseURI) -->
+        </p> 
       </section>
       <section id="yamlrequirements">
         <head>Requirements and Guidance for YAML Output</head>
         <p><req level="must" id="req-output-yaml">The final Catalog output, if using YAML, MUST be valid as defined by the JSON model documentation for the OSCAL Catalog. </req> 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
           <a href="https://pages.nist.gov/OSCAL/reference/latest/complete/json-reference/">complete JSON reference</a> provides model requirements.
         </p>
-        <p>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
-          <xref rid="order" />when outputting a catalog in YAML.
-        </p> <!-- TODO: Add Namespace (BaseURI) -->
+        <p>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
+          <xref rid="order" /> when outputting a catalog in YAML.
+        </p> 
       </section>
       <section id="order">
         <head>Order of objects in serialization</head>

src/specifications/profile-resolution/specml-html-hugo-uswds.xsl

@@ -13,8 +13,8 @@
 
     <xsl:template name="yaml-header">
         <xsl:text>---</xsl:text>
-        <xsl:text>&#xA;title: OSCAL Profile Resolution</xsl:text>
-        <xsl:text>&#xA;description: Transforming a profile into the tailored catalog it represents</xsl:text>
+        <xsl:text>&#xA;title: OSCAL Profile Resolution Specification Draft</xsl:text>
+        <xsl:text>&#xA;description: Working draft of the profile resolution specification.</xsl:text>
         <!--<xsl:text>&#xA;custom_css:</xsl:text>
         <xsl:text>&#xA;  - /css/oscal-specs.css</xsl:text>-->
         <xsl:text>&#xA;toc:</xsl:text>
@@ -52,8 +52,4 @@
         </xsl:element>
     </xsl:template>
 
-
-
-
-
 </xsl:stylesheet>