OpenSCAP User Manual

To perform any task with OpenSCAP you also need to have security policies in SCAP format. We call them SCAP content. There are many providers of SCAP content.

In this document we will use SCAP content provided by SCAP Security Guide (SSG). Many Linux distributions ship it in the scap-security-guide package.

To install scap-security-guide on Red Hat Enterprise Linux 8 and newer, on CentOS 8 and newer or on Fedora use the following command:

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

On other platforms, you can download the upstream release from GitHub.

When the SCAP content is installed on your system, oscap can process the content by specifying the file path to the content.

You can also use any other SCAP content with OpenSCAP.

The most common SCAP file type is an SCAP source data stream. In the following example, we will display information about SCAP source data stream /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml from the scap-security-guide package.

To display more detailed information about a profile including the profile description, use the --profile option followed by the profile ID.

The oscap info command is also helpful with other SCAP file types such as SCAP result data stream (ARF) files.

OpenSCAP can display the evaluation start and end dates when given ARF file.

In this example, we will display information about the ARF file arf.xml.

Commonly, all required input files are bundled together in an SCAP source data stream. Scanning using an SCAP source data stream can be performed by the oscap xccdf eval command, with some additional parameters available. The basic syntax of the oscap xccdf eval command is the following:

Where:

For example, to evaluate the xccdf_org.ssgproject.content_profile_ospp profile from the /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml SCAP source data stream run this command:

The progress and results will be shown in the terminal. Full results are generated in results.xml as an SCAP result data stream. Detailed results can be found in the HTML report report.html.

To evaluate a specific XCCDF benchmark that is part of a specific SCAP source data stream, use the following command:

Where:

To evaluate a specific XCCDF benchmark that is part of an SCAP source data stream use the following options:

Where:

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 OVAL definitions within the given OVAL Definition file the oscap oval eval command can be used. Its basic form is the following:

Where:

It’s possible to select and evaluate one particular definition within the given OVAL Definition file using --id option:

Where the OVAL definition being evaluated has ID oval:rhel:def:1000, 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 component within a SCAP source data stream, run the following command:

Where ds.xml is the ID of a specific 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 the SCAP source 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:

Where united_states_government_configuration_baseline represents a profile in the XCCDF document, xccdf.xml is a file specifying the XCCDF document, oval.xml is the OVAL Definition file, oval_variables.xml is the file containing exported variables from the XCCDF file, and oval_results.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:

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:

Usage of OVAL directives file when scanning OVAL component from a source data stream:

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:

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 data stream files as well. Source data stream will often reference OVAL files that are bundled in it.

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:

The meaning of results is defined by XCCDF Specification. This table lists the possible results of a single rule:

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:

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.

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

The --rule option can be used multiple times to evaluate multiple rules at once.

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

DISA STIG Viewer is a graphical user interface (GUI) application that enables easy viewing of SCAP-formatted Security Technical Implementation Guides (STIGs). For more information on DISA STIG Viewer see the SRG / STIG Tools website.

OpenSCAP can generate results compatible with STIG Viewer even when evaluating SCAP content that uses different rule IDs than the official DISA STIG format, for example, content from the scap-security-guide package or third-party content.

To produce results compatible with STIG Viewer, each rule in an SCAP source data stream must contain a reference to a STIG Rule ID, and the value of the href attribute must be either http://iase.disa.mil/stigs/Pages/stig-viewing-guidance.aspx or https://public.cyber.mil/stigs/srg-stig-tools/.

For example:

In the following example, we use the /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml file provided by the scap-security-guide RPM package. This data stream file meets both prerequisites for rules.

1) Scan your system using the oscap command with the --stig-viewer option.

2) Download a STIG file of your choice, for example, from the STIGs Document Library, and extract it. The version of the STIG must conform to the version of the xccdf_org.ssgproject.content_profile_stig profile.

3) In STIG Viewer, click on File and then on Import STIG. Then, select the STIG in STIGs panel on the left side. Click on Checklists and then on Create Checklists - Check Marked STIG(s).

4) Import the OpenSCAP scan results by clicking on Import and then on XCCDF Results File. Locate the results-stig.xml file obtained in step 1. STIG Viewer shows the results subsequently.

A common theme is to check system status based on requirements of a particular policy. OpenSCAP can select rules that are related to a specific requirement based on the references in the rules.

1) List references that are supported in your scap content using the oscap info --references command. This will list of available reference names and their URIs. For example:

2) Run the evaluation with the --reference option, using the name obtained in the previous step and the requirement ID, separated by a colon. That will filter the list of rules so that only rules that have the given reference ID assigned would be evaluated. For example:

The remediation scripts can be executed at the time of scanning. Evaluation and remediation are performed as a part of a single command.

To enable remediation during scanning, use the oscap xccdf eval command with the --remediate command-line option.

In this example we will execute remediation during evaluation of the OSPP profile:

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.

This feature allows you to postpone fix execution.

In first step, the system is only evaluated, and the results are stored in the <xccdf:TestResult> element in an XCCDF results 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 <xccdf:TestResult> element is created that is based on the input one and inherits all the data. The newly created <xccdf:TestResult> differs only in the <xccdf:rule-result> elements that have failed. For those, remediation is executed.

For example:

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:

Tailoring files can be easily created using SCAP Workbench which is a GUI application.

On the command line, tailoring files can be created using the autotailor tool. This tool is a part of the openscap-utils package.

The basic syntax is:

Where:

The script creates a new file with a new profile with ID in a form BASE_PROFILE_ID_customized.

In the following example, we will create a customized profile with ID custom based on the OSPP profile from the SCAP Security Guide for Red Hat Enterprise Linux 8 (located in /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml which is provided by the scap-security-guide RPM package) which will remove the rule service_usbguard_enabled and save it as a XCCDF Tailoring file into /tmp/tailoring.xml.

The autotailor tool can also consume JSON tailoring files and convert them into XCCDF Tailoring.

For more details about other options of the autotailor program please read the autotailor(8) man page or run autotailor --help.

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.

When evaluating a digitally signed SCAP source data stream OpenSCAP validates the digital signature of the data stream. The signature validation is performed automatically while loading the file. Data streams with invalid signatures would be rejected and would not be evaluated. OpenSCAP uses XML Security Library with OpenSSL backend to validate the digital signature.

The signature validation only checks that the datastream hasn’t been altered since its latest signature. OpenSCAP doesn’t address trustworthiness of certificates or public keys that are part of the KeyInfo signature element and that are used to verify the signature. You should verify those keys yourself to prevent evaluation of datastreams that have been modified and signed by bad actors.

The signature validation can be skipped by adding the --skip-signature-validation option to the oscap xccdf eval command.

Also, signature validation can be enforced (effectively rendering all unsigned data streams invalid) with the --enforce-signature option to the oscap xccdf eval command.

To generate a HTML guide from an SCAP source data stream or an XCCDF file use the oscap xccdf generate guide command.

Generating a guide with profile checklist (see an example):

To generate HTML scan reports after scan from the scan results in ARF or XCCDF format the oscap xccdf generate report command can be used.

Generating the HTML report with information about checks (see an example):

To generate a bash remediation script from an XCCDF profile, use the oscap xccdf generate fix command. OpenSCAP will extract remediation scripts for all rules in the given profile to a file.

For example, to generate a bash remediation script for RHEL 8 OSPP profile, run:

The output contains fixes for all rules in the given profile including those rules that would pass. It’s because system isn’t scanned during this command. If you want to generate remediation only for the failed rules based on scan results, refer to Reviewing remediations.

Similar to generating bash scripts, OpenSCAP is able to extract Ansible tasks associated with XCCDF rules and generate an Ansible Playbook that can be used to configure the operating system according to the given profile. To generate Anisble Playbook use the oscap xccdf generate fix command with --fix-type ansible option.

For example, to generate Ansible Playbook from RHEL 8 OSPP profile, run:

The generated Ansible Playbook is generated from an OpenSCAP profile without preliminary evaluation. It attempts to fix every selected rule, even if the system is already compliant. The output contains fixes for all rules in the given profile including those rules that would pass. It’s because system isn’t scanned during this command. If you want to generate remediation only for the failed rules based on scan results, refer to Reviewing remediations.

OpenSCAP can also create a remediation in form of Image Builder (OSBuild) Blueprint. This remeditaion is intendeded to be used as a bootstrap for image creation and usually it will contain only essential elements of the configuration, elements that would be hard or impossible to change after the image is created, like partitioning or set of installed packages.

It is recommended to combine this type of remediation with other types, executed on the running system.

For example, to generate a blueprint remediation for RHEL 8 OSPP profile, run:

OpenSCAP can generate RHEL kickstarts which can be used for unattended installation of RHEL, Fedora and similar systems. Information about RHEL kickstarts and their syntax can be found at Kickstart references and Kickstart Documentation.

To generate a kickstart, use oscap xccdf generate fix command with the --fix-type kickstart option.

The kickstart will be generated from kickstart snippets in XCCDF rules in the input SCAP content. The kickstart snippets need to be present in <fix> elements with system attribute set to urn:xccdf:fix:script:kickstart.

When processing the kickstart snippets from the XCCDF Rules, each line is processed separately. If a line starts with a supported block keyword, that line and all following lines until a line starting with %end are considered a block. Blocks are propagated to the output without any processing. If a line isn’t part of a block, the following rules are applied:

Supported block keywords:

Supported commands:

For example, to generate a kickstart for RHEL 9 STIG profile, run:

The generated kickstart file needs to be reviewed and customized for the intended deployment. The kickstart sets some default values to makte automated installation possible. These default values are usually good enough but sometimes need to be changed manually. Pay special attention to the items marked as required for security compliance.

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:

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 outputs identifiers of scanned rules regardless of their results. For example:

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 SCAP result data stream (ARF) files. This file can be generated during the scan by adding --results-arf option.

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

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.

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.

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

OpenSCAP identifies SWID tags using OVAL inventory class definitions that are part of an SCAP source data stream or a standalone OVAL Definition file.

It supports the following 3 methods of SWID tags detection:

The oscap command handles the SWID tag detection transparently. The detection algorithm is using OVAL’s xmlfilecontent test. The OVAL inventory class definitions can be evaluated in a standard way, i.e. by using the oscap oval eval for a standalone OVAL Definition file or oscap xccdf eval for definitions that are part of an SCAP source data stream.

For example, the following command can be used to evaluate an SCAP source data stream that contains OVAL inventory class definitions that search for the presence of a matching SWID tag (referenced XML files can be obtained from the SCAP 1.3 validation test suite).

As another example, the following command can be used to evaluate a standalone OVAL Definition file that contains OVAL inventory class definitions that search for the presence of a matching SWID tag:

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

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 one of the profiles and run the evaluation command. For example, the following command is used to assess the given system using the "CIS Red Hat Enterprise Linux 9 Benchmark for Level 2 - Server" profile.

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

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

2) Verify that the PCI-DSS profile is present

3) Evaluate the PCI-DSS profile

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

If you are interested in DISA STIG content for other systems please refer to DoD Cyber Exchange.

The oscap-ssh command 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 data streams 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-podman tool can be used to scan Linux containers and container images. Usage of the tool mimics usage and options of oscap tool.

Note that the oscap-podman command requires root privileges.

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.

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.