From Openscap
Contents |
Users
This part of documentation explains usage of oscap tool in most common use cases and shows examples based on industry standard data (SCAP content). We don't cover all the options and capabilities of oscap tool here. Please see the oscap man page for more details.
$ man oscap
Installation
You can either build OpenSCAP library and oscap tool from a source code (see section developers) or use builds for your Linux distribution. Use this yum command if you want to install the tool on a Fedora or RHEL distribution:
# yum install openscap-utils
Common Usage
Before you start using oscap tool you need to install SCAP content on your machine. This could be done simply by downloading the content from a web site or installing it by your package management system.
Once the content is imported/installed on your computer it can be subsequently processed by oscap tool by specifying the correct file path. 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 SCAP content.
The following command can be used to list oscap tool version, supported specifications, built-in CPE names and supported OVAL objects.
$ oscap -V
Content Info
Let us say you have a file with SCAP content and you want to see information about the content inside. For instance: document type, version, status, date of creation. Or if you need to examine internal document structure. For XCCDF document or SCAP datastream it might be very useful to see: profiles, checklists, streams. You can run:
$ oscap info usgcb-rhel5desktop-ds.xml
Sample output of that command:
Document type: Source Data Stream
Imported: 2013-04-22T17:17:16
Stream: scap_org.open-scap_datastream_from_xccdf_usgcb-rhel5desktop-xccdf.xml
Generated: (null)
Version: 1.2
Checklists:
Ref-Id: scap_org.open-scap_cref_usgcb-rhel5desktop-xccdf.xml
Profile: xccdf_gov.nist.usgcb_profile_united_states_government_configuration_baseline
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 oscap tool is to perform scans of a local system. It's able to evaluate both XCCDF benchmark and OVAL definitions and generate appropriate results.
Please note, the content can be provided either in a single file (SCAP Data Stream) or as multiple separate files. Following examples distinguish between these two approaches.
OVAL
oscap tool is processing OVAL file during evaluation of OVAL definitions. The tool collects system information, evaluates it and generates OVAL Result File. The result of evaluation of each OVAL definition is printed to standard output stream.
Evaluation of all definitions within an OVAL Definition file.
$ oscap oval eval --results oval-results.xml scap-oval.xml
Evaluate just one particular definition with given ID from OVAL Definition file
$ oscap oval eval --id oval:rhel:def:1000 --results oval-results.xml scap-oval.xml
Evaluate all definitions from OVAL component that are part of a particular data stream within a SCAP data stream collection.
$ oscap oval eval --datastream-id ds.xml --oval-id xccdf.xml --results oval-results.xml scap-ds.xml
Sometimes the OVAL definition file is distributed along with the XCCDF file, in such cases it is possible that the OVAL depends on variables exported from that XCCDF file during the scan. Then the evaluation of the OVAL alone may produce misleading results.
To produce correct results, one needs to transform the variables from XCCDF down to the OVAL variable file. And provide this file in the evaluation.
$ 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
XCCDF
oscap tool processes XCCDF file, OVAL file and CPE dictionary during evaluation of XCCDF benchmark. The tool performs system analysis and produces XCCDF results. The result of evaluation of each XCCDF rule within XCCDF checklist is printed to standard output stream. CVE and CCE identifier associated with the rules are printed as well. This is a sample output for a single rule:
Title Verify permissions on 'group' file Rule usgcb-rhel5desktop-rule-2.2.3.1.j Ident CCE-3967-7 Result pass
CPE dictionary is used to determine if the content is applicable on targeted platform. Evaluation of not applicable content end up as "notapplicable" results for each XCCDF rule.
For evaluation of a specific profile in XCCDF file run this command:
$ oscap xccdf eval --profile Desktop --results xccdf-results.xml --cpe cpe-dictionary.xml scap-xccdf.xml
For evaluation of a specific XCCDF benchmark that is part of a data stream within a SCAP data stream collection run:
$ oscap xccdf eval --datastream-id ds.xml --xccdf-id xccdf.xml --results xccdf-results.xml scap-ds.xml
Validate
SCAP data format is usually very complex. It might happen quite easily that there some syntax or semantic issues in the content. Therefore we recommend verifying the content before use. oscap tool provides a validation functionality that verifies the content against SCAP standard XML schemas. Example below runs validation for given source datastream:
$ oscap ds sds-validate scap-ds.xml
It results in validation of all components (XCCDF, OVAL, CPE, ...) inside the datastream.
You can also enable extra Schematron-based validation in case of OVAL specification. It's a bit slower but provides deeper analysis.
$ oscap oval validate --schematron oval-file.xml
The results of validation are printed to standard error stream.
Content Transformation
We provide different XSLT transformations that might be handy when you want to transform SCAP content XML file into a human readable document.
Create Guide (see example)
$ oscap xccdf generate guide scap-xccdf.xml > guide.html
Create Guide plus Profile Checklist (see example)
$ oscap xccdf generate guide --profile Desktop scap-xccdf.xml > guide-checklist.html
XCCDF Scan Report (see example)
$ oscap xccdf generate report xccdf-results.xml > report-xccdf.html
OVAL Scan Report (see example)
$ oscap oval generate report oval-results.xml > report-oval.html
XCCDF report with additional info from failed OVAL tests (see 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 a industry standard checklists that were validated by NIST.
How to Evaluate DISA STIG(RHEL5)
OpenSCAP >= 0.9.1 is required to run evaluation properly.
Download and unpack the content
# wget http://iase.disa.mil/stigs/os/unix/u_redhat_5_v1r2_stig_benchmark_20130125.zip # unzip u_redhat_5_v1r2_stig_benchmark_20130125.zip
Fix the content.
# sed -i 's/<Group\ \(.*\)/<Group\ selected="false"\ \1/g' U_RedHat_5_V1R2_STIG_Benchmark-xccdf.xml
Evaluate your favourite profile, for example: MAC-1_Public. Write XCCDF results into 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
Generate report that you can open in a web browser.
# oscap xccdf generate report --output report.html results.xml
How to evaluate USGCB(RHEL5)
OpenSCAP >= 0.9.1 is required to run evaluation properly.
Download and unpack the content.
# wget http://usgcb.nist.gov/usgcb/content/scap/USGCB-rhel5desktop-1.0.5.0.zip # unzip USGCB-rhel5desktop-1.0.5.0.zip
Run evaluation.
# oscap xccdf eval --profile united_states_government_configuration_baseline --cpe usgcb-rhel5desktop-cpe-dictionary.xml --fetch-remote-resources --results results.xml usgcb-rhel5desktop-xccdf.xml
Generate report that you can open in a web browser.
# oscap xccdf generate report --output report.html results.xml
Developers
This part of documentation is mainly for developers. Its purpose is to help people who want to contribute to the project, help with bug fixing or take advantage of the OpenSCAP library and create projects on top of it.
Compilation
Compilation is pretty straightforward.
- ./autogen.sh for those who get fresh sources from git repository. It requires: autoconf, automake, libtool. If you use release taball you can skip this step.
- ./configure && make build the library. Dependencies may very, it depends on enabled features(by configure). By default you need: swig, libxml2-devel, rpm-devel, libgcrypt-devel, pcre-devel, python-devel, perl-devel, libcurl-devel, libxslt-devel, libtools installed on your system.
- make check run library self-checks
- make install run installation procedure
If you want to create package for Fedora or Red Hat Enterprise Linux distribution, you will need the spec files. These are available under: dist/{fedora,rhel5,rhel6} directories.
Debug
These are the instructions for debugging the library. It's very helpful for developers and users who wants help us with bug "hunting".
Script Check Engine
Script Check Engine(SCE) is an alternative check engine for XCCDF checklist evaluation. It's not part of any SCAP specification. It's a mechanism that allows you to call shell scripts out of XCCDF. This approach might be suitable for various use cases, mostly when OVAL checks are not required/needed. More information about SCE usage is available here.
Reference Manual
There is an online reference manual available for OpenSCAP library. This manual is included in release tarball and can be regenerated from project sources by Doxygen documentation system.
Build on Windows
The library is developed mainly on Linux platform but we do our best to make it multi-platform. Here are short instructions how to build it on windows in cygwin environment.
FAQ
- Is it possible to convert USGCB into SCAP data stream?
- Yes, it is see. See this blog post
- How can I split SCAP datastream into individual files?
- See this post
- Is it possible to scan image of a virtual machine?
- This work is in progress.
- Would be possible to automatically change machine state and make it compliant with desired security policy?
- You looking for SCAP remediation functionality
- Would be possible in remediate machine during installation, before first boot?
- Yes, there is a working solution for Anaconda installer, which is used on Fedora and RHEL systems.
- Is there an light weight alternative for OVAL checks?
- Yes, there is Script Check Engine
