From 1b454919f2b8a223a7d2512009d9586f5f5536d9 Mon Sep 17 00:00:00 2001 From: Stephen Banghart Date: Mon, 14 Mar 2022 12:44:24 -0400 Subject: [PATCH 1/4] Specification changes, #1141 #1142 #1155 --- .../profile-resolution-specml.xml | 39 ++++++++++++------- .../specml-html-hugo-uswds.xsl | 8 +--- 2 files changed, 28 insertions(+), 19 deletions(-) diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml index cb575ce440..e854e7957a 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml.xml @@ -20,9 +20,9 @@ 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.

+

+ 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, @@ -289,9 +289,20 @@ profile:

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 - rlink URI and the above resolution 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 ID 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 obejcts, the tool SHOULD provide a warning.

    • +

  • When a rlink is encountered and is to be resolved, it MUST be resolved by using a HTTP Client 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.

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 @@ -1384,10 +1396,11 @@ control:

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.

    +

    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.

  • -

    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.

    +

    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.

    • @@ -1457,25 +1470,25 @@ control: 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, care should be taken to adhere to the canonical OSCAL order +

    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, care should be taken to adhere to the canonical OSCAL order - when outputting a catalog in YAML. -

    +

    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 diff --git a/src/specifications/profile-resolution/specml-html-hugo-uswds.xsl b/src/specifications/profile-resolution/specml-html-hugo-uswds.xsl index 271a078839..f02f0a2799 100644 --- a/src/specifications/profile-resolution/specml-html-hugo-uswds.xsl +++ b/src/specifications/profile-resolution/specml-html-hugo-uswds.xsl @@ -13,8 +13,8 @@ --- - title: OSCAL Profile Resolution - description: Transforming a profile into the tailored catalog it represents + title: OSCAL Profile Resolution Specification Draft + description: Working draft of the profile resolution specification. toc: @@ -52,8 +52,4 @@ - - - - From 80ec218f5f85ff9bebf9464d09c2c7e6eae4139e Mon Sep 17 00:00:00 2001 From: Stephen Banghart Date: Mon, 14 Mar 2022 13:10:52 -0400 Subject: [PATCH 2/4] Documentation updates --- src/metaschema/oscal_profile_metaschema.xml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index c07c892735..e221db6b33 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -42,15 +42,15 @@ Import resource - The import 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 include-all, include-controls, and exclude-controls directives. + The import 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 include-all, include-controls, and exclude-controls directives. Catalog or Profile Reference A resolvable URL reference to the base catalog or profile that this profile is tailoring. -

    The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter +

    The value of the href can be an internet resource, or an internal reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

    -

    If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

    +

    If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the id value of a resource in the document's back-matter.

    If an internet resource is used, the href 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.

         @@ -93,7 +93,7 @@ Combination rule - A Combine element defines whether and how to combine multiple (competing) versions of the same control + A Combine element defines how to combine multiple (competing) versions of the same control Combination method How clashing controls should be handled @@ -110,7 +110,8 @@

    Whenever combining controls from multiple (import) pathways, an issue arises of what to do with clashing invocations (multiple competing versions of a control).

    -

    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.

    +

    This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (ex. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.

    +

    If no combine element appears, it is considered equivalent to providing a combine element with a method of value keep.

    From 8e588192cf3855220f4bc2e33e4a19e8089793ab Mon Sep 17 00:00:00 2001 From: Stephen Banghart Date: Mon, 14 Mar 2022 13:39:27 -0400 Subject: [PATCH 3/4] Mapping documentation, UUID RFC reference --- .../profile-resolution/profile-resolution-specml.xml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml index e854e7957a..8d20f2fcf0 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml.xml @@ -1382,8 +1382,7 @@ control:

    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 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.

    • From 39199412647105dcf847796426458242d8d0a304 Mon Sep 17 00:00:00 2001 From: Stephen Banghart Date: Thu, 17 Mar 2022 14:03:42 -0400 Subject: [PATCH 4/4] Apply suggestions from AJ's review Co-authored-by: Alexander Stein --- src/metaschema/oscal_profile_metaschema.xml | 6 +++--- .../profile-resolution/profile-resolution-specml.xml | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index e221db6b33..e310f11414 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -50,7 +50,7 @@

      The value of the href can be an internet resource, or an internal reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

      -

      If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the id value of a resource in the document's back-matter.

      +

      If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the uuid value of a resource in the document's back-matter.

      If an internet resource is used, the href 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.

      @@ -93,7 +93,7 @@ Combination rule - A Combine element defines how to combine multiple (competing) versions of the same control + A Combine element defines how to combine multiple (competing) versions of the same control. Combination method How clashing controls should be handled @@ -110,7 +110,7 @@

      Whenever combining controls from multiple (import) pathways, an issue arises of what to do with clashing invocations (multiple competing versions of a control).

      -

      This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (ex. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.

      +

      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.

      If no combine element appears, it is considered equivalent to providing a combine element with a method of value keep.

      diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml index 8d20f2fcf0..5fcffde022 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml.xml @@ -289,14 +289,14 @@ profile:
      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 resource. +

      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 obejcts, the tool SHOULD provide a warning.

        • -

      • When a rlink is encountered and is to be resolved, it MUST be resolved by using a HTTP Client request to retrieve a Byte Stream.

        • +

      • 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.

      @@ -1382,7 +1382,7 @@ control:

      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 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.