Open
banners

From Openscap

Contents

Introduction

The oscap program is a command line tool that allows users to load, scan, validate, edit, and export SCAP documents. The following sections provide information about using oscap for both, normal users and developers. The user part covers explanation of the most common oscap operations and shows the relevant examples. The developer part provides information on tasks related to OpenSCAP development.

Common User Operations

This part of documentation explains usage of the most common oscap operations and presents examples based on industry standard data (SCAP content). For more information about oscap capabilities and a complete list of options, refer to the oscap manual pages:

$ man oscap

Installation

You can either build the OpenSCAP library and the oscap tool from source code (for details refer to Compilation), 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-utils

Common Usage

Prior using the oscap tool, you have to install SCAP content on your system. You can download the SCAP content from the respective web site or you can install it using a package management system implemented in by your Linux distribution.

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 tool supports SCAP 1.2 and is backward compatible with SCAP 1.1 and 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

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 of the command:

$ oscap info usgcb-rhel5desktop-ds.xml

The following is a sample output of the command above:

Document type: Source Data Stream
Imported: 2013-06-11T13:50:06

Stream: scap_org.open-scap_datastream_from_xccdf_usgcb-rhel5desktop-xccdf.xml
Generated: 2011-09-30
Version: 1.2
Checklists:
    Ref-Id: scap_org.open-scap_cref_usgcb-rhel5desktop-xccdf.xml
        Profiles:
            xccdf_gov.nist.usgcb_profile_united_states_government_configuration_baseline
        Referenced check files:
            usgcb-rhel5desktop-oval.xml
                system: http://oval.mitre.org/XMLSchema/oval-definitions-5
            http://www.redhat.com/security/data/oval/com.redhat.rhsa-all.xml
                system: http://oval.mitre.org/XMLSchema/oval-definitions-5
Checks:
    Ref-Id: scap_org.open-scap_cref_usgcb-rhel5desktop-oval.xml
    Ref-Id: scap_org.open-scap_cref_usgcb-rhel5desktop-cpe-oval.xml
Dictionaries:
    Ref-Id: scap_org.open-scap_cref_usgcb-rhel5desktop-cpe-dictionary.xml

Scanning

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

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

XCCDF

When evaluating an XCCDF benchmark, oscap usually processes an XCCDF file, an OVAL file and the CPE dictionary. The tool 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.
  • To evaluate a specific XCCDF benchmark that is part of a data stream within a SCAP data stream 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 data stream collection, ds.xml is the particular data stream, 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 data stream 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 data stream within a SCAP data stream 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 data stream 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.
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

...

Please note that 'notchecked' 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.

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

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.

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)
Built-in CPE Naming Dictionary

Apart from the external CPE Dictionaries, OpenSCAP 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.


CVE, CCE 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 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.

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.

SCAP Content Validating

SCAP data format is very complex so some syntax or semantic errors can occur in the SCAP content. Therefore we recommend verifying the content before use. The oscap tool can be used to validate that content conforms to SCAP standard XML schemas. The following example shows how to validate a given source data stream; all components within the data stream are validated (XCCDF, OVAL, OCIL, CPE, and possibly other components):

$ oscap ds sds-validate scap-ds.xml

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

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.

SCAP Content Signing and Signature Verification

openscap 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

(If you want to experiment with various crypto engines of xmlsec1, see $ xmlsec1-config --help.)

Content Transformation

The oscap tool is also capable of using the XSLT (Extensible Stylesheet Language Transformations) language, which allows transforming SCAP content XML file into another XML, HTML, plain text or XLS 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

Real-Life examples

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

How to Evaluate Defense Information Systems Agency (DISA) Security Technical Implementation Guide (STIG) on Red Hat Enterprise Linux 5

Proper evaluation of the DISA STIG document on Red Hat Enterprise Linux 5 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 DISA STIG content.
    # wget http://iase.disa.mil/stigs/os/unix/u_redhat_5_v1r2_stig_benchmark_20130125.zip
    
  2. Unpack the DISA STIG content.
    # unzip u_redhat_5_v1r2_stig_benchmark_20130125.zip
    
  3. Fix the content using a sed substitution.
    # sed -i 's/<Group\ \(.*\)/<Group\ selected="false"\ \1/g' U_RedHat_5_V1R2_STIG_Benchmark-xccdf.xml
    
  4. 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_5_V1R2_STIG_Benchmark-cpe-dictionary.xml U_RedHat_5_V1R2_STIG_Benchmark-xccdf.xml
    
  5. Generate a scan report that is readable in a web browser.
    # oscap xccdf generate report --output report.html results.xml
    

How to Evaluate United States Government Configuration Baseline (USGCB) on Red Hat Enterprise Linux 5

The USGCB content for represents Tier IV Checklist for Red Hat Enterprise Linux 5 (as defined by NIST Special Publication 800-70). 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.0.5.0.zip
    
  2. Unpack the USGCB content.
    # unzip USGCB-rhel5desktop-1.0.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 on 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
    

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 3)
    # wget http://iase.disa.mil/stigs/os/unix/u_redhat_5_v1r3_stig_benchmark_20130426.zip
    # unzip u_redhat_5_v1r3_stig_benchmark_20130426.zip
    # oscap xccdf eval --profile MAC-2_Public --cpe U_RedHat_5-V1R3_STIG_Benchmark-cpe-dictionary.xml --result result.xml --oval-results U_RedHat_5-V1R3_STIG_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.

How to evaluate guidances for Red Hat Enterprise Linux 6

Guidances for Red Hat Enterprise Linux 6 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. The Pre-release Draft STIG for RHEL 6 Server can be evaluated using folowing command:

# wget -O /etc/yum.repos.d/epel-6-scap-security-guide.repo \
        http://repos.fedorapeople.org/repos/scap-security-guide/epel-6-scap-security-guide.repo
# yum install scap-security-guide
# oscap xccdf eval --profile stig-rhel6-server \
        --results /tmp/`hostname`-ssg-results.xml \
        --report /tmp/`hostname`-ssg-results.html \
        /usr/share/xml/scap/ssg/content/ssg-rhel6-xccdf.xml

How to run vulnerability scan on Red Hat Enterprise Linux

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, and 6. This enable users to perform a vulnerability scan and diagnose whether system is vulnerable or not.

  1. Download the content
    # wget http://www.redhat.com/security/data/metrics/com.redhat.rhsa-all.xccdf.xml 
    # wget http://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 a sample output. It reports that Red Hat Security Advisory(RHSA-2013:0911) was issues 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 by side with "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. CVE identifiers are linked with National Vulnerability Databases where additional information like: CVE description, CVSS score, CVSS vector, etc. are stored.


Notes on the Concept of Multiple OVAL Values

This section describes advanced concepts of OVAL variables and their implementation in OpenSCAP. 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 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 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).

OpenSCAP supports both variable modes as described below.

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

Evaluation of Multiple OVAL Values

With OpenSCAP, 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 OpenSCAP command-line tool (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

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.

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>

Developer operations

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

Compiling

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

  1. Run the following script to get the latest source code from a git repository.
    # ./autogen.sh
    

    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.

  2. Run the following commands to build the library.
    # ./configure
    # make
    

    Build dependencies may vary in dependency on enabled f 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; 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:

    eatures (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
    • libtools
  3. Run library self-checks by executing the following command:
    # make check
    

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

If you want to create a package for Fedora or Red Hat Enterprise Linux distribution, you will need the respective spec files. These spec files are available under the following directories:

  • dist/fedora
  • dist/rhel5
  • dist/rhel6

Debugging

Developers and users who intend to help find and fix possible bugs in OpenSCAP should refer to these instruction on how to enable debugging in OpenSCAP: Debugging instructions.

Scanning with Script Check Engine

The Script Check Engine (SCE) is an alternative check engine for XCCDF checklist evaluation. SCE is not part of any SCAP specification. 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.

Building OpenSCAP on Windows

The OpenSCAP library is developed mainly on Linux platform but it can be built also on Windows platforms. Refer to this page for instructions on how to build OpenSCAP on Windows using Cygwin: Building OpenSCAP on Windows.

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, please take a look at the instructions for cross-compiling OpenSCAP for Windows.

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.


FAQ

  1. Is it possible to convert the USGCB content into a SCAP data stream?
    Yes, it is. See this blog for detailed information: Converting USGCB to a SCAP data stream.
  2. How can I split a SCAP data stream into individual files?
    Refer to this document for an answer: Introduction to SCAP data streams.
  3. Is it possible to scan an image of a virtual machine?
    Yes it is. Refer to this document for details: Offline mode scanning.
  4. Is it possible to automatically change a machine state and make the system compliant with a desired security policy?
    Yes, it is. Refer to this page for details on SCAP remediation: OpenSCAP remediation.
  5. Is it possible to remediate a system during installation, before the first boot?
    Yes, there is a working solution for the Anaconda installer on Fedora and Red Hat Enterprise Linux systems. Refer to: Anaconda add-on for oscap.
  6. Is there an light-weight alternative for OVAL checks?
    Yes, there is the Script Check Engine. For more information refer to: SCE for XCCDF.
  7. I've tried to evaluate an XCCDF content but nothing happened - no results or errors whatsoever.
    Most likely, you didn't specify a profile to evaluate. Get a list of available profiles using oscap info, then pick one and supply it to the scanner using the --profile option..
  8. Is it possible to scan an RPM database at a non-default location?
    Yes, it is. Refer to this document for details: Evaluating your OVAL definitions against an RPM database.

Views Article Discussion Edit History
Personal tools:  Log in / create account
Toolbox What links here Related changes Upload file Special pages Printable version