Check a FedRAMP document's metadata for fedramp-version to identify requirements used

[aj-stein-gsa]

This is a ...

fix - something needs to be different

This relates to ...

• the FedRAMP OSCAL Validations

User Story

As a creator or maintainer of an FedRAMP digital authorization package with its documents in OSCAL, I would like validations to check for the existence of a specific property in the metadata with a name of fedramp-version and only permit value that is a specific release tag for a given OSCAL version.

Goals

• Give tool developers and digital package maintainers a specific field to define which version of FedRAMP automation requirements are used with the package

Dependencies

No response

Acceptance Criteria

• All FedRAMP Documents Related to OSCAL Adoption (https://github.com/GSA/fedramp-automation) affected by the changes in this issue have been updated.
• A Pull Request (PR) that
  • implements an allowed-values constraint with level ERROR if the prop of name fedramp-version at /*/metadata/prop[@name='fedramp-version']) does not have a valid value (for now: fedramp-3.0.0rc1-oscal-1.1.2); it should not allow alternatives
  • implements an expect constraint with level ERROR if the prop of name fedramp-version is not present in the document.
  • Positive test cases with the prop correctly defined
  • Negative test cases with the prop incorrectly defined or missing
• TBD: A related PR to add documentation about this new requirement to the automate.fedramp.gov website

Other information

No response

[aj-stein-gsa]

I apologize for the delays, @DimitriZhurkin, I am very tardy in writing up this issue for you to work on this constraint tomorrow.

[DimitriZhurkin]

@aj-stein-gsa, is fedramp-3.0.0rc1-oscal-1.1.2 a fixed value?

Are we going to update this value in the SSP template every time there's a new version?

[aj-stein-gsa]

@aj-stein-gsa, is fedramp-3.0.0rc1-oscal-1.1.2 a fixed value?

Are we going to update this value in the SSP template every time there's a new version?

I think that warrants discussion, but probably. We should have a few controlled releases a year, and this should be part of commits that are right before a final release as we make them. We have to discuss out of band data eventually, but we must defer that for now. I will update issues and discuss that next week. This is the second case where it comes up.

[DimitriZhurkin]

I apologize, I should've put it a little differently.

Which of the following should we be checking:

• The existence of the prop
• A fixed value
• A value pattern

[aj-stein-gsa]

Which of the following should we be checking:

• The existence of the prop
• A fixed value
• A value pattern

@DimitriZhurkin, ok it seems we need an allowed-value prop and an expect prop separately, make the two separate constraints (the first and second in your list from the above comment, not the third) in their respective files. I will clarify the goals and AC requirements in the issue above when I return from a quick break.

[DimitriZhurkin]

@aj-stein-gsa, do you have a specific location for the <fedramp-version> prop in mind?

Here's how I put it in ssp-all-VALID.xml (third from the bottom):

  <metadata>
    <title>Enhanced Example System Security Plan</title>
    <published>2024-08-01T14:30:00Z</published>
    <last-modified>2024-08-01T14:30:00Z</last-modified>
    <version>1.1</version>
    <fedramp-version>fedramp-3.0.0rc1-oscal-1.1.2</fedramp-version>
    <oscal-version>1.0.0</oscal-version>
    <document-id scheme="https://example.com/identifiers">SSP-2024-002</document-id>

[DimitriZhurkin]

Probably more importantly, we'll need to add <fedramp-version> to Metaschema. Currently, it throws a validation error.

[DimitriZhurkin]

Sorry, not Metaschema, but rather SSP, SAR, SAP, and POAM XSDs.

But first we'd need to decide on the placement (position) of <fedramp-version> inside <metadata>.

[DimitriZhurkin]

Took liberty to tweak the SSP XSD to include <fedramp-version> (see attached; had to change its extension from xsd to txt).

With that XSD, ssp-all-VALID.xml does pass validation In Oxygen.

oscal_ssp_schema.txt

[aj-stein-gsa]

@aj-stein-gsa, do you have a specific location for the <fedramp-version> prop in mind?

Sorry, it seems I should have not said the following words without code formatting, property -> prop.

<system-security-plan>
  <metadata>
    <title>Enhanced Example System Security Plan</title>
    <published>2024-08-01T14:30:00Z</published>
    <last-modified>2024-08-01T14:30:00Z</last-modified>
    <version>1.1</version>
    <fedramp-version>fedramp-3.0.0rc1-oscal-1.1.2</fedramp-version>
    <oscal-version>1.0.0</oscal-version>
    <document-id scheme="https://example.com/identifiers">SSP-2024-002</document-id>
   <!-- See below: -->
   <prop name="fedramp-version" value="3.0.0rc1-oscal-1.1.2`"/>

Does this help, @DimitriZhurkin?

[aj-stein-gsa]

Also, apologies, I got around to updating the acceptance criteria in the ticket. I hope that helps.

[DimitriZhurkin]

Perfect, thank you!

I actually initially thought that you had meant <prop name="fedramp-version" value="fedramp-3.0.0rc1-oscal-1.1.2">FedRAMP Version</prop>.

But then I looked at the <metadata> section and didn't see any <prop> elements.

Sorry for misunderstanding.

[aj-stein-gsa]

No worries I hope that helps.

[DimitriZhurkin]

Terribly sorry to be a pain, but the <prop> element might not work.

When I add the following to oscal_ssp_schema.xsd

         <xs:element name="prop"
                      type="oscal-metadata-fedramp-version-FIELD"
                      minOccurs="1"
                      maxOccurs="1"/>

I get this validation error:

Two elements in the content model have the same name <prop> but different types.
This violates the constraint Element Declarations Consistent.

The error is valid, since there's already a <prop> element declared in the XSD:

         <xs:element name="prop"
                      type="oscal-metadata-property-ASSEMBLY"
                      minOccurs="0"
                      maxOccurs="unbounded"/>

[DimitriZhurkin]

If we do not modify oscal_ssp_schema.xsd, I think it works fine.

[vmangat]

The OSCAL model already includes a "props" field in metadata that is an array of props. The constraints needs to make sure that SSP, SAP, SAR and POAM artifacts have populated one prop called "fedramp-version" in the array.
This will indicate to FedRAMP what version of the specs this file conforms to.
The valid values will be one of the FedRAMP published versions of its specifications that are being accepted at any given time.
The valid value is driven by the FedRAMP versioning scheme tag.

[aj-stein-gsa]

As asked on #800, please update the checklist items for final review so the relevant tasks can be reviewed and we can mark this issue as "Ready to Ship" and you can move onto a new task, @DimitriZhurkin.

[DimitriZhurkin]

Done.

[aj-stein-gsa]

@DimitriZhurkin, ok, but you left the goal unchecked. You think the constraint and documentation do not meet the goal's objective?

[DimitriZhurkin]

Done.