.TH OSCAP "8" "Jun 2010" "Red Hat" "System Administration Utilities"

.SH NAME
oscap \- OpenSCAP command line tool

.SH SYNOPSIS
\fBoscap\fR [\fIgeneral-options\fR] \fBmodule\fR operation [\fIoperation-options-and-arguments\fR]

.SH DESCRIPTION
\fBoscap\fP is Security Content Automation Protocol (SCAP) toolkit based on OpenSCAP library. It provides various functions for 
different SCAP specifications(modules).

.SH GENERAL OPTIONS
.TP
\fB\-V, -\-version\fR
SCAP specification supported by the module.
.TP
\fB\-q, \-\-quiet\fR
No output for certain operations, only return code.
.TP
\fB\-h, \-\-help\fR
Help screen.

.SH MODULES
.TP
\fBoval\fR
Open Vulnerability and Assessment Language.
.TP
\fBxccdf\fR
The eXtensible Configuration Checklist Description Format.
.TP
\fBcpe\fR
Common Platform Enumeration.
.TP
\fBcvss\fR
Common Vulnerability Scoring System

.SH OVAL OPERATIONS
.TP
.B collect\fR [\fIoptions\fR] definitions-file
.RS
Probe the system and gather system characteristics for all objects in OVAL Definition file.
.PP
.TP
\fB\-\-id OBJECT-ID\fR
Collect system characteristics ONLY for specified OVAL Object.
.TP
\fB\-\-variables FILE\fR
Provide external variables expected by OVAL Definitions.
.TP
\fB\-\-syschar FILE\fR
Write OVAL System Characteristic into file
.TP
\fB\-\-skip-valid\fR
Do not validate input/output files.
.RE
.TP
.B eval\fR [\fIoptions\fR] definitions-file
.RS
Probe the system and evaluate all definitions from OVAL Definition file. Print result of each definition to standard output. oscap returns 0 if all definitions pass. If there is an error during evaluation, the return code is 1. If there is at least one failed result definition, oscap-scan finishes with return code 2.
.PP
.TP
\fB\-\-id DEFINITION-ID\fR
Evaluate ONLY specified OVAL Definition.
.TP
\fB\-\-variables FILE\fR
Provide external variables expected by OVAL Definitions.
.TP
\fB\-\-directives FILE\fR
Use OVAL Directives content to specify desired results content.
.TP
\fB\-\-results FILE\fR
Write OVAL Results into file.
.TP
\fB\-\-report FILE\fR
Create human readable (HTML) report from OVAL Results.
.TP
\fB\-\-skip-valid\fR
Do not validate input/output files.
.RE
.RE

.TP
.B analyse\fR [\fIoptions\fR] --results FILE definitions-file syschar-file
.RS
In this mode, the oscap tool does not perform data collection on the local system, but relies upon the input file, which may have been generated on another system. The output (OVAL Results) is printed to file specified by \fB--results\fR parameter
.TP
\fB\-\-variables FILE\fR
Provide external variables expected by OVAL Definitions.
.TP
\fB\-\-directives FILE\fR
Use OVAL Directives content to specify desired results content.
.TP
\fB\-\-skip-valid\fR
Do not validate input/output files.
.RE

.TP
.B validate-xml\fR [\fIoptions\fR] definitions-file
.RS
Validate given OVAL file against a XML schema. Every found error is printed to the standard output. Return code is 0 if validation succeeds, 1 if validation could not be performed due to some error, 2 if the OVAL document is not valid.
.TP
\fB\-\-definitions\fR, \fB\-\-variables\fR, \fB\-\-syschar\fR, \fB\-\-results\fR \fB\-\-directives\fR
Specify whether the validated document is an OVAL Definitions file, external OVAL Variables, OVAL System Characteristics file,  OVAL Results file or OVAL Directives file. Default: definitions.
.TP
\fB\-\-schematron\fR
Turn on Schematron-based validation. It is able to find more errors and inconsistencies but is much slower.
.RE
.TP
.B \fBgenerate\fR <submodule> [submodule-specific-options]
.RS
Generate another document form an OVAL file.
.TP
Available submodules:
.TP
.B \fBreport\fR  [\fIoptions\fR] oval-results-file
.RS
Generate a formatted HTML page containing visualisation of an OVAL results file. Unless the --output option is specified it will be written to the standard output.
.TP
\fB\-\-output FILE\fR
Write the report to this file instead of standard output.
.RE
.RE
.TP
.B \fBlist-probes\fR  [\fIoptions\fR]
.RS
List supported object types (i.e. probes)
.TP
\fB\-\-static\fR
List all probes defined in the internal tables.
.TP
\fB\-\-dynamic\fR
List all probes supported on the current system (this is default behavior).
.TP
\fB\-\-verbose\fR
Be verbose.
.RE

.SH XCCDF OPERATIONS
.TP
.B \fBeval\fR [\fIoptions\fR] xccdf-file [\fIoval-definitions-files\fR]
.RS
Perform evaluation driven by XCCDF file and use OVAL as checking engine. Print result of each rule to standard output. oscap returns 0 if all rules pass. If there is an error during evaluation, the return code is 1. If there is at least one failed rule, oscap-scan finishes with return code 2.
.PP
You may specify all required OVAL Definition files as last parameters. If you don't do that, oscap tool will try to load all OVAL Definition files referenced from XCCDF automaticaly(search in the same path as XCCDF).
.PP
.TP
\fB\-\-profile PROFILE\fR
.RS
Select a particular profile from XCCDF document.
.RE
.TP
\fB\-\-results FILE\fR
.RS
Write XCCDF results into file.
.RE
.TP
\fB\-\-report FILE\fR
.RS
Write HTML report into file. You also have to specify --result for this feature to work.
.RE
.TP
\fB\-\-oval-results\fR
.RS
Generate OVAL Result file for each OVAL session used for evaluation. File with name '\fIoriginal-oval-definitions-filename\fR.result.xml' will be generated for each referenced OVAL file. This option (with conjunction with the \fB\-\-report\fR option) also enables inclusion of additional OVAL information in the XCCDF report.
.RE
.TP
\fB\-\-export-variables\fR
.RS
Generate OVAL Variables documents which contain external variables' values that were provided to the OVAL checking engine during evaluation. The filename format is '\fIoriginal-oval-definitions-filename\fR-\fIsession-index\fR.variables-\fIvariables-index\fR.xml'.
.RE
.TP
\fB\-\-skip-valid\fR
.RS
Do not validate input/output files.
.RE
.RE
.TP
.B resolve\fR -o output-file xccdf-file
.RS
Resolve an XCCDF file as described in the XCCDF specification. It will flatten inheritance hierarchy of XCCDF profiles, groups, rules, and values. Result is another XCCDF document, which will be written to \fIoutput-file\fR.
.TP
\fB\-\-force\fR
Force resolving XCCDF document even if it is already marked as resolved.
.RE
.TP
.B validate-xml\fR [\fIoptions\fR] xccdf-file
.RS
Validate given XCCDF file against a XML schema. Every found error is printed to the standard output. Return code is 0 if validation succeeds, 1 if validation could not be performed due to some error, 2 if the XCCDF document is not valid.
.RE
.TP
.B export-oval-variables\fR [\fIoptions\fR] xccdf-file [\fIoval-definitions-files\fR]
.RS
Collect all the XCCDF values that would be used by OVAL during evaluation of a certain profile and export them as OVAL external-variables document(s). The filename format is '\fIoriginal-oval-definitions-filename\fR-\fIsession-index\fR.variables-\fIvariables-index\fR.xml'.
.PP
.TP
\fB\-\-profile PROFILE\fR
.RS
Select a particular profile from XCCDF document.
.RE
.RE
.TP
.B \fBgenerate\fR [\fIoptions\fR] <submodule> [submodule-specific-options]
.RS
Generate another document form an XCCDF file such as security guide or result report.
.TP
\fB\-\-profile ID\fR
Apply profile with given ID to the Benchmark before further processing takes place.
.TP
\fB\-\-format FMT\fR
Specify output format. This option applies only on document generators (i.e. guide, report). Avalable formats: \fIhtml\fR (default), \fIdocbook\fR.
.TP
Available submodules:
.TP
.B \fBguide\fR  [\fIoptions\fR] xccdf-file
.RS
Generate a formatted document containing a security guide from a XCCDF Benchmark. Unless the --output option is specified it will be written to the standard output. Without profile being set only groups (not rules) will be included in the output.
.TP
\fB\-\-output FILE\fR
Write the guide to this file instead of standard output.
.TP
\fB\-\-hide-profile-info\fR
Information on chosen profile (e.g. rules selected by the profile) will be excluded from the document.
.RE
.TP
.B \fBreport\fR  [\fIoptions\fR] xccdf-file
.RS
Generate a document containing results of a XCCDF Benchmark execution. Unless the --output option is specified it will be written to the standard output. ID of the TestResult element to visualise defaults to the most recent result (according to the end-time attribute).
.TP
\fB\-\-output FILE\fR
Write the report to this file instead of standard output.
.TP
\fB\-\-result-id ID\fR
ID of the XCCDF TestResult from which the report will be generated.
.TP
\fB\-\-show \fIwhat\fR
Specify what result types shall be displayed in the result report. The default is to show everything except for rules with results notselected and notapplicable. The \fIwhat\fR part is a comma-separated list of result types to display in addition to the default. If result type is prefixed by a dash '-', it will be excluded from the results. If \fIwhat\fR is prefixed by an equality sign '=', a following list specifies exactly what rule types to include in the report. Result types are: pass, fixed, notchecked, notapplicable, notselected, informational, unknown, error, fail.
.TP
\fB\-\-oval-template \fItemplate-string\fR
To use the ability to include additional information from OVAL in xccdf result file, a template which will be used to obtain OVAL result file names has to be specified. The template can be either a filename or a string containing wildcard character (percent sign '%'). Wildcard will be replaced by the original OVAL definition file name as referenced from the XCCDF file. This way it is possible to obtain OVAL information even from XCCDF documents referencing several OVAL files. To use this option with results from an XCCDF evaluation, specify \fI%.result.xml\fR as a OVAL file name template.
.RE
.TP
.B \fBfix\fR  [\fIoptions\fR] xccdf-file
.RS
Generate a script that shall bring the system to a state of compliance with given XCCDF Benchmark.
.TP
\fB\-\-output FILE\fR
Write the report to this file instead of standard output.
.TP
\fB\-\-result-id \fIID\fR\fR
With this option the script generating engine will pick rules that failed for given test and generate fixes only for them.
.TP
\fB\-\-template \fIID|FILE\fR\fR
Template to be used to generate the script. If it contains a dot '.' it is interpreted as a location of a file with the template definition. Otherwise it identifies a template from standard set which currently includes: \fIbash\fR (default if no --template switch present). Brief explanation of the process of writing your own templates is in the XSL file \fIxsl/fix.xsl\fR in the openscap data directory. You can also take a look at the default template \fIxsl/fixtpl-bash.xml\fR.
.RE

.SH CPE OPERATIONS
.TP
.B \fBcheck\fR name
.RS
Check whether name is in correct CPE format.
.RE
.PP
.B \fBmatch\fR name dictionary.xml
.RS
Find an exact match of CPE name in the dictionary.

.SH CVSS OPERATIONS
.TP
.B \fBscore\fR \fIcvss_vector\fR
.RS
Calculate score from a CVSS vector. Prints base score for base CVSS vector, base and temporal score for temporal CVSS vector, base and temporal and environmental score for environmental CVSS vector.
.RE
.TP
.B \fBdescribe\fR \fIcvss_vector\fR
.RS
Describe individual components of a CVSS vector in a human-readable format and print partial scores.
.RE
.TP
.B \fICVSS vector\fR consists of several slash-separated components specified as key-value pairs. Each key can be specified at most once. Valid CVSS vector has to contain at least base CVSS metrics, i.e. AV, AC, AU, C, I, and A. Following table summarizes the components and possible values (second column is metric category: B for base, T for temporal, E for environmental):
.RS
.P
AV:[L|A|N]            B   Access vector: Local, Adjacent network, Network
.P
AC:[H|M|L]            B   Access complexity: High, Medium, Low
.P
AU:[M|S|N]            B   Required authentication: Multiple instances, Single instance, None
.P
C:[N|P|C]             B   Confidentiality impact: None, Partial, Complete
.P
I:[N|P|C]             B   Integrity impact: None, Partial, Complete
.P
A:[N|P|C]             B   Availability impact: None, Partial, Complete
.P
E:[ND|U|POC|F|H]      T   Exploitability: Not Defined, Unproven, Proof of Concept, Functional, High
.P
RL:[ND|OF|TF|W|U]     T   Remediation Level: Not Defined, Official Fix, Temporary Fix, Workaround, Unavailable
.P
RC:[ND|UC|UR|C]       T   Report Confidence: Not Defined, Unconfirmed, Uncorroborated, Confirmed
.P
CDP:[ND|N|L|LM|MH|H]  E   Collateral Damage Potential: Not Defined, None, Low, Low-Medium, Medium-High, High
.P
TD:[ND|N|L|M|H]       E   Target Distribution: Not Defined, None, Low, Medium, High
.P
CR:[ND|L|M|H]         E   Confidentiality requirement: Not Defined, Low, Medium, High
.P
IR:[ND|L|M|H]         E   Integrity requirement: Not Defined, Low, Medium, High
.P
AR:[ND|L|M|H]         E   Availability requirement: Not Defined, Low, Medium, High
.RE
.RE
.PP


.SH CONTENT
.TP
\fB National Vulnerability Database\fR - \fIhttp://web.nvd.nist.gov/view/ncp/repository\fR
.TP
\fB Red Hat content repository\fR - \fIhttp://www.redhat.com/security/data/oval/\fR


.SH AUTHOR
Peter Vrabec <pvrabec@redhat.com>