7.4. Using oscap

The oscap command-line utility enables users to scan local systems, validate security compliance content, and generate reports and guides based on these scans and evaluations. This utility serves as a front end to the OpenSCAP library and groups its functionalities to modules (sub-commands) based on the type of SCAP content it processes.
The following sections explain how to install oscap and perform the most common operations. Examples are provided to illustrate these tasks. To learn more about specific sub-commands, use the --help option with an oscap command: 
oscap [options] module module_operation [module_operation_options_and_arguments] --help
where module represents the type of SCAP content that is being processed, and module_operation is a sub-command for the specific operation on the SCAP content.

Example 7.4. Getting Help on a Specific oscap Operation

~]$ oscap ds sds-split --help
oscap -> ds -> sds-split

Split given SourceDataStream into separate files

Usage: oscap [options] ds sds-split [options] SDS TARGET_DIRECTORY

SDS - Source data stream that will be split into multiple files.
TARGET_DIRECTORY - Directory of the resulting files.

Options:
   --datastream-id <id>          - ID of the datastream in the collection to use.
   --xccdf-id <id>               - ID of XCCDF in the datastream that should be evaluated.
To learn about all oscap features and the complete list of its options, see the oscap(8) manual page.

7.4.1. Installing oscap

To install oscap to your system, enter the following command as root: 
~]# yum install openscap-scanner
This command enables you to install all packages required by oscap to function properly, including the openscap package. To be able to write your own security content, you should also install the openscap-engine-sce package, which provides the Script Check Engine (SCE). The SCE is an extension of the SCAP protocol that allows content authors to write their security content using a scripting language, such as Bash, Python, or Ruby. Note that the openscap-engine-sce package is only available from the Optional channel. See Enabling Supplementary and Optional Repositories.
Optionally, after installing oscap, you can check the capabilities of your version of oscap, what specifications it supports, where the certain oscap files are stored, what kinds of SCAP objects you can use, and other useful information. To display this information, type the following command: 
~]$ oscap -V
OpenSCAP command line tool (oscap) 1.0.4
Copyright 2009--2014 Red Hat Inc., Durham, North Carolina.

==== Supported specifications ====
XCCDF Version: 1.2
OVAL Version: 5.10.1
CPE Version: 2.3
CVSS Version: 2.0
CVE Version: 2.0
Asset Identification Version: 1.1
Asset Reporting Format Version: 1.1

==== Capabilities added by auto-loaded plugins ====
SCE Version: 1.0 (from libopenscap_sce.so.8)

==== Paths ====
Schema files: /usr/share/openscap/schemas
Schematron files: /usr/share/openscap/xsl
Default CPE files: /usr/share/openscap/cpe
Probes: /usr/libexec/openscap

==== Inbuilt CPE names ====
Red Hat Enterprise Linux - cpe:/o:redhat:enterprise_linux
Red Hat Enterprise Linux 5 - cpe:/o:redhat:enterprise_linux:5
Red Hat Enterprise Linux 6 - cpe:/o:redhat:enterprise_linux:6
Red Hat Enterprise Linux 7 - cpe:/o:redhat:enterprise_linux:7
Fedora 16 - cpe:/o:fedoraproject:fedora:16
Fedora 17 - cpe:/o:fedoraproject:fedora:17
Fedora 18 - cpe:/o:fedoraproject:fedora:18
Fedora 19 - cpe:/o:fedoraproject:fedora:19
Fedora 20 - cpe:/o:fedoraproject:fedora:20
Fedora 21 - cpe:/o:fedoraproject:fedora:21
Red Hat Enterprise Linux Optional Productivity Applications - cpe:/a:redhat:rhel_productivity
Red Hat Enterprise Linux Optional Productivity Applications 5 - cpe:/a:redhat:rhel_productivity:5

==== Supported OVAL objects and associated OpenSCAP probes ====
system_info                  probe_system_info           
family                       probe_family                
filehash                     probe_filehash              
environmentvariable          probe_environmentvariable   
textfilecontent54            probe_textfilecontent54     
textfilecontent              probe_textfilecontent       
variable                     probe_variable              
xmlfilecontent               probe_xmlfilecontent        
environmentvariable58        probe_environmentvariable58 
filehash58                   probe_filehash58            
inetlisteningservers         probe_inetlisteningservers  
rpminfo                      probe_rpminfo               
partition                    probe_partition             
iflisteners                  probe_iflisteners           
rpmverify                    probe_rpmverify             
rpmverifyfile                probe_rpmverifyfile         
rpmverifypackage             probe_rpmverifypackage      
selinuxboolean               probe_selinuxboolean        
selinuxsecuritycontext       probe_selinuxsecuritycontext
file                         probe_file                  
interface                    probe_interface             
password                     probe_password              
process                      probe_process               
runlevel                     probe_runlevel              
shadow                       probe_shadow                
uname                        probe_uname                 
xinetd                       probe_xinetd                
sysctl                       probe_sysctl                
process58                    probe_process58             
fileextendedattribute        probe_fileextendedattribute 
routingtable                 probe_routingtable
Before you can start using oscap effectively, you also need to install or import some security content on your system. For example, you can install the SCAP Security Guide (SSG) package, scap-security-guide, which contains the currently most evolved and elaborate set of security polices for Linux systems. To install the SCAP Security Guide package on your system, enter the following command as root: 
~]# yum install scap-security-guide
After you install scap-security-guide on your system, unless specified otherwise, the SSG security content is available under the /usr/share/xml/scap/ssg/content/ directory, and you can proceed with other security compliance operations.
To find other possible sources of existing SCAP content that might suit your needs, see Section 7.10, “Additional Resources”.
After installing the SCAP content on your system, oscap can process the content when supplied with the file path to the content. The oscap utility supports SCAP version 1.2 and is backward-compatible with SCAP versions 1.1 and 1.0, so it can process earlier versions of SCAP content without any special requirements.

7.4.2. Displaying SCAP Content

SCAP standard defines numerous file formats. The oscap utility can process or create files conforming to many of the formats. In order to further process the given file with SCAP content, you need to understand how to use oscap with the given file type. If you are unsure how to use a particular file, you can either open and read the file, or you can use the info module of oscap which parses the file and extracts relevant information in human-readable format.
enter the following command to examine the internal structure of a SCAP document and display useful information such as the document type, specification version, a status of the document, the date the document was published, and the date the document was copied to a file system: 
oscap info file
where file is the full path to the security content file being examined. The following example better illustrates the usage of the oscap info command:

Example 7.5. Displaying Information About SCAP Content

~]$ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
Document type: Source Data Stream
Imported: 2014-03-14T12:22:01

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
                Profiles:
                        xccdf_org.ssgproject.content_profile_test
                        xccdf_org.ssgproject.content_profile_rht-ccp
                        xccdf_org.ssgproject.content_profile_common
                        xccdf_org.ssgproject.content_profile_stig-rhel7-server-upstream
                Referenced check files:
                        ssg-rhel7-oval.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_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

7.4.3. Scanning the System

The most important functionality of oscap is to perform configuration and vulnerability scans of a local system. The following is a general syntax of the respective command: 
oscap [options] module eval [module_operation_options_and_arguments]
The oscap utility can scan systems against the SCAP content represented by both an XCCDF (The eXtensible Configuration Checklist Description Format) benchmark and OVAL (Open Vulnerability and Assessment Language) definitions. The security policy can be in the form of a single OVAL or XCCDF file or multiple separate XML files where each file represents a different component (XCCDF, OVAL, CPE, CVE, and others). The result of a scan can be printed to both standard output and an XML file. The result file can then be further processed by oscap in order to generate a report in a human-readable format. The following examples illustrate the most common usage of the command.

Example 7.6. Scanning the System Using the SSG OVAL definitions

To scan your system against the SSG OVAL definition file while evaluating all definitions, enter the following command: 
~]$ oscap oval eval --results scan-oval-results.xml /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
The results of the scan are stored as the scan-oval-results.xml file in the current directory.

Example 7.7. Scanning the System Using the SSG OVAL definitions

To evaluate a particular OVAL definition from the security policy represented by the SSG data stream file, enter the following command: 
~]$ oscap oval eval --id oval:ssg:def:100 --results scan-oval-results.xml /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
The results of the scan are stored as the scan-oval-results.xml file in the current directory.

Example 7.8. Scanning the System Using the SSG XCCDF benchmark

To perform the SSG XCCDF benchmark for the xccdf_org.ssgproject.content_profile_rht-ccp profile on your system, enter the following command: 
~]$ 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
The results of the scan are stored as the scan-xccdf-results.xml file in the current directory.

Note

The --profile command-line argument selects the security profile from the given XCCDF or data stream file. The list of available profiles can be obtained by running the oscap info command. If the --profile command-line argument is omitted the default XCCDF profile is used as required by SCAP standard. Note that the default XCCDF profile may or may not be an appropriate security policy.

7.4.4. Generating Reports and Guides

Another useful features of oscap is the ability to generate SCAP content in a human-readable format. The oscap utility allows you to transform an XML file into the 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.
The following are the most common examples of the command usage:

Example 7.9. Generating a Guide with a Checklist

To produce an SSG guide with a checklist for the xccdf_org.ssgproject.content_profile_rht-ccp profile, enter the following command: 
~]$ oscap xccdf generate guide --profile xccdf_org.ssgproject.content_profile_rht-ccp /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml > ssg-guide-checklist.html
The guide is stored as the ssg-guide-checklist.html file in the current directory.

Example 7.10. Transforming an SSG OVAL Scan Result into a Report

To transform a result of an SSG OVAL scan into an HTML file, enter the following command: 
~]$ oscap oval generate report scan-oval-results.xml > ssg-scan-oval-report.html
The result report is stored as the ssg-scan-oval-report.html file in the current directory. This example assumes that you run the command from the same location where the scan-oval-results.xml file is stored. Otherwise you need to specify the fully-qualified path of the file that contains the scan results.

Example 7.11. Transforming an SSG XCCDF Scan Result into a Report

To transform a result of an SSG XCCDF scan into an HTML file, enter the following command: 
~]$ oscap xccdf generate report scan-xccdf-results.xml > scan-xccdf-report.html
The result report is stored as the ssg-scan-xccdf-report.html file in the current directory. Alternatively, you can generate this report in the time of the scan using the --report command-line argument: 
~]$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_rht-ccp --results scan-xccdf-results.xml --report scan-xccdf-report.html /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

7.4.5. 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 utility 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: 
oscap module validate [module_options_and_arguments] file
where file is the full path to the file being validated. The only exception is the data stream module (ds), which uses the sds-validate operation instead of validate. Note that all SCAP components within the given data stream are validated automatically and none of the components is specified separately, as can be seen in the following example: 
~]$ oscap ds sds-validate /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
With certain SCAP content, such as OVAL specification, you can also perform a Schematron validation. The Schematron validation is slower than the standard validation but provides deeper analysis, and is thus able to detect more errors. The following SSG example shows typical usage of the command: 
~]$ oscap oval validate --schematron /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml

7.4.6. Using OpenSCAP to Remediate the 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 constains certain remediation instructions.
System remediation consists of the following steps:
  1. OpenSCAP 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. OpenSCAP 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 OpenSCAP and stored within the rule-result element. The return value of the fix script is stored as well.
  5. Whenever OpenSCAP executes a fix script, it immediatelly 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 OpenSCAP with regard to remediation: online, offline, and review.

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

7.4.6.2. OpenSCAP Offline Remediation

Offline remediation allows you to postpone fix execution. In the 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, OpenSCAP creates a new TestResult element 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

7.4.6.3. OpenSCAP Remediation Review

The review mode enables 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

7.4.7. Exporting XCCDF Results for the DISA STIG Viewer

The DISA STIG Viewer enables users to view results from the perspective of DISA rule IDs. This utility expects the DISA (Defense Information Systems Agency) STIG (Security Technical Implementation Guide) identifiers, for example, SV-86551r1_rule, to be used as rule IDs. In most of the publicly-available SCAP content, the convention is to have the DISA STIG IDs attached to XCCDF rules as references or identifiers. Therefore, XCCDF results produced by OpenSCAP and SCAP Security Guide are not readable when opened in DISA STIG Viewer.
OpenSCAP enables you to output your XCCDF results to a format that is compatible with DISA STIG Viewer. The transformation takes the attached STIG rule ID reference and replaces the XCCDF rule ID with it.

Example 7.12. Scanning a System for DISA STIG Compliance and Producing Results for STIG Viewer

To scan a local system for DISA STIG compliance and produce XCCDF results that can be opened in DISA STIG Viewer: 
$ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_stig-rhel7-disa --stig-viewer stig-results.xml /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml
To view the XCCDF Results in DISA STIG Viewer, import the STIG of your choice first, and create a checklist. With the checklist created, use the Import → XCCDF Result File menu item to fit your results.

Note

Note that you can use any of the other oscap options with the --stig-viewer option to export results with the usual rule IDs.
For more information about STIG Viewing, see the IASE STIG Viewing Guidance web page.