Balisage Paper: SCAP Composer

1. SCAP Source Data Stream Collections

The Security Content Automation Protocol (SCAP — pronounced ess-cap) standard [1] contains a family of Extensible Markup Language (XML) [2] vocabularies for representing security content. System administrators use configuration checking and vulnerability scanning software tools that produce and consume SCAP data to secure servers, workstations, networks, and other deployed hardware and applications. United States government agencies and their service providers are required to use SCAP-conforming software products [3] and content [4] for security policy compliance checking and continuous monitoring of information technology assets. The private sector also relies on SCAP products and content for ensuring its information systems are protected. For example, banks and credit card companies use SCAP-conforming security configuration checklists [5] to verify compliance with the Payment Card Industry Data Security Standard [6]. Additionally, some private sector organizations use SCAP's XML vocabularies to develop security content for internal use, or to provide to their customers [7].

Central to the SCAP standard is the source data stream collection data model, an XML schema [8] defined in NIST Special Publication (SP) 800-126 (Technical Specification for the Security Content Automation Protocol) [9]. This schema specifies how to package, into a self-contained entity, the collective input required for an SCAP-conforming software product to assure a system is not overly vulnerable to cyberattack. The schema enables lossless exchange of security content between SCAP-conforming software products, allowing SCAP users to avoid vendor lock-in and to share source data stream collections within their organization or with partners.

But the same SCAP source data stream collection schema that promotes interoperability and shareability among SCAP-conforming software products also makes source data stream collection authoring hard. The reason why is that no schema can single-handedly meet the needs of SCAP scanner tool developers and SCAP content authors. Section 3 of this paper discusses use of the Darwin Information Typing Architecture (DITA) standard [10] to define a new source data stream collection XML document type for content authors. This new document type, which specializes DITA's map type, does not replace the SP 800-126 schema. Instead, the new DITA document type serves as an alternative that makes it easier for authors to express a source data stream collection. Section 4 describes SCAP Composer, a software application that implements the new, author-friendly document type and transforms valid instances of it into valid instances of the SP 800-126 schema. SCAP composer uses the DITA Open Toolkit [11]^[1], an open source DITA processor. The National Institute of Standards and Technology expects to make SCAP Composer available as open source software in late 2019.

Before delving into the authoring schema and application, it is important to understand why they are needed. Section 2 of this paper provides an overview of the NIST SP 800-126 schema's underlying data model — highlighting its advantages and drawbacks. But first it is instructive to see an example of SCAP in action. Figure 1 illustrates what an SCAP-conforming software product can do with a source data stream collection. The software depicted enables a user to open an SCAP source data stream collection file, view security checklists, and perform configuration and vulnerability scans. The checklists reside in the source data stream collection's checklist component, whose XML content conforms to the Extensible Configuration Checklist Description Format (XCCDF) specification [12]. XCCDF an XML vocabulary SCAP uses to represent security configuration rules. Clicking the Scan button causes the target system — either the local computer or a remote system — to be checked against the checklist to determine whether the checklist's rules are satisfied. Using this software to scan a remote target requires that an SCAP scanning client be installed on a remote system, and that the network allows secure upload of the SCAP source data stream collection file to that system.

Figure 1

SCAP-conforming scanning and tailoring software.

This software also provides a user interface for selecting a subset of rules from a checklist component, assigning parameters to the subset, and saving the result as a tailoring document. The tailoring document references the original checklist component without modifying the XML resource it contains, and thus promotes reuse of SCAP content.

The preceding discussion of Figure 1 suggests the following important requirements that the SP 800-126 schema must address:

2. The SP 800-126 Schema

Figure 2 provides a high-level example of an SCAP source data stream collection containing two data streams^[2] and five components. Each component encapsulates an XML resource conforming to an SCAP vocabulary schema (such as the schema for checklists). Each data stream represents a specific SCAP use case, for example, checking the configuration of a server running Ubuntu Linux version 16.04. Data streams reference components, as shown by the arrows. More than one data stream can reference the same component.

Figure 2

SCAP data stream collection.

Figure 2 does not capture two subtleties of SCAP source data stream collections. The first has to do with the part-whole relationship between a component and the XML resource it encapsulates. An XML resource typically exists outside the scope of a source data stream collection. For example, a checklist contained in a component may have been copied from its original residing in a security checklist repository. Therefore, one can think of a component as a snapshot of an XML resource at a specific point in time. Figure 3 illustrates this idea with two distinct components, each in a distinct source data stream collection, encapsulating the same XML resource. To capture this snapshot notion, the SP 800-126 schema represents a component as a wrapper element, with a time stamp attribute, surrounding a copy of the XML resource.

Figure 3

Components reusing the same XML resource.

The second subtlety pertains to component references — shown as directional arrows in Figure 2 and Figure 3. At first glance, it seems that an XLink simple link [13] can easily represent a component reference. But there is a less-than-obvious complication. A data stream collection might have two components, with one component's XML resource referencing the other component's XML resource. In fact, it is common in SCAP for a source data stream to have both a component containing a checklist resource and a component containing a check resource described in the Open Vulnerability Assessment Language (OVAL). OVAL [14] is an XML vocabulary for representing system configuration information, tests and states. An XCCDF checklist rule typically references check definitions in an OVAL resource that are used to determine if the current state of a system satisfies the rule criteria. XCCDF checklist rules and OVAL definitions together usually make up most of the XML data in a source data stream collection^[3].

Figure 4 shows a source data stream collection containing checklist and check components. The directional arrow labeled href indicates a reference from within a checklist rule to a check definition (each represented by a small square inside the XML resource). The problem is that the act of encapsulating the checklist and check resources into components in a source data stream collection breaks the internal references from checklist rules to check definitions. As an example, consider the following reference to a check definition from within a checklist rule:

<check-content-ref href="oval.xml" 
                   name="oval:nist.validation.family:def:1"/>

Figure 4

Checklist resource with URI reference to a check resource.

The SP 800-126 schema solves this problem by requiring that a data stream referencing a component with internal references to a location inside another component include a mapping. The mapping enables the source data stream collection consumer to translate internal references within the encapsulated XML resource to the corresponding component location within the source data stream collection. Figure 4 shows the mapping as dotted lines indicating a pair of URI references. The first URI reference is the relative URI reference inside the checklist rule. The second is the reference to the check component in the source data stream collection.

The SP 800-126 schema expresses the mapping using XML Catalogs standard [15] syntax. Figure 5 shows a possible XML representation of the reference to the checklist component shown in Figure 4. The component-ref element has an XLink simple link pointing to the component, whose identifier is scap_gov.nist_comp_content-xccdf. An embedded XML Catalogs uri element tells the source data stream collection consumer to translate internal references to oval.xml from within the checklist resource to references to the URI of the data stream component reference that points to the check component, #scap_gov.nist_cref_content-oval.

<component-ref id="scap_gov.nist_cref_content-xccdf"
   xlink:href="#scap_gov.nist_comp_content-xccdf">
   <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
      <uri name="oval.xml" 
           uri="#scap_gov.nist_cref_content-oval"/>
   </catalog>
</component-ref>

The long, verbose identifiers in Figure 5 are the result of a SP 800-126 requirement that data stream collections, data streams, components and component references have globally-unique identifiers (GUIDs). To this end, the schema requires the identifier format conventions shown in Table I. An identifier must be underscore-delimited, beginning with scap, followed by a reverse domain name system (DNS) style substring associated with the creator, followed by a substring indicating the object type being identified (collection, datastream, cref or comp), and ending with an XML NCName [16]. For example, a data stream containing the component reference shown in Figure 5 could have scap_gov.nist_datastream_example as its identifier. By requiring GUIDs, SP 800-126 reduces the likelihood of conflicting identifiers within a source data stream collection or identifiers that conflict with those in another organization's source data stream collection.

To recap, the SP 800-126 self-containment and reversibility requirements — although important for component integration and interoperability — result in added schema complexity and added pain for source data stream collection authors. The GUID format minimizes the possibility of ambiguous or dangling references, but it results in verbose, repetitive, and author-unfriendly identifiers. The SP 800-126 schema's underlying data model, hampered by XML's inability to intuitively express part-whole relationships between a component and its encapsulated XML resource, represents component references as first class objects using XML Catalogs to handle translation of resource-to-resource references from within the source data stream collection. This added complexity makes authoring a chore and impedes human readability of source data stream collections. Appendix A shows the source data stream collection XML that was read into the SCAP scanner software application shown in Figure 1. Figure 6 shows a less verbose, easier-to-read, and more author-friendly equivalent representation of this source data stream collection using the new DITA type discussed in Section 3.

3. The Source Data Stream Collection DITA Type

This section describes a new DITA element type for source data stream collections. The source data stream collection element type design arose from a conceptual implementation-agnostic information model developed to gain a deeper understanding of source data stream collections and how they achieve self-containment and reversibility. Reference [17] discusses the conceptual model and how it paved the way for an earlier DITA application. This paper provides a more implementation-focused perspective, with expanded discussions of DITA specialization in this section and DITA-OT implementation in Section 4.

DITA, developed by the Organization for the Advancement of Structured Information Standards (OASIS), is a standardized XML-based architecture for authoring, managing, reusing and transforming technical content [10]. DITA does not specify a schema or set of schemas per se. Instead, the DITA architecture provides:

The burden of following the rules for creating specializations and document type shells is a downside of DITA. But this burden falls mostly on developers of specializations. Content authors are not exposed to this burden. A DITA document's architectural attributes are defined by the document type shell using default values, hiding them — and their complexity — from content authors. More importantly, software application developers implementing a DITA specialization gain the benefit of inherited functionality, resulting in reduced implementation cost [18].

The source data stream collection element type is a specialization of DITA's map element type. The map element type was chosen for specialization because SCAP source data stream collections and data streams are map-like in nature. Like a DITA map, a source data stream collection is essentially a structured collection of components and references to components. Each source data stream collection element inherits from one of the following elements from the DITA map element type:

Table II lists all the XML elements and attributes in the source data stream collection element type's document type shell. The leftmost column contains the element names. The second column from the left specifies the DITA map element (either map, topicref, or keydef) from which the source data stream collection element inherits. The third column from the left shows the element's content model. *, + and ? indicate zero or more occurrences, one or more occurrences, and optional, respectively. The rightmost column specifies each element's attributes.

scapDataStreamCollection, the source data stream collection's root element, has three attributes. @reverseDNS provides the reverseDNS portion for all GUIDs in the collection. scapName provides the name portion of the collection's GUID. schematronVersion specifies which version of the SCAP Requirements Schematron [19] schema to use for validating that a transformation (discussed in Section 4) of the DITA map conforms to SP 800-126 requirements.

scapComponent represents a component. @keys, @href, and @scope are attributes defined in the DITA standard. In DITA, @keys provides a list of key names, but the source data stream collection element type further constrains it to represent a single key name. This succinct name may be used elsewhere in the DITA map in place of the XML resource URI (represented by @href) that the component encapsulates. This attribute enables source data stream collection authors to specify the URI in just one place and use the key name elsewhere in the DITA map. The optional @scope attribute specifies whether @href points to a local resource (the default) or an external resource on the Internet.

scapDataStream represents a source data stream. @scapName provides the name portion of the data stream's GUID. @scapVersion and @useCase correspond to required attributes in the SP 800-126 schema specifying the version of the SCAP standard to which the data stream content should conform, and the data stream's use case.

scapDictionaries, scapChecklists, and scapChecks aggregate groups of dictionary component references, checklist component references, and check component references, respectively.

scapCpeListRef, scapBenchmarkRef, scapTailoringRef, scapOvalRef, and scapOcilRef are all component references. @keyref, a DITA attribute, enables the author to specify the component being referenced using the short name corresponding to the scapComponent element's @keys value, saving authors the trouble of having to type the same URI multiple times, and minimizing the number of DITA map revisions needed if the URI changes. scapCpeListRef references a dictionary component that assigns identifiers to platforms (hardware, operating system, or software application) using SCAP's Common Platform Enumeration (CPE) nomenclature. These identifiers are typically used in checklist and check components for checking the presence of a device, operating system, or software product on the target system. scapBenchmarkRef, scapTailoringRef, scapOvalRef, and scapOcilRef reference a benchmark component, tailoring component, check component containing an OVAL check resource, and check component containing an Open Checklist Interactive Language (OCIL) check resource, respectively. OCIL is used for checking state via a human-oriented collection of information when OVAL-based methods are not feasible.

scapExternalLinks and scapUri together represent the mapping (shown in Figure 4) translating internal references within an encapsulated XML resource to the corresponding component location within the source data stream collection. @keyref is used to specify the component whose encapsulated XML resource is being referenced from within the component referenced by the parent element of scapExternalLinks. The optional @localUri is for overriding the URI obtained when DITA processing resolves the key reference specified in @keyref. This is needed when the referencing and referenced XML resources are in different local directories, or when one is external and the other is local.

Figure 6 lists a DITA map representing the data stream collection shown in Appendix A. This data stream collection contains one data stream and four components referenced by the data stream. The dictionary component and the check component referenced by the dictionary component encapsulate dictionary and check resources in the same directory as the DITA map. The benchmark component encapsulates a checklist resource in a subdirectory. Another check component encapsulates a check resource located externally (and has the value external for @scope). Because the dictionary and checklist resources both reference check resources, the dictionary component reference and benchmark component references contain scapExternalLinks and scapUri elements.

<scapDataStreamCollection reverseDNS="gov.nist" scapName="example" 
    schematronVersion="1.3">
    <scapComponent href="checklist-content/xccdf.xml" keys="content-xccdf"/>
    <scapComponent scope="external" keys="content-oval" href=
"https://raw.githubusercontent.com/usnistgov/sctools/master/dita/examples/
nist-example/checklist-content/oval.xml"/>
    <scapComponent href="cpe-oval.xml" keys="content-cpe-oval"/>
    <scapComponent href="cpe-dictionary.xml" keys="content-cpe-dictionary"/>
    <scapDataStream scapName="example" scapVersion="1.3" 
                    useCase="CONFIGURATION">
        <scapDictionaries>
            <scapCpeListRef keyref="content-cpe-dictionary">
                <scapExternalLinks>
                    <scapUri localUri="cpe-oval.xml" 
                             keyref="content-cpe-oval"/>
                </scapExternalLinks>
            </scapCpeListRef>
        </scapDictionaries>
        <scapChecklists>
            <scapBenchmarkRef keyref="content-xccdf">
                <scapExternalLinks>
                    <scapUri localUri="oval.xml" keyref="content-oval"/>
                </scapExternalLinks>
            </scapBenchmarkRef>
        </scapChecklists>
        <scapChecks>
            <scapOvalRef keyref="content-oval"/>
            <scapOvalRef keyref="content-cpe-oval"/>
        </scapChecks>
    </scapDataStream>
</scapDataStreamCollection>

4. SCAP Composer DITA Open Toolkit Implementation

The DITA Open Toolkit (DITA-OT) [11] meets the DITA standard's requirements for a specialization-aware, output-producing DITA processor. As such, DITA-OT merges topics referenced in a map and resolves key references, eliminating the need for custom transformation code to perform the functions. Because it is specialization-aware, DITA-OT inherits the processing behavior for elements in the source data stream collection element type from their supertypes. Thus, scapComponent inherits keydef's processing behavior, scapSourceDataStream inherits map's processing behavior, and the elements based on topicref inherit topicref's processing behavior. As a result, DITA-OT built-in functionality greatly reduced the coding effort required to implement SCAP Composer.

DITA-OT has a modular architecture with an extensible plug-in mechanism. SCAP Composer consists of two DITA-OT plug-ins:

SCAP Composer's source code consists principally of the following:

The flowchart in Figure 7 illustrates the workflow defined by the transformation plug-in's Ant script. This workflow begins when DITA-OT is invoked with sds (short for source data stream collection) as the output format argument. The plug-in accepts two additional optional arguments:

Figure 7

SCAP Composer transformation plug-in processing flow.

Processing begins with a preprocessing stage common to all transformation plug-ins. The preprocessing includes the merging and key reference resolution operations mentioned earlier. If sds.componentkey is specified, SCAPval validates the XML resource pointed to by the key's scapComponent element, and a validation report is produced as output (assuming sds.scapval is also specified; if not, processing stops with an error message). If sds.componentkey is not specified, the plug-in generates a single file in SP 800-126 schema format from the DITA map and XML resources. If sds.scapval is specified, the plug-in then validates the generated file and produces a validation report.

Suppose the source data stream collection DITA map file name is nist-example-hybrid.ditamap, and DITA-OT is invoked as follows:

dita -i nist-example-hybrid.ditamap -f sds --sds.scapval=scapval-1.3.2.jar

Figure 8

SCAPval validation report summary.

5. Discussion

SCAP Composer takes an incremental approach to aiding SCAP content authors. This is both a limitation and a strength. The limitation is that SCAP Composer only helps with creating source data stream collections. It does not offer any help with creating the XML resources encapsulated in a source data stream collection. Checklist and check resources are large, highly complex, and hard to create using conventional XML editing software applications. Reference [25] explores the feasibly of developing DITA element types for representing checklist rules and profiles (collections of rules), but more implementation and testing is needed to scale the proof-of-concept demonstration to real-world rule sets.

SCAP Composer's incrementalism is a strength in that its limited scope makes it easy both to deploy and integrate with other SCAP content development aids. SCAP Composer has no software dependencies other than DITA-OT, which runs in all common operating systems. SCAP Composer is not tethered to a larger SCAP software product or content repository infrastructure. This flexibility enables SCAP Composer to contribute to a larger authoring and content management solution by providing the piece responsible for creating source data stream collections, leaving it up to other mechanisms to produce and manage the XML resources to be encapsulated.

DITA-OT's extensible and customizable transformation workflow offers many possibilities for combining DITA processing with other capabilities. SCAP Composer exploits this to combine transformation from DITA to SP 800-126 XML with SCAPval validation and report generation. DITA-OT flexibility even allows a workflow with no DITA processing at all, as demonstrated by DITA-OT plug-in from Jason Fox [26] that automatically displays a random cat picture or XKCD comic strip as a splash screen while waiting for another plug-in's transformation to complete.

Although Fox's plug-in sounds frivolous, the same underlying idea can be practical in the context of SCAP Composer. For example, a future version of SCAP Composer could be supplemented with a decompose plug-in whose input includes an SP 800-126 schema-conforming source data stream collection, and whose output is the set of XML resources encapsulated by the components contained in the collection. Such a plug-in would perform no DITA processing yet would add useful and complementary functionality.

Software products that produce and manage SCAP are part of the broader research and development goal of modeling cybersecurity compliance requirements in a manner enabling them to be structured, organized, executed and reused efficiently [27]. SCAP Composer is a small contribution to this goal. Other efforts, such as the Compliance as Code open source project [28], are more ambitious. Compliance as Code contains a collection of compliance rules written in a YAML [29] format, OVAL XML fragments, as well as code fragments for automated remediation of compliance issues. A collection of build scripts generates SCAP source data stream collections and remediation scripts from the fragments. Another effort, ConfigValidator [30], is a system that checks a variety of targets — including running containers and cloud-based environments — for compliance with configuration rules written in a YAML-based declarative language.

The Compliance as Code and ConfigValidator projects have broader scopes and implement far more capabilities than SCAP Composer. However, both rely on one-off collections of scripts for processing compliance rules written in non-XML formats. Lack of standardization is a barrier to reusing the Compliance as Code and ConfigValidator technology in other projects. Also, both projects reject the use of XML for authoring compliance rules, claiming XML is hard for humans to edit. But, as SCAP Composer shows, XML is not the problem. The real problem is that, as discussed in Section 2, no single schema can meet all implementation requirements.

6. Conclusion

This paper describes SCAP Composer, a novel software application for creating and validating SCAP source data stream collections. What makes SCAP Composer unique is its use of DITA specialization and the DITA Open Toolkit to simplify the reuse of SCAP content while adhering to self-containment and reversibility requirements. Integration with SCAPval adds the ability for users to conveniently check source data stream collections and their components for conformance to SP 800-126. Other efforts to facilitate authoring and reuse of SCAP content rely on ad hoc authoring formats and extract/transform/load workflows, making them difficult to maintain or deploy in new projects. SCAP Composer is based on DITA, a robust architecture specifically for authoring and organization of topic-oriented information. Because it is standards-based and has a small footprint and scope, SCAP Composer is easy to integrate into a variety of SCAP authoring and deployment scenarios.