Constraint Management

Background

The term "constraints" is a reference to Metaschema Constraints. Metaschema is the same modeling language used to define OSCAL itself. The constraints are able to enforce rules such as whether content is required and data type, as well as any required or suggested values.

For an initial primer on Metaschema Constraints, please familiarize yourself with the tutorials and practice with modification to simpler example models or OSCAL model constraints.

FedRAMP-defined constraints are applied to OSCAL content as a second layer of validation beyond core OSCAL syntax validation. In other words, OSCAL-based FedRAMP authorization packages must first meet the OSCAL core-syntax validation and then also satisfy FedRAMP OSCAL constraint validation.

The following has been defined to ensure FedRAMP OSCAL constraints are created, modified or retired consistently.

Goals

• Contributors consistently implement FedRAMP constraints.
• FedRAMP stakeholders are able to use FedRAMP constraints to validate packages as much as possible prior to submission to FedRAMP.
• FedRAMP reviewers are able to use FedRAMP constraints as a pre-check to submitted packages before performing human-judgement review activities.
• FedRAMP stakeholders are able to easily discover the following for every constraint:
  • documentation that clearly explains expected OSCAL content for FedRAMP packages
  • clear examples demonstrating OSCAL-based FedRAMP Authorization Packages.
  • The justification or rationale for creating, modifying or retiring a constraint.

Definition of Done

For constraint work, the following tasks must be performed for each issue related to creating constraints before the issue is considered complete:

• All OSCAL adoption content affected by the change in this issue have been updated per the Documentation Standard.
• All constraints associated with the review task have been created.
• The appropriate example OSCAL file is updated with content that demonstrates the FedRAMP-compliant OSCAL presentation.
• The constraint conforms to the FedRAMP Constraint Style Guide.
  • All automated and manual review items that identify non-conformance are addressed or technical leads (ping or assign for review fedramp-automation-admins or @david-waltermire; @aj-stein-gsa individually) have approved the PR and “override” the style guide requirement.
• Known good test content is created for unit testing.
• Known bad test content is created for unit testing.
• Unit testing is configured to run both known good and known bad test content examples.
• Passing and failing unit tests, and corresponding test vectors in the form of known valid and invalid OSCAL test files, are created or updated for each constraint.
• A Pull Request (PR) is submitted that fully addresses the goals section of the User Story in the issue.
  • The issue is referenced in the PR.

Documentation Standards

• An appropriate section in the content exists
• The topic is listed in the section summary
• The topic has or is within an appropriate subsection
• The subsection title uses appropriate styling, such that it appears in the “On this page” list
• Where practical and appropriate, use an image of the MS-Word template.
  • The relevant portion of the template image is annotated
• A description of the content is present
• The content is depicted in the OSCAL Representation
  • The relevant portion of the OSCAL representation is annotated
• The OSCAL representation is OSCAl-valid:
  • XML format only for now
    • NOTE: We will address JSON and YAML versions of examples as our automation matures such that XML snippets can be converted to OSCAL-valid JSON and YAML snippets automatically by our CI/CD pipeline
  • Valid UUID values are used, but may be crafted.
    • Example: 00000000-0000-4000-8000-000000000001 For crafted UUID’s:
      • To ensure RFC-4122 UUIDv4 and OSCAL datatype compliance, crafted UUIDs must follow the following pattern, where “x” represents digits that may be manually adjusted: xxxxxxxx-xxxx-4000-8000-xxxxxxxxxxxx
  • Use canonical id values where appropriate . For example, use the 800-53 controls IDs for controls, and the OSCAL-defined role IDs for roles whenever practical.
• OSCAL Representation commentary should always be present.
  • Make the example “speak for itself” as much as possible
  • Minimize the use of XML comments as they will not translate easily to JSON or YAML.
  • Use OSCAL-valid remarks fields to add commentary on the OSCAL snippet where appropriate.
  • Ensure there is discussion text near the OSCAL representation that adds clarification and provides commentary that does not fit cleanly into the example.
• A metapath query is depicted for the content targeted by the constraint.
• A list of constraint IDs that pertain to the content.