DOCSEARCHbyAlgolia
Submit Docs

Open Security Controls Assessment Language (OSCAL)

repository·main·Indexed 21 days ago

https://github.com/usnistgov/oscal

A standardized, machine-readable set of XML, JSON, and YAML formats developed by NIST for representing security control information, including publication, implementation, and assessment data. The project includes a format-neutral Metaschema used to generate data models, conversion scripts, and documentation, as well as tools for schema validation and profile resolution.

Tokens
7.5K
Snippets
17
Records
41
Agent score
75%

What's inside OSCAL

  1. What is Open Security Controls Assessment Language (OSCAL)?

    main

    OSCAL is a set of hierarchical, XML-, JSON-, and YAML-based formats developed by NIST to provide standardized representations of information regarding the publication, implementation, and assessment of security controls.

    The formats are designed to be minimal and generic enough to capture broad control specifications while allowing for ad-hoc tuning and extensions to support specific industry standards or new control types.

    Key resources for developers:

  2. Locate the Public OSCAL Website and Reference

    main

    The OSCAL project has reorganized its web presence into two distinct repositories to separate general website content from technical documentation.

    • Public OSCAL Website: Managed in the OSCAL-Pages repository. It uses Hugo and USWDS styling. The content is published to the nist-pages branch of the OSCAL repository to comply with NIST deployment requirements.
    • Public OSCAL Reference: Managed in the OSCAL-Reference repository. This contains the technical documentation generated from OSCAL metaschema content. It is linked from the main OSCAL website.

  3. Access OSCAL tools and utilities

    main

    OSCAL tools are available through several channels:

    1. Official Tool List: A curated list of tools is maintained on the NIST OSCAL tools page.
    2. OSCAL Tools Repository: A dedicated repository of tools is maintained at https://github.com/usnistgov/oscal-tools.
    3. Community Tools: Various community-contributed tools are available in open repositories, though these are not officially maintained by the OSCAL project.

    This specific repository contains archived functionality, including a profile resolution demonstration and a schema validator.

  4. What is the OSCAL Metaschema?

    main

    The OSCAL Metaschema is a format-neutral definition of the information structures that constitute an OSCAL model. It serves as the single source of truth for the semantics and structure of OSCAL, allowing for consistent support across different data formats.

    By using Metaschema modules, the project can automatically generate several critical artifacts to ensure consistency between XML and JSON representations:

  5. Understand Mirror Statuses for document lifecycle

    main

    When using the <mirror> element, the status attribute communicates how the mirrored resource relates to the current OSCAL document:

    StatusMeaning
    currentThe mirror is the same version/release as this file, potentially in a different notation (e.g., a JSON version of an XML file). These can be compared directly to establish identity.
    supersedingPoints to a newer, updated version available elsewhere. It is informative and may not be backward compatible.
    supersededThe mirror is an older version that has been replaced by the current version. Used for forward tracking across versions.
    subsumedThe mirror is a prior version where differences are not considered "significant," and backward compatibility is expected.
    alignedThe mirror is an alternative version (like a PDF or Word doc) that is conceptually the same, but cannot be reliably verified via automated comparison. To declare alignment with Word/ODT, use media-type="zip" and status="aligned".

  6. What validation does and does not guarantee in OSCAL

    main

    Validation is an objective determination by a program.

    • What it guarantees: That your data is syntactically correct and conforms to the structural rules of the schema, making it fit for further automated processing.
    • What it does NOT guarantee: That the information represented is "correct." Validation cannot determine if the data is truthful, complete, adequate, or accurate in a human/subjective sense. A document can be perfectly valid according to the schema while containing incorrect security information.

  7. Understand the difference between well-formedness and validity in OSCAL

    main

    When working with OSCAL (XML, JSON, or YAML), it is critical to distinguish between these two concepts:

    1. Well-formedness: Refers to whether the file follows the basic syntax rules of the language (e.g., XML tags are properly closed, JSON braces are balanced). A file that is not well-formed cannot be parsed and will cause immediate errors in any processor.
    2. Validity: Refers to whether the data structure conforms to the specific rules of an OSCAL model (e.g., a system-security-plan must contain certain required elements).

    Key takeaway: A file can be well-formed (readable by a parser) but still be invalid (not conforming to the OSCAL schema).

  9. Understand the purpose of Profile Resolver Pipeline tests

    main

    The testing/* directories contain XSpec tests designed to verify the interim results produced by each XSLT transformation within the resolver pipeline sequence.

    Important Caveats:

    • Schema Validity: The interim results captured in these tests are not guaranteed to be valid against any official OSCAL schema, though they typically adhere closely to OSCAL profile and catalog syntax.
    • Implementation Specificity: These tests are specific to this particular implementation. For implementation-independent tests and sample files related to profile resolution, refer to the profile resolution specification.

  10. Understand the simplified system lifecycle used in OSCAL tutorials

    main

    To reduce complexity and focus on security automation, OSCAL tutorials use a simplified system lifecycle rather than full frameworks like NIST 800-37 (RMF) or ISO/IEC 27005. This lifecycle is designed to be evocative of real-world processes while stripping away non-essential steps to keep the focus on OSCAL implementation.

    When following OSCAL tutorials, you can map the simplified steps to standard Risk Management Framework (RMF) or Software Development Life Cycle (SDLC) phases as follows:

    Simplified Lifecycle StepRMF EquivalentSDLC Equivalent
    DesignSelectDesign
    DevelopImplementDevelop
    TestAssessTest

    Note that this model collapses 'prepare', 'categorize', and 'select' into Design, renames 'implement' to Develop, and collapses 'assess' and 'authorize' into Test. The 'monitor' phase is omitted from this simplified model.

    |RISK MGMT | Select | Implement | Assess |
| --- | --- | --- | --- |
|DEVELOPMENT | Design | Develop | Test |

  11. Artifacts generated from OSCAL Metaschema

    main

    The Metaschema is used to derive the following technical artifacts used by developers and automated tools:

    • Data Models: XML (XSD) and JSON schemas derived from Metaschema modules.
    • Conversion Scripts: Tools that convert OSCAL content between XML and JSON formats while ensuring the output remains schema-valid.
    • Model Documentation: XML and JSON documentation used to describe the OSCAL models on official NIST websites.

  12. OSCAL Content Development and Release Workflow

    main

    The OSCAL project manages content (catalogs, profiles, and examples) in a dedicated oscal-content repository. To ensure data integrity and compatibility with the core OSCAL models, the following workflow is required for content releases:

    Development Standards

    • Source Format: All examples, profiles, and catalogs must be developed in the src directory of the oscal-content repository using OSCAL XML format only. Conversion to other formats occurs later in the pipeline.
    • Tooling: The oscal-content repository uses a Makefile-based approach for development and automation, consistent with the core repository.

    Release Requirements

    Every OSCAL model release must coincide with an oscal-content release. Even if the content itself has not changed, the following updates are mandatory to maintain synchronization with the latest models:

    1. Update Submodule: Update the OSCAL submodule to the latest tagged release.
    2. Increment Versions: For all source catalogs and profiles, increment both the oscal-version and the version fields.
    3. Update Timestamps: Update the last-modified and published timestamps, even for backwards-compatible changes.
    4. Update Schema Instructions: Update all xml-model instructions at the top of every example, profile, and catalog instance to point to the complete OSCAL XML schema artifact that matches the new oscal-version.

    Versioning and Tagging

    • Releases must follow SemVer (Semantic Versioning) requirements.
    • Tagged commits must include generated artifacts.
    • The release process mimics the core OSCAL repository's versioning, branching, and release guidelines.