vertical logo
Table of Contents

1. Introduction

This documentation provides information about a command-line tool called oscap and its most common operations. With oscap you can check security configuration settings of a system, and examine the system for signs of a compromise by using rules based on standards and specifications. The oscap uses SCAP which is a line of specifications maintained by the NIST which was created to provide a standardized approach for maintaining system security. New specifications are governed by NIST’s SCAP Release cycle in order to provide a consistent and repeatable revision workflow. The oscap mainly processes the XCCDF which is a standard way of expressing a checklist content and defines security checklists. It also combines with other specifications such as CPE, CCE and OVAL to create a SCAP-expressed checklist that can be processed by SCAP-validated products. For more information about the SCAP please refer to SCAP Standards.

The oscap tool is a part of the OpenSCAP project. If you’re interested in a graphical alternative to this tool please visit SCAP Workbench page.

We will use the scap-security-guide SSG project to provide us the SCAP content. It provides security policies written in a form of SCAP documents covering many areas of computer security, and it implements security guidances recommended by respected authorities, namely PCI DSS, STIG, and USGCB.

You can also generate your own SCAP content if you have an understanding of at least XCCDF or OVAL. XCCDF content is also frequently published online under open source licenses, and you can customize this content to suit your needs instead. SCAP Workbench is a great tool to do the customization.

The Basic oscap usage section of the manual presents how to install the tool and SCAP content and how to use those to examine a SCAP content, perform a configuration scan or how to automatically remediate your machines.

Third section provides cover advanced topic like validation, signing and transformation of SCAP content, generating reports and guides and also some information about CPE applicability.

Last section contains information about debugging and compiling oscap on Linux and Windows which can be useful for developers.

2. Basic oscap Usage

If you want to perform configuration or vulnerability scans of a local system then the following must be available:

  1. A tool (oscap or SCAP Workbench)

  2. SCAP content (XCCDF, OVAL…​)

2.1. Installation

You can either build the OpenSCAP library and the oscap tool from source (for details please refer to the compiling section), or you can use an existing build for your Linux distribution. Use the following yum command if you want to install the oscap tool on your Fedora or Red Hat Enterprise Linux distribution:

# yum install openscap-scanner
Note
If the openscap-scanner is not available install openscap-utils instead.

Before you can start using the oscap tool you must have some SCAP content on your system. You can download it from the respective web site but we will use the SSG project in the following sections. You can build it from the source or you can install it using a package management system:

# yum install scap-security-guide

The SCAP content will be installed in /usr/share/xml/scap/ssg/content/.

When the SCAP content is imported or installed on your system, oscap can process the content by specifying the file path to the content. The oscap supports SCAP 1.2 and is backward compatible with SCAP 1.1 and SCAP 1.0. No special treatment is required in order to import and process earlier versions of the SCAP content.

To display the version of oscap, supported specifications, built-in CPE names, and supported OVAL objects, type the following command:

$ oscap -V

2.2. Displaying Information about SCAP Content

One of the capabilities of oscap is to display information about the SCAP contents within a file. Running the oscap info command allows the examination of the internal structure of a SCAP document and displays information such as the document type, specification version, status, the date the document was published (Generated) and the date the document was copied to file system (Imported). When examining an XCCDF document or a SCAP data stream, generally, the most useful information is about profiles, checklists, and streams.

The following example demonstrates usage and sample output of the command when target is SCAP data stream:

$ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
Document type: Source Data Stream
Imported: 2016-08-10T20:49:16

Stream: scap_org.open-scap_datastream_from_xccdf_ssg-rhel7-xccdf-1.2.xml
Generated: (null)
Version: 1.2
Checklists:
        Ref-Id: scap_org.open-scap_cref_ssg-rhel7-xccdf-1.2.xml
                Status: draft
                Generated: 2016-08-10
                Resolved: true
                Profiles:
                        xccdf_org.ssgproject.content_profile_standard
                        xccdf_org.ssgproject.content_profile_pci-dss
                        xccdf_org.ssgproject.content_profile_C2S
                        xccdf_org.ssgproject.content_profile_rht-ccp
                        xccdf_org.ssgproject.content_profile_common
                        xccdf_org.ssgproject.content_profile_stig-rhel7-workstation-upstream
                        xccdf_org.ssgproject.content_profile_stig-rhel7-server-gui-upstream
                        xccdf_org.ssgproject.content_profile_stig-rhel7-server-upstream
                        xccdf_org.ssgproject.content_profile_ospp-rhel7-server
                        xccdf_org.ssgproject.content_profile_nist-cl-il-al
                        xccdf_org.ssgproject.content_profile_cjis-rhel7-server
                Referenced check files:
                        ssg-rhel7-oval.xml
                                system: http://oval.mitre.org/XMLSchema/oval-definitions-5
                        ssg-rhel7-ocil.xml
                                system: http://scap.nist.gov/schema/ocil/2
                        http://www.redhat.com/security/data/oval/Red_Hat_Enterprise_Linux_7.xml
                                system: http://oval.mitre.org/XMLSchema/oval-definitions-5
Checks:
        Ref-Id: scap_org.open-scap_cref_ssg-rhel7-oval.xml
        Ref-Id: scap_org.open-scap_cref_ssg-rhel7-ocil.xml
        Ref-Id: scap_org.open-scap_cref_output--ssg-rhel7-cpe-oval.xml
        Ref-Id: scap_org.open-scap_cref_output--ssg-rhel7-oval.xml
Dictionaries:
        Ref-Id: scap_org.open-scap_cref_output--ssg-rhel7-cpe-dictionary.xml

and when XCCDF document is examined:

$ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel7-xccdf.xml
Document type: XCCDF Checklist
Checklist version: 1.1
Imported: 2016-08-10T20:49:16
Status: draft
Generated: 2016-08-10
Resolved: true
Profiles:
        standard
        pci-dss
        C2S
        rht-ccp
        common
        stig-rhel7-workstation-upstream
        stig-rhel7-server-gui-upstream
        stig-rhel7-server-upstream
        ospp-rhel7-server
        nist-cl-il-al
        cjis-rhel7-server
Referenced check files:
        ssg-rhel7-oval.xml
                system: http://oval.mitre.org/XMLSchema/oval-definitions-5
        ssg-rhel7-ocil.xml
                system: http://scap.nist.gov/schema/ocil/2
        http://www.redhat.com/security/data/oval/Red_Hat_Enterprise_Linux_7.xml
                system: http://oval.mitre.org/XMLSchema/oval-definitions-5

Document type describes what format the file is in. Common types include XCCDF, OVAL, Source Data Stream and Result Data Stream.

Checklist version is the XCCDF version only shown for XCCDF files. Common values are 1.1 and 1.2.

Imported is the date the file was imported for use with OpenSCAP. Since OpenSCAP uses the local filesystem and has no proprietary database format the imported date is the same as file modification date.

Status is the XCCDF Benchmark status. Common values include "accepted", "draft", "deprecated" and "incomplete". Please refer to the XCCDF specification for details. This is only shown for XCCDF files.

Generated date is the date the file was created / generated. This date is shown for XCCDF files and Checklists and is sourced from the XCCDF Status element.

Checklists lists available checklists incorporated in the Data Stream that you can use for the --benchmark-id command line attribute with oscap xccdf eval. Also each checklist has the detailed information printed.

Profiles lists available profile IDs that you can use for the --profile command line attribute with oscap xccdf eval.

2.2.1. More Information about Result Files (XCCDF and ARF)

oscap info is less helpful with XCCDF results and ARF files. Two important dates that are commonly requested are the evaluation start and end dates.

To look them up in the XCCDF result file, open the file and look for the TestResult element. The start-time and end-time attributes contain the evaluation times and dates.

<TestResult id="xccdf_org.open-scap_testresult_common" start-time="2017-01-21T19:16:28" end-time="2017-01-21T19:17:35"

To look up the dates in ARF file open the file and again look for the TestResult elements. The elements will be located in the arf:report elements.

<arf:reports>
  <arf:report id="xccdf1">
    <arf:content>
      <TestResult xmlns="http://checklists.nist.gov/xccdf/1.2" id="xccdf_org.open-scap_testresult_xccdf_org.ssgproject.content_profile_stig-rhel7-server-upstream" start-time="2017-01-20T14:30:18" end-time="2017-01-20T14:36:32"

You can also find both dates in a HTML report, table Evaluation characteristics. To generate HTML report from XCCDF result or ARF, use oscap xccdf generate report command.

2.3. Scanning with OSCAP

The main goal of the oscap tool is to perform configuration and vulnerability scans of a local system. Oscap is able to evaluate both XCCDF benchmarks and OVAL definitions and generate the appropriate results. Please note that SCAP content can be provided either in a single file (as an OVAL file or SCAP Data Stream), or as multiple separate XML files. The following examples distinguish between these approaches.

2.3.1. OVAL

The SCAP document can have a form of a single OVAL file (an OVAL Definition file). The oscap tool processes the OVAL Definition file during evaluation of OVAL definitions. It collects system information, evaluates it and generates an OVAL Result file. The result of evaluation of each OVAL definition is printed to standard output stream. The following examples describe the most common scenarios involving an OVAL Definition file.

  • To evaluate all definitions within the given OVAL Definition file, run the following command:

$ oscap oval eval --results oval-results.xml scap-oval.xml

Where scap-oval.xml is the OVAL Definition file and oval-results.xml is the OVAL Result file.

  • The following is an example of evaluating one particular definition within the given OVAL Definition file:

$ oscap oval eval --id oval:rhel:def:1000 --results oval-results.xml scap-oval.xml

Where the OVAL definition being evaluated is defined by the oval:rhel:def:1000 string, scap-oval.xml is the OVAL Definition file and oval-results.xml is the OVAL Result file.

  • To evaluate all definitions from the OVAL component that are part of a particular data stream within a SCAP data stream collection, run the following command:

$ oscap oval eval --datastream-id ds.xml --oval-id xccdf.xml --results oval-results.xml scap-ds.xml

Where ds.xml is the given data stream, xccdf.xml is an XCCDF file specifying the OVAL component, oval-results.xml is the OVAL Result file, and scap-ds.xml is a file representing the SCAP data stream collection.

When the SCAP content is represented by multiple XML files, the OVAL Definition file can be distributed along with the XCCDF file. In such a situation, OVAL Definitions may depend on variables that are exported from the XCCDF file during the scan, and separate evaluation of the OVAL definition(s) would produce misleading results. Therefore, any external variables has to be exported to a special file that is used during the OVAL definitions evaluation. The following commands are examples of this scenario:

$ oscap xccdf export-oval-variables --profile united_states_government_configuration_baseline usgcb-rhel5desktop-xccdf.xml
$ oscap oval eval --variables usgcb-rhel5desktop-oval.xml-0.variables-0.xml --results usgcb-results-oval.xml usgcb-rhel5desktop-oval.xml

Where united_states_government_configuration_baseline represents a profile in the XCCDF document, usgcb-rhel5desktop-xccdf.xml is a file specifying the XCCDF document, usgcb-rhel5desktop-oval.xml is the OVAL Definition file, usgcb-rhel5desktop-oval.xml-0.variables-0.xml is the file containing exported variables from the XCCDF file, and usgcb-results-oval.xml is the the OVAL Result file.

An OVAL directives file can be used to control whether results should be "thin" or "full". This file can be loaded by OpenSCAP using --directives <file> option.

Example of an OVAL directive file which enables thin results instead of full results:

<?xml version="1.0" encoding="UTF-8"?>
<oval_directives xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:oval="http://oval.mitre.org/XMLSchema/oval-common-5" xmlns:oval-res="http://oval.mitre.org/XMLSchema/oval-results-5" xmlns="http://oval.mitre.org/XMLSchema/oval-directives-5" xsi:schemaLocation="http://oval.mitre.org/XMLSchema/oval-results-5 oval-results-schema.xsd http://oval.mitre.org/XMLSchema/oval-common-5 oval-common-schema.xsd http://oval.mitre.org/XMLSchema/oval-directives-5 oval-directives-schema.xsd">
  <generator>
    <oval:product_name>OpenSCAP</oval:product_name>
    <oval:schema_version>5.8</oval:schema_version> <!-- make sure the OVAL version matches your input -->
    <oval:timestamp>2017-02-04T00:00:00</oval:timestamp>
  </generator>
  <directives include_source_definitions="true">
    <oval-res:definition_true reported="true" content="thin"/>
    <oval-res:definition_false reported="true" content="thin"/>
    <oval-res:definition_unknown reported="true" content="thin"/>
    <oval-res:definition_error reported="true" content="thin"/>
    <oval-res:definition_not_evaluated reported="true" content="thin"/>
    <oval-res:definition_not_applicable reported="true" content="thin"/>
  </directives>
</oval_directives>

If your use-case requires thin OVAL results you most likely also want to omit system characteristics. You can use the --without-syschar option to that effect.

Usage of OVAL directives file when scanning a plain OVAL file:

$ oscap oval eval --directives directives.xml --without-syschar --results oval-results.xml oval.xml

Usage of OVAL directives file when scanning OVAL component from a Source DataStream:

$ oscap oval eval --directives directives.xml --without-syschar --datastream-id ds.xml --oval-id oval.xml --results oval-results.xml scap-ds.xml

It is not always clear which OVAL file will be used when multiple files are distributed. In case you are evaluating an XCCDF file you can use:

$ oscap info ssg-rhel7-xccdf.xml
Document type: XCCDF Checklist
Checklist version: 1.1
Imported: 2017-01-20T14:20:43
Status: draft
Generated: 2017-01-19
Resolved: true
Profiles:
        standard
        pci-dss
        C2S
        rht-ccp
        common
        stig-rhel7-workstation-upstream
        stig-rhel7-server-gui-upstream
        stig-rhel7-server-upstream
        stig-rhevh-upstream
        ospp-rhel7-server
        nist-cl-il-al
        cjis-rhel7-server
        docker-host
        nist-800-171-cui
Referenced check files:
        ssg-rhel7-oval.xml
                system: http://oval.mitre.org/XMLSchema/oval-definitions-5
        ssg-rhel7-ocil.xml
                system: http://scap.nist.gov/schema/ocil/2
        https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2
                system: http://oval.mitre.org/XMLSchema/oval-definitions-5

In the output you can see all referenced check files. In this case we see that ssg-rhel7-oval.xml is referenced. To see contents of this file you can open it in a text editor.

You can use oscap info with Source DataStream files as well. Source DataStream will often reference OVAL files that are bundled in it. It is also possible to extract OVAL files from Source DataStream through oscap ds sds-split.

$ oscap ds sds-split ssg-rhel7-ds.xml extracted/
$ ls -1 extracted/
scap_org.open-scap_cref_output--ssg-rhel7-cpe-dictionary.xml
scap_org.open-scap_cref_ssg-rhel7-xccdf-1.2.xml
ssg-rhel7-cpe-oval.xml
ssg-rhel7-ocil.xml
ssg-rhel7-oval.xml

After splitting the Source DataStream you can inspect OVAL and XCCDF files individually using a text editor. Keep in mind that this is only an example and filenames depend on contents of the DataStream you are splitting and that you can also inspect XCCDF and OVAL content directly in Source DataStream or Result DataStream.

2.3.2. XCCDF

When evaluating an XCCDF benchmark, oscap usually processes an XCCDF file, an OVAL file and the CPE dictionary. It performs system analysis and produces XCCDF results based on this analysis. The results of the scan do not have to be saved in a separate file but can be attached to the XCCDF file. The evaluation result of each XCCDF rule within an XCCDF checklist is printed to standard output stream. The CVE and CCE identifiers associated with the rules are printed as well. The following is a sample output for a single XCCDF rule:

Title   Verify permissions on 'group' file
Rule    usgcb-rhel5desktop-rule-2.2.3.1.j
Ident   CCE-3967-7
Result  pass

The CPE dictionary is used to determine whether the content is applicable on the target platform or not. Any content that is not applicable will result in each relevant XCCDF rule being evaluated to "notapplicable".

The following examples show the most common scenarios of XCCDF benchmark evaluation:

  • To evaluate a specific profile in an XCCDF file run this command:

$ oscap xccdf eval --profile Desktop --results xccdf-results.xml --cpe cpe-dictionary.xml scap-xccdf.xml

Where scap-xccdf.xml is the XCCDF document, Desktop is the selected profile from the XCCDF document, xccdf-results.xml is a file storing the scan results, and cpe-dictionary.xml is the CPE dictionary.

  • You can additionaly add --rule option to the above command to evaluate a specific rule:

$ oscap xccdf eval --profile Desktop --rule ensure_gpgcheck_globally_activated  --results xccdf-results.xml --cpe cpe-dictionary.xml scap-xccdf.xml

Where ensure_gpgcheck_globally_activated is the only rule from the Desktop profile which will be evaluated.

2.3.3. Source DataStream

Commonly, all required input files are bundled together in Source DataStream. Scanning using Source DataStream is also handled by oscap xccdf eval command, with some additional parameters available to determine which of the bundled benchmarks should be performed.

  • To evaluate a specific XCCDF benchmark that is part of a DataStream within a SCAP DataStream collection, run the following command:

$ oscap xccdf eval --datastream-id ds.xml --xccdf-id xccdf.xml --results xccdf-results.xml scap-ds.xml

Where scap-ds.xml is a file representing the SCAP DataStream collection, ds.xml is the particular DataStream, xccdf.xml is ID of the component-ref pointing to the desired XCCDF document, and xccdf-results.xml is a file containing the scan results.

Note
If you omit --datastream-id on the command line, the first data stream from the collection will be used. If you omit --xccdf-id, the first component from the checklists element will be used. If you omit both, the first DataStream that has a component in the checklists element will be used - the first component in its checklists element will be used.
  • (Alternative, not recommended) To evaluate a specific XCCDF benchmark that is part of a DataStream within a SCAP DataStream collection run the following command:

$ oscap xccdf eval --benchmark-id benchmark_id --results xccdf-results.xml scap-ds.xml

Where scap-ds.xml is a file representing the SCAP DataStream collection, benchmark_id is a string matching the "id" attribute of xccdf:Benchmark containing in a component, and xccdf-results.xml is a file containing the scan results.

2.3.4. Result DataStream (ARF)

In the examples above we are generating XCCDF result files using the --results command-line argument. You can use --results-arf to generate a Result DataStream (also called ARF - Asset Reporting Format) XML instead.

$ oscap xccdf eval --benchmark-id benchmark_id --results-arf arf-results.xml scap-ds.xml

2.3.5. Result STIG Viewer

If you want to import the XCCDF scan results to DISA STIG Viewer but your Rule IDs don’t match the DISA’s ones, you can use the --stig-viewer command-line argument along with a special reference in your Rules to generate XCCDF result files that can be imported by DISA STIG Viewer.

$ oscap xccdf eval --profile stig-rhel7-disa --stig-viewer results-stig.xml ssg-rhel7-ds.xml

Each rule in the input XCCDF must contain a reference to its STIG Rule ID, and its href attribute must be exactly "http://iase.disa.mil/stigs/Pages/stig-viewing-guidance.aspx".

For example:

<Rule id="rpm_verify_permissions">
  ...
  <reference href="http://iase.disa.mil/stigs/Pages/stig-viewing-guidance.aspx">SV-86473r2_rule</reference>
  ...
</Rule>

For more information on DISA STIG Viewer click here.

2.4. Remediate System

OpenSCAP allows to automatically remediate systems that have been found in a non-compliant state. For system remediation, an XCCDF file with instructions is required. The scap-security-guide package contains certain remediation instructions.

System remediation consists of the following steps:

  1. oscap performs a regular XCCDF evaluation.

  2. An assessment of the results is performed by evaluating the OVAL definitions. Each rule that has failed is marked as a candidate for remediation.

  3. oscap searches for an appropriate fix element, resolves it, prepares the environment, and executes the fix script.

  4. Any output of the fix script is captured by oscap and stored within the rule-result element. The return value of the fix script is stored as well.

  5. Whenever oscap executes a fix script, it immediately evaluates the OVAL definition again (to verify that the fix script has been applied correctly). During this second run, if the OVAL evaluation returns success, the result of the rule is fixed, otherwise it is an error.

  6. Detailed results of the remediation are stored in an output XCCDF file. It contains two TestResult elements. The first TestResult element represents the scan prior to the remediation. The second TestResult is derived from the first one and contains remediation results.

There are three modes of operation of oscap with regard to remediation: online, offline, and review.

2.4.1. Online Remediation

Online remediation executes fix elements at the time of scanning. Evaluation and remediation are performed as a part of a single command.

To enable online remediation, use the --remediate command-line option. For example, to execute online remediation using the scap-security-guide package, run:

$ oscap xccdf eval --remediate --profile xccdf_org.ssgproject.content_profile_rht-ccp --results scan-xccdf-results.xml /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

The output of this command consists of two sections. The first section shows the result of the scan prior to the remediation, and the second section shows the result of the scan after applying the remediation. The second part can contain only fixed and error results. The fixed result indicates that the scan performed after the remediation passed. The error result indicates that even after applying the remediation, the evaluation still does not pass.

2.4.2. Offline Remediation

Offline remediation allows you to postpone fix execution. In first step, the system is only evaluated, and the results are stored in a TestResult element in an XCCDF file.

In the second step, oscap executes the fix scripts and verifies the result. It is safe to store the results into the input file, no data will be lost. During offline remediation, a new TestResult element is created that is based on the input one and inherits all the data. The newly created TestResult differs only in the rule-result elements that have failed. For those, remediation is executed.

To perform offline remediation using the scap-security-guide package, run:

$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_rht-ccp --results scan-xccdf-results.xml /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
$ oscap xccdf remediate --results scan-xccdf-results.xml scan-xccdf-results.xml

2.4.3. Remediation Review

The review mode allows users to store remediation instructions to a file for further review. The remediation content is not executed during this operation. To generate remediation instructions in the form of a shell script, run:

$ oscap xccdf generate fix --template urn:xccdf:fix:script:sh --profile xccdf_org.ssgproject.content_profile_rht-ccp --output my-remediation-script.sh /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

2.5. Check Engines

Most XCCDF content uses the OVAL check engine. This is when OVAL Definitions are being evaluated in order to assess a system. Complete information of an evaluation is recorded in OVAL Results files, as defined by the OVAL specification. By examining these files it’s possible check what definitions were used for the evaluation and why the results are as they are. Please note these files are not generated unless --oval-results is used.

Some content may use alternative check engines, for example the SCE check engine.

Results of rules with a check that requires a check engine not supported by OpenSCAP will be reported as notchecked. Check contents are not read or interpreted in any way unless the check system is known and supported. Following is an evaluation output of an XCCDF with unknown check system:

$ oscap xccdf eval sds-datastream.xml

Title   Check group file contents
Rule    xccdf_org.example_rule_system_authcontent-group
Result  notchecked

Title   Check password file contents
Rule    xccdf_org.example_rule_system_authcontent-passwd
Result  notchecked

Title   Check shadow file contents
Rule    xccdf_org.example_rule_system_authcontent-shadow
Result  notchecked

...
Note
The notchecked result is also reported for rules that have no check implemented. notchecked means that there was no check in that particular rule that could be evaluated.

2.5.1. CVE, CCE, CPE and other identifiers

Each XCCDF Rule can have xccdf:ident elements inside. These elements allow the content creator to reference various external identifiers like CVE, CCE, CPE and others.

When scanning, oscap output identifiers of scanned rules regardless of their results. For example:

Title   Ensure Repodata Signature Checking is Not Disabled For Any Repos
Rule    rule-2.1.2.3.6.a
Result  pass

Title   Verify user who owns 'shadow' file
Rule    rule-2.2.3.1.a
Ident   CCE-3918-0
Result  pass

Title   Verify group who owns 'shadow' file
Rule    rule-2.2.3.1.b
Ident   CCE-3988-3
Result  pass

All identifiers (if any) are printed to stdout for each rule. Since standard output doesn’t allow for compact identifier metadata to be displayed, only the identifiers themselves are displayed there.

Identifiers are also part of the HTML report output. If the identifier is a CVE you can click it to display its metadata from the official NVD database (requires internet connection). OpenSCAP doesn’t provide metadata for other types of identifiers.

Another place where these identifiers can be found are machine-readable Result Datastream files. This file can be generated during the scan by adding --results-arf option.

$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_common --fetch-remote-resources --results-arf results.xml /usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml

Result data stream file results.xml contains these identifiers in <rule-result> elements.

<rule-result idref="xccdf_org.ssgproject.content_rule_partition_for_tmp" time="2017-01-20T14:30:18" severity="low" weight="1.000000">
  <result>pass</result>
  <ident system="https://nvd.nist.gov/cce/index.cfm">CCE-27173-4</ident>
  <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5">
    <check-content-ref name="oval:ssg-partition_for_tmp:def:1" href="#oval0"/>
  </check>
</rule-result>

Since OpenSCAP 1.2.9 you can use the Group-By feature of HTML report to get an overview of results based on their identifiers and references.

The HTML report can also be used to look-up Rules by their identifiers. You can type the identifier (e.g.: CCE-27173-4) in the search box in the HTML report and only rules with this identifier will be shown. This can be used for any type of XCCDF identifier or reference. You can also click on the rule title to show more details and see all its identifiers, including the identifier you looked for. This relies heavily on SCAP content quality, if the identifiers are not present in the source content they will not be available in the HTML report.

If you want to map two identifiers — e.g.: map CCE identifier to NIST 800-53 identifier — you need to look-up the CCE ID in the HTML report through the search box using the first identifier. And then, by grouping by NIST SP 800-53 ID, you can see all NIST 800-53 IDs related to the searched CCE ID.

2.5.2. Bundled CCE data

OpenSCAP does not provide any static or product bundled CCE data. Thus it has no way of displaying the last generated, updated and officially published dates of static or product bundled CCE data because the dates are not defined.

3. Advanced oscap usage

3.1. Validating SCAP Content

Before you start using a security policy on your systems, you should first verify the policy in order to avoid any possible syntax or semantic errors in the policy. The oscap tool can be used to validate the security content against standard SCAP XML schemas. The validation results are printed to the standard error stream (stderr). The general syntax of such a validation command is the following:

$ scap module validate [module_options_and_arguments] file

where file is the full path to the file being validated. As a module you can use:

  • xccdf,

  • oval,

  • cpe or

  • cve.

The only exception is the data stream module (ds), which uses the sds-validate operation instead of validate. So for example, it would be like:

$ oscap ds sds-validate scap-ds.xml
Note
Note that all SCAP components within the given data stream are validated automatically and none of the components is specified separately.

You can also enable extra Schematron-based validation if you validate OVAL specification. This validation method is slower but it provides deeper analysis. Run the following command to validate an OVAL document using Schematron:

$ oscap oval validate --schematron oval-file.xml

The results of validation are printed to standard error stream (stderr).

Note
Please note that for the rest of oscap functionality, unless you specify --skip-valid, validation will automatically occur before files are used. Therefore, you do not need to explicitly validate a datastream before use.

3.2. SCAP Content Signing and Signature Verification

The oscap itself does not do signature verification. It skips over the respective elements. This is due to the fact that there are way too many options when it comes to keystores and crypto choices. Instead we recommend users to use xmlsec1 to verify their SCAP content. Safely evaluating signed content (with signature verification) involves the following steps:

1) Install xmlsec1 and at least one of its crypto engines

# yum install xmlsec1 xmlsec1-openssl

2) Run xmlsec1 --verify on the content:

This simple example will only show 2 specific cases of verifying the signature, the steps may vary depending on which technique was used to sign the datastream.

Assuming the datastream was signed with a private key and we have the respective public key to verify it with:

$ xmlsec1 --verify --pubkey-pem pub.key datastream.xml

Assuming the datastream was signed with a certificate and we have the respective public part of the certificate to verify it with:

$ xmlsec1 --verify --pubkey-cert-pem pubcert.key datastream.xml

There are countless other options, for more details see: xmlsec1 --help-verify

Successful output should look similar to this:

$ xmlsec1 verify --pubkey-pem key.pub datastream.xml
OK
SignedInfo References (ok/all): 1/1
Manifests References (ok/all): 0/0

And the exit code must be 0 before proceeding.

3) If the previous steps resulted in successful verification, proceed by evaluating the datastream:

$ oscap xccdf eval datastream.xml
Note
If you want to experiment with various crypto engines of xmlsec1, see xmlsec1-config --help

3.3. Generating Reports and Guides

Another useful features of oscap is the ability to generate SCAP content in a human-readable format. It allows you to transform an XML file into HTML or plain-text format. This feature is used to generate security guides and checklists, which serve as a source of information, as well as guidance for secure system configuration. The results of system scans can also be transformed to well-readable result reports. The general command syntax is the following:

$ oscap module generate sub-module [specific_module/sub-module_options_and_arguments] file

where module is either xccdf or oval, sub-module is a type of the generated document, and file represents an XCCDF or OVAL file. A sub-module can be either report, guide, custom or fix. Please see man oscap for more details.

3.4. Content Transformation

The oscap tool is also capable of using the XSLT (Extensible Stylesheet Language Transformations) language, which allows transformation of a SCAP content XML file into another XML, HTML, plain text or XSL document. This feature is very useful when you need the SCAP document in a human-readable form. The following commands represent the most common cases:

  • Creating a guide (see an example):

$ oscap xccdf generate guide scap-xccdf.xml > guide.html
  • Creating a guide with profile checklist (see an example):

$ oscap xccdf generate guide --profile Desktop scap-xccdf.xml > guide-checklist.html
  • Generating the XCCDF scan report (see an example):

$ oscap xccdf generate report xccdf-results.xml > report-xccdf.html
  • Generating the OVAL scan report (see an example):

$ oscap oval generate report oval-results.xml > report-oval.html
  • Generating the XCCDF report with additional information from failed OVAL tests (see an example):

$ oscap xccdf generate report --oval-template oval-results.xml xccdf-results.xml > report-xccdf-oval.html

3.5. CPE applicability

XCCDF rules in the content may target only specific platforms and hold no meaning on other platforms. Such an XCCDF rule contains an <xccdf:platform> element in its body. This element references a CPE name or CPE2 platform (defined using cpe2:platform-specification) that could be defined in a CPE dictionary file or a CPE language file or it can also be embedded directly in the XCCDF document.

An XCCDF rule can contain multiple <xccdf:platform> elements. It is deemed applicable if at least one of the listed platforms is applicable. If an XCCDF rule contains no <xccdf:platform> elements it is considered always applicable.

If the CPE name or CPE2 platform is defined in an external file, use the --cpe option and oscap auto-detects format of the file. The following command is an example of the XCCDF content evaluation using CPE name from an external file:

$ oscap xccdf eval --results xccdf-results.xml --cpe external-cpe-file.xml xccdf-file.xml

Where xccdf-file.xml is the XCCDF document, xccdf-results.xml is a file containing the scan results, and external-cpe-file.xml is the CPE dictionary or a language file.

If you are evaluating a source data stream, oscap automatically registers all CPEs contained within the data stream. No extra steps have to be taken. You can also register an additional external CPE file, as shown by the command below:

$ oscap xccdf eval --datastream-id ds.xml --xccdf-id xccdf.xml --results xccdf-results.xml --cpe additional-external-cpe.xml scap-ds.xml

Where scap-ds.xml is a file representing the SCAP data stream collection, ds.xml is the particular data stream, xccdf.xml is the XCCDF document, xccdf-results.xml is a file containing the scan results, and additional-external-cpe.xml is the additional CPE dictionary or language file.

The oscap tool will use an OVAL file attached to the CPE dictionary to determine applicability of any CPE name in the dictionary.

Apart from the instructions above, no extra steps have to be taken for content using cpe:fact-ref or cpe2:fact-ref. See the following sections for details on resolving.

3.5.1. xccdf:platform applicability resolution

When a CPE name or language model platform is referenced via <xccdf:platform> elements, resolution happens in the following order:

  1. Look into embedded CPE2 language model if name is found and applicable deem it applicable

  2. If not found or not applicable, look into external CPE2 language models (order of registration)

  3. If not found or not applicable, look into embedded CPE dictionary

  4. If not found or not applicable, look into external CPE dictionaries (order of registration)

If the CPE name is not found in any of the sources, it is deemed not applicable. If it is found in any of the sources but not applicable, we look for it elsewhere.

3.5.2. cpe:fact-ref and cpe2:fact-ref resolution

CPE name referenced from within fact-ref is resolved in the following order:

  1. Look into embedded CPE dictionary, if name is found and applicable deem it applicable

  2. If not found or not applicable, look into external CPE dictionaries (order of registration)

3.5.3. Built-in CPE Naming Dictionary

Apart from the external CPE Dictionaries, oscap comes with an inbuilt CPE Dictionary. The built-in CPE Dictionary contains only a few products (sub-set of Official CPE Dictionary) and it is used as a fall-back option when there is no other CPE source found.

The list of inbuilt CPE names can be found in the output of

$ oscap --version

You can file a request to include any additional product in the built-in dictionary via open-scap mailing list or bugzilla.

3.6. Notes on the Concept of Multiple OVAL Values

This section describes advanced concepts of OVAL Variables and their implementation in oscap. The SCAP specification allows for an OVAL variable to have multiple values during a single assessment run. There are two variable modes which can be combined:

  • Multival — A variable is assigned with multiple values at the same time. As an example, consider a variable which refers to preferred permission of a given file, that may take multiple values like: '600', '400'. The evaluation tries to match each (or all) and then outputs a single OVAL Definition result.

  • Multiset — A variable is assigned with a different value (or multival) for different evaluations. This is known as a variable_instance. As an example consider an OVAL definition which checks that a package given by a variable is not installed. For the first evaluation of the definition, the variable can be assigned with 'telnet-server' value, for second time the variable can be assigned with 'tftp-server' value. Therefore both evaluations may output different results. Thus, the OVAL Results file may contain multiple results for the same definition, these are distinguished by variable_instance attribute.

These two concepts are a source of confusion for both the content authors and the result consumers. On one hand, the first concept is well supported by the standard and the OVAL Variable file format. It allows multiple <value> elements for each <variable> element. On the other hand, the second concept is not supported by an OVAL Variable schema which prevents fully automated evaluation of the multisets (unless you use XCCDF to bridge that gap).

Tip
oscap supports both variable modes as described below.

3.6.1. Sources of Variable Values

First we need to understand how a single value can be bound to a variable in the OVAL checking engine. There are three ways to do this:

1) OVAL Variables File — The values of external variables can be defined in an external file. Such a file is called an OVAL Variable File and can be recognized by using the following command: oscap info file.xml. The OVAL Variables file can be passed to the evaluation by --variables argument such as:

$ oscap oval eval --variables usgcb-rhel5desktop-oval.xml-0.variables-0.xml --results usgcb-results-oval.xml usgcb-rhel5desktop-oval.xml

2) XCCDF Bindings — The values of external variables can be given from an XCCDF file. In the XCCDF file within each <xccdf:check> element, there might be <xccdf:check-export> elements. These elements allow transition of <xccdf:value> elements to <oval:variables> elements. The following command allows users to export variable bindings from XCCDF to an OVAL Variables file:

$ oscap xccdf export-oval-variables --profile united_states_government_configuration_baseline usgcb-rhel5desktop-xccdf.xml

3) Values within an OVAL Definition File — Variables' values defined directly in the OVAL definitions file <constant_variable> and <local_variable> elements.

3.6.2. Evaluation of Multiple OVAL Values

With oscap, there are two possible ways how two or more values can be specified for a variable used by one OVAL definition. The approach you choose depends on what mode you want to use, multival or multiset.

The oscap handles multiple OVAL values seemlessly; such that user doesn’t need to do anything differently than what she (or he) does for a normal scan. The command below demonstrates evaluation of DataStream, which may include multiset, multival, or both concepts combined, or none of them.

$ oscap xccdf eval --profile my_baseline --results-arf scap-arf.xml --cpe additional-external-cpe.xml scap-ds.xml

3.6.3. Multival

Multival can pass multiple values to a single OVAL definition evaluation. This can be accomplished by all three ways as described in previous section.

1) OVAL Variables file — This option is straight forward. The file format (XSD schema) allows for multiple <value> elements within each <variable> element.

  <variable id="oval:com.example.www:var:1" datatype="string" comment="Unknown">
    <value>600</value>
    <value>400</value>
  </variable>

2) XCCDF Bindings — Use multiple <xccdf:check-export> referring to the very same OVAL variable binding with multiple different XCCDF values.

  <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5">
    <check-export value-id="xccdf_com.example.www_value_1" export-name="oval:com.example.www:var:1"/>
    <check-export value-id="xccdf_com.example.www_value_2" export-name="oval:com.example.www:var:1"/>
    <check-content-ref href="my-test-oval.xml" name="oval:com.example.www:def:1"/>
  </check>

3) Values within OVAL Definitions file — This is similar to using a Variables file, there are multiple <value> elements allowed within <constant_variable> or <local_variable> elements.

3.6.4. Multiset

Multiset allows for the very same OVAL definition to be evaluated multiple times using different values assigned to the variables for each evaluation. In OpenSCAP, this is only possible by option (2) XCCDF Bindings. The following XCCDF snippet evaluates twice the very same OVAL Definition, each time it binds a different value to the OVAL variable.

  <Rule id="xccdf_moc.elpmaxe.www_rule_1" selected="true">
    <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5">
      <check-export value-id="xccdf_moc.elpmaxe.www_value_1" export-name="oval:com.example.www:var:1"/>
      <check-content-ref href="my-test-oval.xml" name="oval:com.example.www:def:1"/>
    </check>
  </Rule>
  <Rule id="xccdf_moc.elpmaxe.www_rule_2" selected="true">
    <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5">
      <check-export value-id="xccdf_moc.elpmaxe.www_value_2" export-name="oval:com.example.www:var:1"/>
      <check-content-ref href="my-test-oval.xml" name="oval:com.example.www:def:1"/>
    </check>
  </Rule>

After the evaluation, the OVAL results file will contain multiple result-definitions and multiple result-tests and multiple collected-objects. The elements of the same id will be differentiated by the value of the variable_instance attribute. Each of the definitions/tests/object might have a different result of evaluation. The following snippet of OVAL results file illustrates output of a multiset evaluation.

    <tests>
      <test test_id="oval:com.example.www:tst:1" version="1" check="at least one" result="true" variable_instance="1">
        <tested_item item_id="1117551" result="true"/>
        <tested_variable variable_id="oval:com.example.www:var:1">600</tested_variable>
      </test>
      <test test_id="oval:com.example.www:tst:1" version="1" check="at least one" result="false" variable_instance="2">
        <tested_item item_id="1117551" result="false"/>
        <tested_variable variable_id="oval:com.example.www:var:1">400</tested_variable>
      </test>
    </tests>

3.7. External or remote resources

Some SCAP content references external resources. For example SCAP Security Guide uses external OVAL file to check that the system is up to date and has no known security vulnerabilities. However, other content can use external resources for other purposes.

When you are evaluating SCAP content with external resources the oscap tool will warn you:

$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_common /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
WARNING: This content points out to the remote resources. Use `--fetch-remote-resources' option to download them.
WARNING: Skipping https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2 file which is referenced from XCCDF content

By default the oscap tool will not blindly download and execute remote content. If you trust your local content and the remote content it references, you can use the --fetch-remote-resources option to automatically download it using the oscap tool.

$ oscap xccdf eval --fetch-remote-resources --profile xccdf_org.ssgproject.content_profile_common /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
Downloading: https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2 ... ok
Title   Ensure /var/log Located On Separate Partition
Rule    xccdf_org.ssgproject.content_rule_partition_for_var_log
...

3.8. Evaluating XCCDF rules with multiple checks

Normally, each XCCDF rule references to a single check with a specified name. However, if @name attribute of xccdf:check-content-ref of a given rule is omitted, multiple checks can be executed to evaluate the rule. This is common for security_patches_up_to_date check. By default, only a single result is produced for an XCCDF rule in such case, and the result is computed from all results of checks in the referenced location. In case user wants to see separate results for each check (one xccdf:check-result element in results document for each check evaluated), then multi-check attribute of xccdf:check element must be set to true.

   <Rule id="xccdf_org.nist-testsuite.content_rule_security_patches_up_to_date" selected="false" weight="10.0">
      <title xml:lang="en-US">Security Patches Up-To-Date</title>
      <description xml:lang="en-US">All known security patches have been installed.</description>
      <requires idref="xccdf_org.nist-testsuite.content_group_CM-6"/>
      <requires idref="xccdf_org.nist-testsuite.content_group_SI-2"/>
      <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5" multi-check="true">
        <check-content-ref href="r1100-scap11-win_rhel-patches.xml"/>
      </check>
    </Rule>

In XCCDF specification older than 1.2, the multi-check element is not defined, which means that only a single result is always produced. To produce separate results for each check from the content older than XCCDF version 1.2, you need to convert it first into XCCDF 1.2 using the following command:

$ xsltproc --stringparam reverse_DNS com.example.www /usr/share/openscap/xsl/xccdf_1.1_to_1.2.xsl xccdf.xml > xccdf-1.2.xml

And then patch the content using a text editor, adding multi-check as shown in the example Rule snippet above.

To create a source DataStream from the patched content, the following command can be used:

$ oscap ds sds-compose xccdf-1.2.xml source_ds.xml

If the original XCCDF file referenced a custom CPE dictionary, you also have to inject the CPE dictionary into the DataStream in order to create a valid source DataStream. To add a CPE dictionary component into your DataStream in place, use this command:

$ oscap ds sds-add cpe_dictionary.xml source_ds.xml

Now the source_ds.xml DataStream can be evaluated as usual.

4. Practical Examples

This section demonstrates practical usage of certain security content provided for Red Hat products.

These practical examples show usage of industry standard checklists that were validated by NIST.

4.1. Auditing System Settings with SCAP Security Guide

The SSG project contains guidance for settings of Red Hat Enterprise Linux 7.

1) Install the SSG

$ sudo yum install -y scap-security-guide

2) To inspect the security content use the oscap info module:

$ oscap info /usr/share/xml/scap/ssg/rhel7/ssg-rhel7-ds.xml

The output of this command contains available configuration profiles. To audit your system settings choose the xccdf_org.ssgproject.content_profile_rht-ccp profile and run the evaluation command . For example, the The following command is used to assess the given system against a draft SCAP profile for Red Hat Certified Cloud Providers:

 $ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_rht-ccp
--results ssg-rhel7-xccdf-result.xml --report ssg-rhel7-report.html
/usr/share/xml/scap/ssg/rhel7/ssg-rhel7-ds.xml

4.2. Auditing Security Vulnerabilities of Red Hat Products

The Red Hat Security Response Team provides OVAL definitions for all vulnerabilities (identified by CVE name) that affect Red Hat Enterprise Linux 3, 4, 5, 6 and 7. This enable users to perform a vulnerability scan and diagnose whether system is vulnerable or not. The data is provided in three ways — OVAL file, OVAL + XCCDF and a Source DataStream.

4.2.1. OVAL + XCCDF

1) Download the content

$ wget https://www.redhat.com/security/data/metrics/com.redhat.rhsa-all.xccdf.xml
$ wget https://www.redhat.com/security/data/oval/com.redhat.rhsa-all.xml

2) Run the scan

$ oscap xccdf eval --results results.xml --report report.html com.redhat.rhsa-all.xccdf.xml

This is the sample output. It reports that Red Hat Security Advisory (RHSA-2013:0911) was issued but update was not applied so a system is affected by multiple CVEs (CVE-2013-1935, CVE-2013-1943, CVE-2013-2017)

Title   RHSA-2013:0911: kernel security, bug fix, and enhancement update (Important)
Rule    oval-com.redhat.rhsa-def-20130911
Ident   CVE-2013-1935
Ident   CVE-2013-1943
Ident   CVE-2013-2017
Result  fail

Human readable report report.html is generated, as well as "machine" readable report results.xml. Both files hold information about vulnerability status of scanned system. They map RHSA to CVEs and report what security advisories are not applied to the scanned system. CVE identifiers are linked with National Vulnerability Databases where additional information like CVE description, CVSS score, CVSS vector, etc. are stored.

4.2.2. OVAL only

1) Download the content

$ wget https://www.redhat.com/security/data/oval/com.redhat.rhsa-all.xml

2) Run the scan

$ oscap oval eval --results results.xml --report report.html com.redhat.rhsa-all.xml

This is the sample output. It reports that Red Hat Security Advisory (RHSA-2013:0911) was issued but update was not applied. Notice that the standard output is different from the XCCDF + OVAL output.

Definition oval:com.redhat.rhsa:def:20130911: true

As in case of XCCDF+OVAL, human readable report report.html, and "machine" readable report results.xml are generated. Look of report.html is different to the one generated when XCCDF checklist is used as a basis for the scan, the information in it again holds information about vulnerability status of scanned system, and mapping of RHSA to CVEs. CVE identifiers are linked with Red Hat database where additional information like CVE description, CVSS score, CVSS vector etc. are stored.

4.2.3. Source DataStream

The Source DataStream use-case is very similar to OVAL+XCCDF. The only difference is that you don’t have to download two separate files.

1) Download the content

$ wget https://www.redhat.com/security/data/metrics/ds/com.redhat.rhsa-all.ds.xml

2) Run the scan

$ oscap xccdf eval --results results.xml --report report.html com.redhat.rhsa-all.ds.xml

4.2.4. More Specialized Files

The files we used above cover multiple Red Hat products. If you only want to scan one product - for example a specific version of Red Hat Enterprise Linux - we advise to download a smaller specialized file covering just this one version. Using a smaller file will utilitize less bandwidth and make the evaluation quicker.

For example for Red Hat Enterprise Linux 7 the plain OVAL file is located at:

$ wget https://www.redhat.com/security/data/oval/Red_Hat_Enterprise_Linux_7.xml

You can get a list of all the plain OVAL files by visiting https://www.redhat.com/security/data/oval/

The list of available datastream files is available at https://www.redhat.com/security/data/metrics/ds/

4.2.5. Disclaimer

Note
Note that these OVAL definitions are designed to only cover software and updates released by Red Hat. You need to provide additional definitions in order to detect the patch status of third-party software.

To find out more information about this project, see https://www.redhat.com/security/data/metrics/.

4.3. How to Evaluate PCI-DSS on RHEL7

This section describes how to evaluate the Payment Card Industry Data Security Standard (PCI-DSS) on Red Hat Enterprise Linux 7.

1) Install SSG which provides the PCI-DSS SCAP content

$ sudo yum install -y scap-security-guide

2) Verify that the PCI-DSS profile is present

$ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

3) Evaluate the PCI-DSS content

$ oscap xccdf eval --results results.xml --profile xccdf_org.ssgproject.content_profile_pci-dss /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

4) Generate report readable in a web browser.

$ oscap xccdf generate report --output report.html results.xml

4.4. How to Evaluate DISA STIG

This section describes how to evaluate the Defense Information Systems Agency (DISA) Security Technical Implementation Guide (STIG) on Red Hat Eneterprise Linux 6.

1) Download the DISA STIG content.

$ wget http://iasecontent.disa.mil/stigs/zip/July2015/U_RedHat_6_V1R8_STIG_SCAP_1-1_Benchmark.zip

2) Unpack the content.

$ unzip U_RedHat_6_V1R8_STIG.zip

3) Fix the content using a sed substitution.

$ sed -i 's/<Group\ \(.*\)/<Group\ selected="false"\ \1/g' U_RedHat_6_V1R8_STIG_SCAP_1-1_Benchmark-xccdf.xml
Note
Why is the substitution needed? According to the XCCDF specification 1.2 the selected attribute for Rule or Group is true by default. It means that if you create a new profile even with only one rule selected, all rules within the benchmark will be evaluated because they are set to true by default. The substitution will set all Groups as unselected by default which means all descendants will also be unselected by default.

4) Display a list of available profiles.

$ oscap info U_RedHat_6_V1R8_STIG_SCAP_1-1_Benchmark-xccdf.xml

5) Evaluate your favorite profile, for example MAC-1_Public, and write XCCDF results into the results.xml file.

$ oscap xccdf eval --profile MAC-1_Public --results results.xml --cpe U_RedHat_6_V1R8_STIG_SCAP_1-1_Benchmark-cpe-dictionary.xml U_RedHat_6_V1R8_STIG_SCAP_1-1_Benchmark-xccdf.xml

6) Generate a scan report that is readable in a web browser.

$ oscap xccdf generate report --output report.html results.xml

If you are interested in DISA STIG content for RHEL5 or RHEL7 please visit National Vulnerability Database and look for Red Hat Enterprise Linux 6 or Red Hat Enterprise Linux 7 as a target product.

4.5. How to Evaluate United States Government Configuration Baseline (USGCB)

Note
NIST offers no official USGCB for RHEL6 as of September 2014 but you can acquire the content from the SSG project.

The USGCB content for represents Tier IV Checklist for Red Hat Enterprise Linux 5 (as defined by NIST Special Publication 800-70).

Warning
Proper evaluation of the USGCB document requires OpenSCAP version 0.9.1 or later.

After ensuring that version of OpenSCAP on your system is sufficient, perform the following tasks:

1) Download the USGCB content.

$ wget http://usgcb.nist.gov/usgcb/content/scap/USGCB-rhel5desktop-1.2.5.0.zip

2) Unpack the USGCB content.

$ unzip USGCB-rhel5desktop-1.2.5.0.zip

3) Run evaluation of the USGCB content.

$ oscap xccdf eval --profile united_states_government_configuration_baseline --cpe usgcb-rhel5desktop-cpe-dictionary.xml --oval-results --fetch-remote-resources --results results.xml usgcb-rhel5desktop-xccdf.xml

4) Generate a scan report that is readable in a web browser.

$ oscap xccdf generate report --output report.html results.xml

Additional reports can be generated from detailed OVAL result files. Scanner outputs OVAL results files in the current directory, for each OVAL file on input there is one output. In case of USGCB, there is one OVAL file distributed along the XCCDF, another one which is downloaded from Red Hat Repository. The latter contains CVE information for each evaluated definition.

$ oscap oval generate report --output oval-report-1.html usgcb-rhel5desktop-oval.xml.result.xml
$ oscap oval generate report --output oval-report-2.html http%3A%2F%2Fwww.redhat.com%2Fsecurity%2Fdata%2Foval%2Fcom.redhat.rhsa-all.xml.result.xml

If you’re interested in runing evaluation of the USGCB on a remote machine using a GUI please see: Evaluate Remote Machine for USGCB Compliance with SCAP Workbench tutorial.

4.6. How to Evaluate Third-Party Guidances

The SCAP content repository hosted at National Vulnerability Database (NVD) can be searched for publicly available guidances for a given product. For example, as per 2013/05/11 there are two Tier III checklists for Red Hat Enterprise Linux 5. Analogously, the MITRE Corp. hosts repository of OVAL content for various platforms, sorted by versions and classes.

Likewise the USGCB, any downloaded guidance can be evaluated by OpenSCAP.

  • Examplary evaluation of DoD Consensus Security Configuration Checklist for Red Hat Enterprise Linux 5 (2.0)

$ wget http://nvd.nist.gov/ncp/DoD-RHEL5-desktop.zip
$ unzip DoD-RHEL5-desktop.zip
$ oscap xccdf eval --profile DOD_baseline_1.0.0.1 --cpe dcb-rhel5_cpe-dictionary.xml --results result.xml --oval-results dcb-rhel5_xccdf.xml
  • Examplary evaluation of Red Hat 5 STIG Benchmark (Version 1, Release 12)

$ wget http://iasecontent.disa.mil/stigs/zip/July2015/U_RedHat_5_V1R12_STIG_SCAP_1-1_Benchmark.zip
$ unzip U_RedHat_5_V1R12_STIG_SCAP_1-1_Benchmark.zip
$ oscap xccdf eval --profile MAC-2_Public --cpe
U_RedHat_5_V1R12_STIG_SCAP_1-1_Benchmark-cpe-dictionary.xml --results result.xml
--oval-results U_RedHat_5_V1R12_STIG_SCAP_1-1_Benchmark-xccdf.xml

Furthermore, any individual file from the archive can be inspected using the oscap info command line option. The oscap program does not have the concept of importing SCAP files, therefore it can process any SCAP files available on the filesystem. That is possible because the SCAP standard files are native file formats of the OpenSCAP.

4.7. How to evaluate guidances for Red Hat Enterprise Linux 6 or 7

Guidances for Red Hat Enterprise Linux 6 and 7 can be acquired from SCAP Security Guide project (SSG). SSG holds currently the most evolved and elaborate SCAP policy for Linux systems. The project provides practical security hardening advice for Red Hat products and also links it to compliance requirements in order to ease deployment activities, such as certification and accreditation.

The project started in 2011 as open collaboration of U.S. Government bodies to develop next generation of United States Government Baseline (USGCB) available for Red Hat Enterprise Linux 6. There are multiple parties contributing to the project from the public sector and private sector.

The SSG project contains baselines for both desktops and servers. See https://github.com/OpenSCAP/scap-security-guide

4.8. How to check that patches are up-to-date on Red Hat Enterprise Linux 6 or 7

This section describes how to check that software patches are up-to-date using external OVAL content.

1) Install the SSG

$ sudo yum install -y scap-security-guide

2a) Evaluate common profile for RHEL 6

$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_common --fetch-remote-resources --results-arf results.xml /usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml

2b) Evaluate common profile for RHEL 7

$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_common --fetch-remote-resources --results-arf results.xml /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

This command evaluates common profile for Red Hat Enterprise Linux 6 or 7. Part of the profile is a rule to check that patches are up-to-date. To evaluate the rule correctly, oscap tool needs to download an up-to-date OVAL file from Red Hat servers. This can be allowed using --fetch-remote-resources option. Result of this scan will be saved in results.xml using ARF format.

4.9. How to tailor Source data stream

This section describes tailoring of content using Tailoring file. This allows you to change behavior of content without its direct modification.

1) Obtain tailoring file

Tailoring file can be easily generated using SCAP Workbench.

2) List profiles of tailoring file

$ oscap info
Document type: XCCDF Tailoring
Imported: 2016-08-31T11:08:16
Benchmark Hint: /usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml
Profiles:
	xccdf_org.ssgproject.content_profile_C2S_customized

3) Evaluate

$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_C2S_customized --tailoring-file ssg-rhel6-ds-tailoring.xml --results results.xml /usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml

The command above evaluates tailored data stream by ssg-rhel6-ds-tailoring.xml tailoring file. XCCDF results can be found in results.xml file.

Instead of external tailoring file, you can also use tailoring component integrated to data stream.

$ oscap info simple-ds.xml
Document type: Source Data Stream
Imported: 2016-02-02T14:06:14

Stream: scap_org.open-scap_datastream_from_xccdf_simple-xccdf.xml
Generated: (null)
Version: 1.2
Checklists:
	Ref-Id: scap_org.open-scap_cref_simple-xccdf.xml
		Status: incomplete
		Resolved: false
		Profiles:
			xccdf_org.open-scap_profile_override
		Referenced check files:
			simple-oval.xml
				system: http://oval.mitre.org/XMLSchema/oval-definitions-5
	Ref-Id: scap_org.open-scap_cref_simple-tailoring.xml
		Benchmark Hint: (null)
		Profiles:
			xccdf_org.open-scap_profile_default
			xccdf_org.open-scap_profile_unselecting
			xccdf_org.open-scap_profile_override
Checks:
	Ref-Id: scap_org.open-scap_cref_simple-oval.xml
No dictionaries.

To choose tailoring component "scap_org.open-scap_cref_simple-tailoring.xml", the command below can be used.

$ oscap xccdf eval --tailoring-id scap_org.open-scap_cref_simple-tailoring.xml --profile xccdf_org.open-scap_profile_default --results results.xml simple-ds.xml

The command above evaluates content using tailoring component scap_org.open-scap_cref_simple-tailoring.xml from source data stream. Scan results are stored in results.xml file.

4.10. Evaluation of content

Specified XCCDF or data stream content can contain zero or more profiles.

Scan can be evaluated without specific profile, otherwise profile can be selected using --profile option.

$ oscap xccdf eval --results results.xml /usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml

The command above evaluates rules without specific profile. XCCDF results are stored in results.xml file.

5. Other utilities

Apart from the oscap command, OpenSCAP provides also other utilities for special purposes. Those utilities use oscap under the hood, but they enable users to perform advanced tasks in a single command. This manual gives a quick overview of and shows basic usage of these tools. Each of the tools have its own manual page that gives more detailed information.

5.1. Scanning remote machines using oscap-ssh

The oscap-ssh is a simple tool for scanning remote machines with OpenSCAP over network and collecting results.

The tool uses SSH connection to copy the SCAP content to a remote machine, then it runs an evaluation of the target system and downloads the results back. The remote machine needs to have OpenSCAP installed.

The tool can evaluate source DataStreams and OVAL files. Usage of the tool mimics usage and options of oscap tool.

In the following example, we will scan a remote Fedora server located on IP address 192.168.1.13 that listens for SSH connections on port 22. The server will be scanned for compliance with the Common Profile for General-Purpose Fedora Systems provided by SCAP Security Guide. HTML report is written out as report.html on the local machine.

$ oscap-ssh root@192.168.1.13 22 xccdf eval --profile xccdf_org.ssgproject.content_profile_common --report report.html /usr/share/xml/scap/ssg/content/ssg-fedora-ds.xml

5.2. Scanning of Docker containers and images using oscap-docker

The oscap-docker is used to scan Docker containers and images. It can assess vulnerabilities in the container or image and check their compliance with security policies. Usage of the tool mimics usage and options of oscap tool.

The oscap-docker tool uses a technique called offline scanning. That means that the filesystem of the container is mounted to a directory on the host. The mounted filesystem is read-only. OpenSCAP then assess the container from the host. Therefore no agent is installed in the container and container is not touched or changed in any way.

However, oscap-docker requires Atomic installed on the host. Atomic is advanced container management solution and it enables oscap-docker to access the containers.

In the first example, we will perform a vulnerability assessment of an Docker image of Red Hat Enterprise Linux 7 (named rhel7). The command will attach docker image, determine OS variant/version, download CVE stream applicable to the given image and finally it will evaluate the image for vulnerabilities. CVE stream is a list of vulnerabilities in SCAP format and is downloaded directly from Red Hat. HTML report is written out as report.html on the local machine.

$ oscap-docker image-cve rhel7 --report report.html

In the second example, we will check the same rhel7 image for compliance with a security policy specified in an XCCDF checklist.

$ oscap-docker image rhel7 xccdf eval --report report.html xccdf.xml

To scan running containers, commands are very similar, just replace "image-cve" with "container-cve" and "image" with "container".

5.3. Scanning of virtual machines using oscap-vm

OpenSCAP provides a simple tool to evaluate virtual machines called oscap-vm.

The tool can scan given virtual machine directly from the virtualisation host. Usage of the tool mimics usage and options of oscap tool.

Similarly to oscap-docker, this utility also uses offline scanning, so it doesn’t install anything in the guest, doesn’t require OpenSCAP installed in the guest and it doesn’t create or change anything in the guest’s filesystem.

5.4. Scanning arbitrary filesystems using oscap-chroot

A very simple script oscap-chroot can be used to perform an offline scan of a filesystem that is mounted at arbitrary path. It can be used for scanning of custom objects that are not supported by oscap-docker or oscap-vm, like containers in other formats than Docker. Again, usage of the tool mimics usage and options of oscap tool.

6. Developer’s operations

This part of documentation is meant to serve mainly to developers who want to contribute to the oscap, help to fix bugs, or take an advantage of the OpenSCAP library and create own projects on top of it.

6.1. Compiling

If you want to build the libopenscap library and the oscap tool from the source code then follow these instructions:

1) Get the lastest source code

$ git clone https://github.com/OpenSCAP/openscap.git

2) Run the follwoing script.

$ ./autogen.sh
Note
The autoconf, automake, and libtool tools are required to be installed on your system. If you use a release taball, you can skip this step.

3) Run the following commands to build the library.

$ ./configure
$ make

Build dependencies may vary in dependency on enabled features (by the configure command). By default, you need the following packages installed on your system:

  • swig

  • libxml2-devel

  • rpm-devel

  • libgcrypt-devel

  • pcre-devel

  • python-devel

  • perl-devel

  • libcurl-devel

  • libxslt-devel

  • libtool

  • perl-XML-XPath

    1. Run library self-checks by executing the following command: # make check

    2. Run the installation procedure by executing the following command: # make install

6.2. Debugging

Developers and users who intend to help find and fix possible bugs in OpenSCAP or possible bugs in their security policies have these possibilities:

6.2.1. Verbose mode

The verbose mode provides user additional information about process of system scanning. The mode is useful for diagnostics of SCAP content evaluation and also for debugging. It produces a detailed report log with various messages. The mode is available for xccdf eval, oval eval, oval collect and oval analyse modules. There is no need to special compilation, the feature is available for all OpenSCAP users.

To turn the verbose mode on, run oscap with this option:

  • --verbose VERBOSITY_LEVEL - Turn on verbose mode at specified verbosity level.

The VERBOSITY_LEVEL can be one of:

  1. DEVEL - the most detailed information for developers and bug hunters

  2. INFO - reports content processing and system scanning

  3. WARNING - possible failures which OpenSCAP can recover from

  4. ERROR - shows only serious errors

The verbose messages will be written on standard error output (stderr). Optionally, you can write the log into a file using --verbose-log-file FILE.

This is an example describing how to run OpenSCAP in verbose mode:

$ oscap oval eval --results results.xml --verbose INFO --verbose-log-file log.txt oval.xml

Then see the log using eg.:

$ less log.txt

6.2.2. Debug mode

Debug mode is useful for programmers. You need to build OpenSCAP from source code with a custom configuration to enable the debug mode. Use this command:

$ ./configure --enable-debug && make

Debug mode provides:

  • debug symbols on and optimization off - you can use gdb, every process that was run.

  • assertions are evaluated.

6.2.3. Testing library

Next important step is to preload libopenscap_testing.so before you run oscap tool. The testing library allows you to specify custom path to probes via OVAL_PROBE_DIR environment variable. The easiest way how to achieve that without need to install libopenscap, is to use shell script called run in the OpenSCAP directory.

$ ./run utils/.libs/oscap xccdf eval ... whatever

The run script is generated at configure time and it sets:

  • LD_PRELOAD and LD_LIBRARY_PATH - preload libopenscap_testing.so

  • OVAL_PROBE_DIR - path to probes

  • OSCAP_SCHEMA_PATH - path to XCCDF, OVAL, CPE, …​ schemas. (required for valudation)

  • OSCAP_XSLT_PATH- path to XSLT transformations. (required if you want to generate html documents from xml)

6.2.4. Example

$ ./run gdb --args utils/.libs/oscap xccdf eval --profile hard --results xccdf-results.xml --oval-results my-favourite-xccdf-checklist.xml

The --oval-results option force oscap tool to generate OVAL Result file for each OVAL session used for evaluation. It’s also very useful for debugging!

6.2.5. Debugging probes

It’s also possible to debug a probe itself. You need to raise timeout value for thread join in src/OVAL/probes/probe/main.c:228 and rebuild sources.

-       j_tm.tv_sec += 3;
+       j_tm.tv_sec += 3000;

Then you can run gdb with probe binary:

$ ./run gdb src/OVAL/probes/.libs/probe_rpmverifypackage

An input for the probe can be found in the log file created by previous oscap tool run in verbose mode, e.g.:

 ("seap.msg" ":id" 0 (("rpmverifypackage_object" ":id" "oval:org.mitre.oval.test:obj:1386" ":oval_version" 84541440 ) (("name" ":operation" 5 ":var_check" 1 ) "plymouth" ) (("behaviors" ":nodeps" "false" ":nodigest" "false" ":noscripts" "true" ":nosignature" "false" ) ) ) )

6.2.6. Environment variables

There are few more environment variables that control oscap tool behaviour.

  • OSCAP_FULL_VALIDATION=1 - validate all exported documents (slower)

  • SEXP_VALIDATE_DISABLE=1 - do not validate SEXP expressions (faster)

6.3. Scanning with Script Check Engine (SCE)

The Script Check Engine (SCE) is an alternative check engine for XCCDF checklist evaluation. SCE allows you to call shell scripts out of the XCCDF document. This approach might be suitable for various use cases, mostly when OVAL checks are not required. More information about SCE usage is available on this page: Using SCE.

Warning
SCE is not part of any SCAP specification.

6.4. Building OpenSCAP on Windows

The OpenSCAP library is developed mainly on Linux platform but it can be built also on Windows platforms. Follow these instructions to build OpenSCAP on Windows using Cygwin:

  1. The easiest way to compile OpenSCAP on Windows is in cygwin. First install basic set of packages from cygwin distribution plus:

    • autoconf automake libtool make gcc

    • pcre-devel libxml2-devel libcurl-devel libgrcypt-devel

    • swig perl python

  2. Checkout the master branch of OpenSCAP:

    $ git clone -b master https://github.com/OpenSCAP/openscap.git
  3. Run autotools machinery by

    $ ./autogen.sh
  4. Unfortunately the probes support is platform dependent and windows code was not implemented yet so it’s necessary to disable compilation of probes by

    $ configure --disable-probes
  5. Build the library

    $ make build
  6. You might want to run the library self-check by

    $ make check
  7. Install the library

    $ make install
  8. The final DLL is called cygopenscap-0.dll and you can link you app to it.

Example: gcc myapp.c -I/path/to/headers -L/path/to/dynamic/library -lcygopenscap-0

If you want to run your app, make sure cygopenscap-0.dll is either in working directory or in PATH variable directories.

6.5. Generating of code coverage

Code coverage can be usefull during writing of test or performance profiling. We could separate the process into five phases.

1) Get dependencies

# dnf install lcov

2) Run configure & make

To allow code to generate statistics, we need to compile it with specific flags.

$ ./configure CFLAGS="--coverage" LDFLAGS=-lgcov --enable-debug
$ make

3) Run code.

In this phase we should run code. We can run it directly or via test suite.

$ ./run ./utils/.libs/oscap

4) Generate and browse results

$ lcov -t "OpenSCAP coverage" -o ./coverage.info -c -d .
$ genhtml -o ./coverage ./coverage.info
$ xdg-open ./coverage/index.html # open results in browser

5) Clean stats

Every run only modify our current statistics and not rewrite them completely. If we want to generate new statistics, we should remove the old ones.

$ lcov --directory ./ --zerocounters ; find ./ -name "*.gcno" | xargs rm
$ rm -rf ./coverage

6.6. Building OpenSCAP for Windows (cross-compilation)

Building OpenSCAP for Windows without a POSIX emulation layer is currently not possible. However, we are close to a native port of OpenSCAP for Windows. If you want to help us solve the remaining problems. Instructions for cross-compiling OpenSCAP for Windows:

1) Install the cross-compiler & dependencies

 # yum install mingw32-gcc mingw32-binutils mingw32-libxml2 \
 mingw32-libgcrypt mingw32-pthreads mingw32-libxslt \
 mingw32-curl mingw32-pcre \
 automake autoconf libtool

2) Checkout the portable branch of the OpenSCAP repository

 $ git clone -b master https://github.com/OpenSCAP/openscap.git \
 openscap-portable.git
 $ cd openscap-portable.git/

3) Prepare the build

 $ ./autogen.sh
 $ mingw32-configure --disable-probes --disable-python

4) Build!

 $ make -k 2> build-errors.log

5) Inspect build-errors.log for problems

 $ grep -E '(error:|implicit)' build-errors.log
oscap_acquire.c:32:17: fatal error: ftw.h: No such file or directory
rbt_i32.c:36:9: warning: implicit declaration of function 'posix_memalign'
rbt_i64.c:35:9: warning: implicit declaration of function 'posix_memalign'
rbt_str.c:39:9: warning: implicit declaration of function 'posix_memalign'
tailoring.c:200:2: warning: implicit declaration of function 'strverscmp'
oscap-tool.c:37:17: fatal error: ftw.h: No such file or directory
oscap-oval.c:37:17: fatal error: ftw.h: No such file or directory
oscap-info.c:37:26: fatal error: linux/limits.h: No such file or directory

We need to solve the following problems:

  1. No implementation of strverscmp for Windows

  2. No implementation of ftw API for Windows

  3. Replace posix_memalign with a Windows API equivalent

  4. Get rid of linux/limits.h dependency on Windows

If you would like to send us a patch solving one of these problems, please consult the page about contributing to the OpenSCAP project.

6.7. OpenSCAP Reference Manual

For more information about OpenSCAP library, you can refer to this online reference manual: OpenSCAP reference manual. This manual is included in a release tarball and can be regenerated from project sources by Doxygen documentation system.