search

usnistgov / OSCAL

Open Security Controls Assessment Language (OSCAL)
https://pages.nist.gov/OSCAL/
Other
670 stars 182 forks source link

Prepare Documentation and Artifacts for Milestone 1 Release #341

Closed brian-ruf closed 5 years ago

brian-ruf commented 5 years ago

User Story:

As an OSCAL adopter, I need to rely on NIST-provided OSCAL resources in order to properly adopt OSCAL.

Goals:

Dependencies:

Issue #311 #331 #332

Acceptance Criteria

Catalog and Profile documentation is accurate, complete, and up-to-date, including:

Appropriate files are posted in appropriate locations

Tools are available

iMichaela commented 5 years ago

5/2/2019

The team made progress, but more work is needed on the schema documentation.

brian-ruf commented 5 years ago

5/9/2019

@brianrufgsa and @david-waltermire-nist to schedule working session next week. (Monday afternoon)

david-waltermire commented 5 years ago

Discussed this issue with @brianrufgsa today. We came up with the following outline:

Release archive with the following contents:

The following is an outline of the readme.txt:

Overview

Release Contents

The following contents are provided in this release:

This mirrors the new site layout.

Using OSCAL resources

For the following, provide usage examples using open source tools:

Roadmap

How to Contribute

david-waltermire commented 5 years ago

@brianrufgsa will start on the "Using OSCAL resources" and "Roadmap" sections of the readme.txt. @david-waltermire-nist will start on the rest.

david-waltermire commented 5 years ago

5/16/19

The following work needs to be done still:

brian-ruf commented 5 years ago

Using OSCAL

NIST developed the Open Security Controls Assessment Language (OSCAL) as a machine-readable data exchange format. It enables organizations to express and exchange detailed cybersecurity content in either Extensible Markup Language (XML) or JavaScript Object Notation (JSON).

NIST defined and governs the core OSCAL syntax, which includes cyber security content that is universal across industries and compliance regimes. NIST further designed OSCAL to be extended by other organizations to address industry-specific, compliance-specific, or organization-specific content. Please see the Extending OSCAL section for more information.

OSCAL Adoption

For OSCAL compliance, mechanisms interpreting or generating OSCAL content must honor the core syntax described at https://pages.nist.gov/OSCAL/docs/schemas/.

While not mandatory, organizations adopting OSCAL are encouraged to use NIST-published validation and translation mechanisms. The validation mechanism ensures XML and JSON files are OSCAL-compliant, while the translation mechanism converts OSCAL content from either format to the other. An automated governance process enables NIST to ensure these mechanisms remain aligned with the latest OSCAL syntax.

Standards

NIST makes validation and conversion mechanisms available using the following established standards:

OSCAL Syntax Validation
XML XML Schema Definition Language (XSD) 1.1
[ https://www.w3.org/TR/xmlschema11-1/ ]
JSON JSON Schema, draft-07
[ https://json-schema.org/ ]
OSCAL File Conversion
XML & JSON Extensible Stylesheet Language Transformation (XSLT) 3.0
[ https://www.w3.org/TR/2017/REC-xslt-30-20170608/]

XPath 3.1
[https://www.w3.org/TR/xpath-31/ ]

IMPORTANT : XSLT 3.0 and XPath 3.1 are only required when using NIST published tools to convert OSCAL files between JSON and XML. Any version of XSLT or XPath may be used when transforming or querying OSCAL files for other reasons. Later versions offer more robust capabilities. There are several JSON query capabilities available, such as JSONPath [https://restfulapi.net/json-jsonpath/]; however, no one capability has emerged as a clear standard as of this publication.

Available Tools and Resources

There are many tools available to validate and manipulate XML and JSON content using these standards. This includes both open source and commercial tools, as well as standard capabilities available in many programming languages.

The following tools are used by the NIST OSCAL Team and are known to work with OSCAL. This is neither an exhaustive list of available tools, nor an endorsement. OSCAL adopters are encouraged to do their own research and select the resources that are best for their specific needs and budget. OSCAL adopters are also responsible for ensuring their compliance with any licensing requirements.

Tool Commercial Open-Source NOTES
oXygen XML Editor Yes https://www.oxygenxml.com/
A commercial tool with a graphical user interface for working with XML, XSLT, XSD and related capabilities.
xmllint Yes http://xmlsoft.org/xmllint.html
Linux-based open source tool for XML management and manipulation.
xmllint can be run on Windows with a Linux subsystem.
Saxon-HE (Home Edition) Yes http://www.saxonica.com/
Saxon-HE offers the latest XSLT processing, and is fully open-source without technical support.

Saxon-HE is available via SourceForge and Maven. It supports XSLT 3.0 and XPath 3.1.Java and .NET modules are available, which can be run from the command line or integrated into applications.

Saxonica also offers Saxon PE and EE versions, which are commercial products with technical support and redistribution rights.
Another JSON Schema Validator (AJV) Yes https://ajv.js.org/
Java-based open source tool for validating JSON files are compliant with JSON schema files.
node.js Yes https://nodejs.org
An asynchronous event driven JavaScript runtime, required to run AJV above.
Document Object Model (DOM) (aka DOMDocument) Yes https://www.w3.org/DOM/
A standard object-oriented model for manipulating XML files, which is built into many modern programming languages.DOM can manipulate XML content. Most implementations can also perform OSCAL syntax validation using OSCAL-published XSD files; however. Unfortunately, most implementations can only process XSLT and XPath 1.0 transformations, which is insufficient to use OSCAL's XSLT 3.0-based transformation files.

OSCAL Usage Examples

The following examples demonstrate the use of OSCAL.

Syntax Validation

This examples uses xmllint to perform validation of the XML syntax within an OSCAL file using a NIST-published XML Schema file. Each layer has its own XSD file for validation.

export schema="./oscal_catalog_schema.xsd"
export file="./catalog.xml"
xmllint --noout --schema schema file

This examples uses the DOMDocument model to perform validation of the XML syntax within an OSCAL file using a NIST-published XML Schema file. Each layer has its own XSD file for validation. (Example PHP code provided. Similar DOMDocument syntax is available in many popular programming languages, including VisualBasic/VBscript, PHP, and Python.)

// Enable user error handling
libxml_disable_entity_loader(false);
libxml_use_internal_errors(true);

$ns_alias = "oscal";
$oscal_schema_file = "c:\path\to\validation\file\oscal_catalog_schema.xsd";
$oscal_file = "c:\path\to\oscal\content\file\catalog.xml";

// Creates a memory object to handle the XML file
$oscal = new DOMDocument();

// Preserving white space is an option in the XML spec. 
// NOTE: Make sure this aligns with OSCAL's recommendation.
$oscal->preserveWhiteSpace = true; 

// Load the file and only proceed if there were no errors.
if (! $oscal->load($oscal_file) === false) { 

    // This just will let us see properly indented XML if we display it
    $oscal->formatOutput = true;        

    // OSCAL XML documents must have a namespace declared
    $ns = $oscal->documentElement->namespaceURI;

    if ($oscal->schemaValidate($oscal_schema_file)) {
        echo "ALL SYNTAX IS VALID!";
    } else {
        echo "SYNTAX VALIDATION ERRORS:";
        echo ("<br /><br />\n\n");
        $errors = libxml_get_errors();
        foreach ($errors as $error) {
            switch ($error->level) {
                case LIBXML_ERR_WARNING:
                    echo "Warning ";
                    break;
                case LIBXML_ERR_ERROR:
                    echo "Error ";
                    break;
                case LIBXML_ERR_FATAL:
                    echo "Fatal Error ";
                    break;
                }
                echo $error->code;
                echo ("<br />\n");
                echo $error->message;
                echo ("<br /><br />\n\n");
        }
        libxml_clear_errors();
    }
}

This examples uses AJV to perform validation of the JSON syntax within an OSCAL file using a NIST-published JSON Schema file. Each layer has its own XSD file for validation.

export schema="./oscal_catalog_schema.xsd"
export file="./catalog.xml"
ajv validate -s $schema -d $file --extend-refs=true --verbose

Conversion

This example uses Saxon HE to convert an OSCAL XML file to JSON using a NIST published XML to JSON XSLT file.

@echo off
cls
REM Path and file name to Java processor
set javaprocessor="java"

REM Path and file name of XSLT processor .jar file
set xmlprocessor=".\saxon9he.jar"

REM Path and file name of NIST OSCAL XSLT Conversion File 
set xslfile=".\oscal-catalog-xml-to-json-converter.xsl"

%javaprocessor% -jar %xmlprocessor% -s:%1 -o:%2 -xsl:%xslfile% json-indent=yes

This example uses Saxon HE to convert an OSCAL JSON file to XML using a NIST-published JSON to XML XSLT file.

@echo off
cls
REM Path and file name to Java processor
set javaprocessor="java"

REM Path and file name of XML processor .jar file
set xmlprocessor=".\saxon9he.jar"

REM Path and file name of NIST OSCAL XSLT Conversion File
set xslfile=".\oscal-catalog-json-to-xml-converter.xsl"

REM JSON file is a runtime parameter to the XSLT processor

%javaprocessor% -jar %xmlprocessor% -o:"%2" -xsl:%xslfile% -lt  json-file="%1

Extending OSCAL

OSCAL is designed to meet common cybersecurity information needs across multiple compliance regimes. It also provides organizations the ability to add information fields where OSCAL does not natively have an appropriate field. Always try to use a native OSCAL field first, and only extend OSCAL when no native syntax meets your organization's needs.

Extending OSCAL is accomplished through the use of "prop" and "part" elements. These may be added as child elements under any OSCAL element. "prop" should be used where there is one data item to represent, such as a title or date. "part" should be used where there is more than one piece of data that must be represented, such as an address containing street, city, state, and zip code.

Both "prop" and "part" have the following attributes available:

Optionally, "part" elements may also use an @id attribute.

Tools that process OSCAL content are not required to interpret unrecognized OSCAL extensions; however, OSCAL-compliant tools much not modify or remove unrecognized extensions, unless there is a compelling reason to do so, such as data sensitivity.

Best Practices and Recommendations for Extending OSCAL

Any organization that extends OSCAL should consistently assign @ns with a value that represents the organization, and then ensure each @name has a value that is unique. As a result, the combination of @ns and @name should always be unique and unambiguous, even when mixed with extensions from other organizations. @ns is required to ensure two different organizations can use the same value for @name without conflict.

For example, if FedRAMP and DoD both extend OSCAL, FedRAMP will ensure every "part" and "prop" added by FedRAMP has @ns=′fedramp′, while the DoD will ensure every "part" and "prop" added by DoD has @ns=′usdod′. If both FedRAMP and DoD need to add a status field for different reasons, there would be no conflict because:

Each organization is responsible for governance of their extensions, and is strongly encouraged to publish their extensions as standards to their user community. In the example above, FedRAMP is responsible for ensuring consistent use of @name values everyplace @ns=′fedramp′ exists. Similarly, DoD is responsible for ensuring consistent use of @name values everyplace @ns=′usdod′ exists.

The OSCAL Roadmap

The most recent and complete OSCAL Roadmap is always available here: https://pages.nist.gov/OSCAL/learnmore/roadmap/

Future OSCAL Compatibility Commitment

The NIST OSCAL Team recognizes the impact of syntax changes to a complex emerging language, and takes care to minimize the impact of any necessary changes. Syntax will only change where there is a compelling need to do so. To the greatest extend practical, OSCAL files will be future compatible.

Of course, NIST can not anticipate all issues or feedback. In rare cases, NIST may need to make exceptions to address a compelling issue. In these instances, NIST will do everything practical to minimize the impact to early adopters, and document any changes where impacts are unavoidable.

NIST encourages early adoption and feedback in the form of an issue posted to the NIST OSCAL GitHub page. If appropriate, we ask you add a comment to an existing relevant issue, and only create a new issue where no relevant issue exists.

In general early adopters can count on the following, from the milestone release to the first official 1.0 release of OSCAL:

Please direct any questions, comments, concerns, or kudos to oscal@nist.gov

brian-ruf commented 5 years ago

@david-waltermire-nist the above content is ready for review.

david-waltermire commented 5 years ago

@brianrufgsa I like the content, but I think most of it would be better placed on the site and in the repo. I started PR #416 to do this work. Checkout the new XML documentation to see what I am thinking.

I'd appreciate any thoughts you have on this (partial, work-in-progress) approach.

wendellpiez commented 5 years ago

I would also be willing to pitch in and add some useful hooks and pointers. Looks great so far!

david-waltermire commented 5 years ago

PR #421 also adds a "download" page to the OSCAL website. This PR will be pulled after the release is made.