OpenSCAP User Manual

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:

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:

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:

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:

and when XCCDF document is examined:

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.

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.

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:

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

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:

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:

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

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:

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:

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

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

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:

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

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

Successful output should look similar to this:

And the exit code must be 0 before proceeding.

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

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:

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.

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:

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:

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:

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.

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:

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).

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:

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.

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.

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:

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:

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:

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

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

1) Install the SSG

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

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:

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.

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

2) Verify that the PCI-DSS profile is present

3) Evaluate the PCI-DSS content

4) Generate report readable in a web browser.

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.

2) Unpack the content.

3) Fix the content using a sed substitution.

4) Display a list of available profiles.

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

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

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.

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

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

1) Download the USGCB content.

2) Unpack the USGCB content.

3) Run evaluation of the USGCB content.

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

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.

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.

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.

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.

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

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

1) Install the SSG

2a) Evaluate common profile for RHEL 6

2b) Evaluate common profile for RHEL 7

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.

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

3) Evaluate

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.

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

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.

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.

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

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.

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.

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

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

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.

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.

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

2) Run the follwoing script.

3) Run the following commands to build the library.

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

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

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.

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:

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

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

1) Get dependencies

2) Run configure & make

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

3) Run code.

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

4) Generate and browse results

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.

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

2) Checkout the portable branch of the OpenSCAP repository

3) Prepare the build

4) Build!

5) Inspect build-errors.log for problems

We need to solve the following problems:

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

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.