AP/AR/POA&M Local Definitions and Metadata Party/Location Require a Link to Corrected Content

[brian-ruf]

User Story:

When a local definition is a correction, a mechanism is required to link the corrected content to the original content.

We intend for the the AP, AR, and POA&M to reference content in the SSP when present and accurate (and for the AR to reference content in the AP as appropriate).

We say that whenever content is missing or inaccurate in the SSP (or AP when appropriate), the missing or inaccurate should be defined in local-definitions (for component, inventory-item, user, and control-objective), or in meatadata for location and party.

Where the local entry is to add information, this is very straight-forward; however, where the local entry is to correct existing information, a mechanism is required to link the corrected content to the original content.

This was discussed, but not implemented.

Goals:

• Establish a mechanism for linking locally corrected content to its original content

Dependencies:

None.

Acceptance Criteria

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

[brian-ruf]

I recommend establishing a "updates-uuid" property in:

• /assessment-plan/metadata/party
• /assessment-plan/metadata/location
• /assessment-plan/local-definitions/component
• /assessment-plan/local-definitions/inventory-item
• /assessment-plan/local-definitions/user
• /assessment-results/metadata/party
• /assessment-results/metadata/location
• /assessment-results/result/local-definitions/component
• /assessment-results/result/local-definitions/inventory-item
• /assessment-results/result/local-definitions/user
• /plan-of-action-and-milestones/party
• /plan-of-action-and-milestones/location
• /plan-of-action-and-milestones/local-definitions/component
• /plan-of-action-and-milestones/local-definitions/inventory-item
• /plan-of-action-and-milestones/local-definitions/user

Whenever the entry is a correction for content elsewhere in the OSCAL stack, the "corrects-uuid" property is added and contains the UUID of the original content.

The new content should be complete and used in place of the original content. Any correct details from the original content must be duplicated into the updated content.

EDIT (by @brianrufgsa ): changed corrects-uuid to updates-uuid

[iMichaela]

@brianrufgsa If the latest, accurate information is permitted to be scattered in all places under local definitions (for component, inventory-item, user and control-objective), is there a danger to not be able to identify what is correct/accurate for a system, despite the updates-uuid added artifact, especially that the AP, AR and POA&M are authored not by the system owner? Is it possible to, at minimum annotate also the SSP with a pointer to where the latest/most-accurate information can be found? This will be very useful for the authorizing official too.

EDIT (by @brianrufgsa ): changed corrects-uuid to updates-uuid

[brian-ruf]

@iMichaela The SSP is authored by the system owner. The AP and AR are authored by the assessor.

The assessor must never modify SSP content. They may ask the system-owner to do so, but when that is not practical, the assessor needs a way to add missing information and update inaccurate information. This approach is already part of the design and it outside the scope of this issue.

This issue only enhances the existing approach to make it clear the locally defined version is an update, not an addition.

Existing Approach:
From the AP and AR, the assessor uses UUIDs from the SSP to cite information. If they find that information is missing or incorrect, they add it to local definitions, so it is clear this is information provided by the assessor (because it is in the assessor's document). Then they cite the UUID of the content in local definitions.

The local-definitions version is always considered to be more up-to-date/complete because it was the assessor finds as different from the SSP's documentation.
This issue simply establishes a link to the original SSP content when the locally defined content is an update to existing SSP content rather than an addition.

[iMichaela]

@brianrufgsa - I am very well aware of the documents' ownership and hence the comment. I like very much the local 'update' solution, put I wonder it there is a direct way of collecting this information and pushing it back to the system owner (using maybe the POA&M to collect it and convey it in one package)? Because today the page with the ATO signature is attached to the SSP in front, as a cover page, making the SSP part of the ATO. The best or not the best, this is current practice for the agencies I spoke with. The information conveyed back to hte system owner can be the SSP errata.

[brian-ruf]

The POA&M is also a system-owner authorized document. The assessor may update it on behalf of the system owner.

In theory, anything the assessor added or corrected is in local-definitions, so it could be as easy as a summary of that content, which is what we said in the workshop and what we are saying in the FedRAMP guides.

[iMichaela]

@brianrufgsa - yes, that was the thought I had - assessors could use the POA&M and their right to update it, to convey or gather the local-definitions information in one place (POA&M) so the 'errata' (as in 'updated information' not 'errors locator') is made easily available to the system owner.
I like the sound of : "so it could be as easy as a summary of that content" coming form you because it is what I think too. Should I understand that POA&A supports this approach today form your statement: "which is what we said in the workshop and what we are saying in the FedRAMP guides."?

[brian-ruf]

Yes. That is the intention; however, the thought is that since both are typically authored by the system owner, the local-definitions will not be used as extensively.

Some of the POA&M use cases might include:

• adding a scanning tool to the local-definitions of the POA&M since scanning tools are often not defined in the SSP.
• Keeping a component or inventory-item in the POA&M when it is no longer valid in the SSP, such as may be desired for historical reference.
• adding all SSP components and system inventory-items to the local-definitions of the POA&M when delivering the POA&M (such as to FedRAMP) without an attached SSP.

[Arminta-Jenkins-NIST]

At 9/28 Triage Meeting: @aj-stein-nist suggests this is a metaschema issue that should be transferred.

[aj-stein-nist]

At 9/28 Triage Meeting: @aj-stein-nist suggests this is a metaschema issue that should be transferred.

Meetings in the car are dangerous when I must rely on issue numbers on the board from memory. This issue was not usnistgov/metaschema#434 like I thought it was and I must have confused with my comments, I got them confused. We should discuss this one. I apologize. We should reprioritize this one, apologies!

[aj-stein-nist]

I know this is a long-standing issue, but I would like to propose a method with functionality that was added to the link assembly, resource-fragment that supports a generalized ability applicable to the use cases above if we are talking about use cases casually based on "I want to be able to link changes back to the original source in these places."

We say that whenever content is missing or inaccurate in the SSP (or AP when appropriate), the missing or inaccurate should be defined in local-definitions (for component, inventory-item, user, and control-objective), or in meatadata for location and party.

Now, wherever link is supported, you can use either the URI or href of the source document that changed or its UUID (because it is pointing to the documented by UUID to this information in a back-matter/resource entry) and then point to the specific UUID within that document (a.k.a the resource fragment), so you know which document and where.

Can we proceed with examples and determine if that approach, supported in 1.1.0 and newer, is acceptable and we can move to close this issue or refine it further to move forward on this given a specific need @brian-ruf ?

[brian-comply0]

@aj-stein-nist given the local-definition should only be correcting content in "the OSCAL stack" (aka other content linked to either directly or indirectly via import statements), anything that can point to the UUID of the original content should be sufficient by itself. I think a link statement is perfectly reasonable.

I believe the key is to have a documented and consistent mechanism for expressing that link, such as using the @rel attribute with a NIST-defined value of something like supersedes, updates, or corrects, and a constraint in metaschema that limits link[@rel='corrects'] (for example) to those assemblies (local-definitions/components, local-definitions/inventory-item, local-definition/user, local-definition/control-objective, and metadata/party in AP, AR and POA&M) and limits the value to UUID-only.

Finally, there may be cause to have both a corrects and a supersedes as those are slightly different use cases. (AP and AR are more likely corrects, while POA&M could be either corrects or supersedes - given the use case of delivering POA&M and inventory monthly to AOs, but delivering SSP less often.)

[aj-stein-nist]

Thanks for the feedback, we will noodle on this and continue fleshing out in comments.

[Arminta-Jenkins-NIST]

At 10/12 Triage Meeting: @aj-stein-nist will spec out some examples to present (maybe at the next Models Engineering meeting). He will also ask Brian for feedback prior to next Triage meeting.

[Arminta-Jenkins-NIST]

At the 11/30 Triage Meeting: The OSCAL team discussed this issue and would like to know if @brian-easyd can provide examples or submit a pull request with a proposed approach which would best capture his vision allowing the community members to clearly understand the proposal and endorse it or provide feedback.