Develop a solution for managing identifier clashes in OSCAL Profiles

[david-waltermire]

User Story

As an OSCAL Profile author or consumer, I need a means to resolve identifier clashes caused by importing catalog content from different sources, whose objects have the same identifier for different objects. The approach that is used must be deterministic and must preserve the provenance of the original identifiers.

A solution must be able to support:

• Renaming specific identifiers by specifying an old and new name. Resolved by Profile import identifier handling #1424.
• Applying a prefix and/or suffix supporting bulk renaming. Resolved by DRAFT: Issue 1327 support prefix suffix during mapping #1428.
• Recording the original identifier for a given object. Resolved by Retain reassigned identifier in catalog props assembly. #1397 #1423.

Conflicts may occur in controls, groups, parts, and parameters.

This issue will develop a solution to address the following issues:

• Tracking control identity via catalog of origin #538 -> PR Profile Identifier Mapping #1196
• Profile: identifier specificity when multiple catalogs are imported #843
• Profile Resolution: Support control identifier prefix/suffix when importing catalog controls. #1327

Follow on work needs to include:

• Document source-identifier in the profile resolution specification based on the changes in PR Retain reassigned identifier in catalog props assembly. #1397 #1423.
• Align profile resolution specification with latest processing model defined in the profile metaschema. #1474

Goals

• Feature PR Profile import identifier handling #1424 has been updated to include all additional PRs contributing to this feature set.
  • Merged PR Retain reassigned identifier in catalog props assembly. #1397 #1423.
• Design and document an approach to update the Profile model that will address the requirements above.
  • Documented approach is backwards compatible with OSCAL 1.x models.
• Develop a few examples that illustrate use of the features identified above and publish these examples as GitHub gists.
• Create issues for any follow on work to be addressed.

Issue #1398 will be used to socialize the design with the OSCAL community.

Dependencies

None.

Acceptance Criteria

• New design document is publicly available
• Examples are published publicly
• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

[Compton-US]

Summary to address the third requirement: "Recording the original identifier for a given object."

This solution is an approach to handling identifier conflicts by:

• Req 3: Recording the original identifier for a given object.

The draft specification profile model supports from and to mapping, but the catalog model needs to track the from identifier to maintain a record of the original identifier for traceability.

Proposed Solution

The catalog model supports props which is capable of maintaining key/value information related to controls. One possible solution that utilizes the existing major version of OSCAL (non-breaking) is to define a property as:

Catalog Model

catalog [1]: {
    uuid [1]: uuid,
    metadata [1]: { … },
    params [0 or 1]: [ … ],
    controls [0 or 1]: [
        An array of control objects [1 to ∞] {
            id [1]: token,
            class [0 or 1]: token,
            title [1]: markup-line,
            params [0 or 1]: [ … ],

       props [0 or 1]: [
           An array of prop objects [1 to ∞] {
               name [1]: token,
               uuid [0 or 1]: uuid,
               ns [0 or 1]: uri,
               value [1]: string,
               class [0 or 1]: token,
               remarks [0 or 1]: markup-multiline,
           }
       ],

            links [0 or 1]: [ … ],
            parts [0 or 1]: [ … ],
            controls [0 or 1]: [ … ],
        }
    ],
# [...SNIP...]

Catalog Sample

    <control class="SP800-53" id="au-6-low">
        <title>Audit Review, Analysis, and Reporting</title>
        <!-- [...SNIP...] -->

        <prop ns="http://csrc.nist.gov/ns/oscal"
            name="source-identifier" 
            value="au-6"/>

        <!-- [...SNIP...] -->  
    </control>
    <control class="SP800-53" id="au-6">
        <title>Audit Review, Analysis, and Reporting</title>
        <!-- [...SNIP...] -->
    </control>

[Compton-US]

Prefix/Suffix requirement is documented in another issue: #1327