SIX OVAL: Users Guide (version 0.4.0)

This article describes the SIX OVAL usage and a bit of internal details.

1. OVAL Interpreter

1.1 Introduction

Open Vulnerability and Assessment Language (OVALĀ®) is a language to standardize the three main steps of the assessment process:

System information, a specific machine state, and the results of an assessment are written in XML which are conform to OVAL System Characteristics, Definition, and Results schema, respectively.

The OVAL Interpreter collects system information based on a set of OVAL Definitions read from an XML document, evaluates it, and writes the information and the evaluation results to OVAL System Characteristics and Results documents respectively (Figure 1). There is a freely available reference implementation of the Interpreter. The Interpreter is a command named ovaldi. To invoke the Interpreter, the input OVAL Definition document is located on the target system as a file.

Figure 1: Input and Output of the OVAL Interpreter

OVAL-Interpreter

The SIX OVAL Interpreter is a small extension to the OVAL Interpreter at the input/output feature. It can get the Definition and send the Results documents via HTTP, in the REST style (Figure 2). The main assessment process is forwarded to the reference implementation, i.e. ovaldi.

Figure 2: Input and Output of the SIX OVAL Interpreter

SIX-OVAL-Interpreter

1.2 Using the SIX OVAL Interpreter

The Java class for the SIX OVAL Interpreter is NetOvalIntepreter. Listing 1 shows the least steps to create and execute the Interpreter. The parameter of the constructor represents a command line to invoke ovaldi. That is, the executable program and its arguments. Here, the "-o" option specifies the input OVAL definition document. See the documents of the reference implementation to find the details of the options.

Listing 1: Creation and execution of the OVAL Interpreter


import jp.go.aist.six.oval.process.NetOvalIntepreter;
import jp.go.aist.six.oval.process.OvalProcessStatus;

String[]  cmdarray = new String[] {
  "/usr/sbin/ovaldi",
  "-a", "/usr/share/ovaldi",
  "-o", "definitions.xml",
  "-s",
  "-m"
};

NetOvalIntepreter  interpreter = new NetOvalIntepreter( cmdarray );
OvalProcessStatus  status = interpreter.execute();

The SIX Interpreter is utilized by the "-o" option with an URL and the additional "-post" option. In Listing 2, the Definition document is obtained from the OVAL web site. In Listing 3, the Results document is sent to a server at the specified location. The server may be a centralized store of assessment results. It sure is possible to set the "-o" option with a local file and the "-post" option.

Listing 2: Creation of the OVAL Interpreter (HTTP input)


String[]  cmdarray = new String[] {
  "/usr/sbin/ovaldi",
  "-a", "/usr/share/ovaldi",
  "-o", "http://oval.mitre.org/repository/data/DownloadDefinition?id=oval%3aorg.mitre.oval%3adef%3aXXXX",
  "-s",
  "-m"
};

NetOvalIntepreter  interpreter = new NetOvalIntepreter( cmdarray );

Listing 3: Creation of the OVAL Interpreter (HTTP input/output)


String[]  cmdarray = new String[] {
  "/usr/sbin/ovaldi",
  "-a", "/usr/share/ovaldi",
  "-o", "http://oval.mitre.org/repository/data/DownloadDefinition?id=oval%3aorg.mitre.oval%3adef%3aXXXX",
  "-post", "http://example.org/oval/results/",
  "-s",
  "-m"
};

NetOvalIntepreter  interpreter = new NetOvalIntepreter( cmdarray );

2. Generation of OVAL Definitions

Some major operating systems are supported by the OVAL Community or vendors. Here, we show how to generate OVAL Definition documents dedicated to several operating systems which are NOT supported by them.

2.1 CentOS

CentOS is a type of Red Hat Enterprise Linux (RHEL). On investigation, we concluded that there are rules in naming of CentOS package releases derived from the ones of RHEL. In SIX OVAL, the rules are written in XSLT, and OVAL Definitions dedicated to CentOS are generated by transforming the ones for RHEL using an XSLT processor.

2.1.1 Programmatic usage

Listing 4 shows how to generate OVAL Definition documents dedicated for CentOS. The CentOSOvalGenerator class is responsible to this generation. The object has two properties, one for the input RHEL Definition document and another one for the output CentOS Definition document.

Listing 4: CentOS OVAL Generator (programmatic usage)


import jp.go.aist.six.oval.process.OvalProcessStatus;
import jp.go.aist.six.oval.process.centos.CentOSOvalGenerator;

.....
String  sourceDef = "https://rhn.redhat.com/rhn/oval?errata=9522";
String  generatedDef = "oval-definition_9522.xml";

CentOSOvalGenerator  generator = new CentOSOvalGenerator();
generator.setSourceRedhatDefinitionLocation( sourceDef );
generator.setOutputDefinitionLocation( generatedDef );

OvalProcessStatus  status = generator.execute();

2.1.2 Command line usage

From a command line, the Generator is invoked using the Java application launcher, i.e. java command. In this case, a wrapper class CentOSOvalGeneratorCli is used. There are two arguments:

Listing 5: CentOS OVAL Generator (command line usage)


$ java -classpath ... \
  jp.go.aist.six.oval.process.centos.CentOSOvalGeneratorCli \
  -rho https://rhn.redhat.com/rhn/oval?errata=9522 \
  -o oval-definition_9522.xml

2.2 Debian GNU/Linux

We found that the Debian Security Advisory (DSA) web pages contain sufficient information to generate OVAL Definition documents for Debian GNU/Linux. They include the information about what packages fix the security issues.

Figure 3 shows the steps to generate a Definition document in SIX OVAL.

  1. First, a DSA page is parsed and a Java object representing it is created by the DSA Parser.
  2. Secondly, another Java object representing an OVAL Definition is generated from the DSA object.
  3. At last, the OVAL object is serialized to an OVAL Definition document.

Figure 3: Debian OVAL Generator

Debian-OVAL-Generator

Here, the Debian OVAL Generator is responsible for the whole process. Jericho HTML Parser and Castor are utilized for parsing the DSA pages and object serialization by the DSA Parser and XML Mapper, respectively.

2.2.1 Programmatic usage

The Debian OVAL Generator, DebianOvalGenerator class, can be configured with two properties. The one is the location of the source DSA and another is the path name of the generated document file (Listing 6).

Listing 6: Debian OVAL Generator (programmatic usage)


import jp.go.aist.six.oval.process.OvalProcessStatus;
import jp.go.aist.six.oval.process.debian.DebianOvalGenerator;

.....
String  sourceDsa = "http://www.debian.org/security/2010/dsa-1974.en.html";
String  generatedDef = "oval-definition_1974.xml";

DebianOvalGenerator  generator = new DebianOvalGenerator();
generator.setSourceDsaLocation( sourceDsa );
// or  DebianOvalGenerator  generator = new DebianOvalGenerator( sourceDsa );
generator.setOutputDefinitionLocation( generatedDef );

OvalProcessStatus  status = generator.execute();

2.2.2 Command line usage

From a command line, a wrapper class DebianOvalGeneratorCli is invoked with the following arguments:

Listing 7: Debian OVAL Generator (command line usage)


$ java -classpath ... \
  jp.go.aist.six.oval.process.DebianOvalGeneratorCli \
  -dsa http://www.debian.org/security/2010/dsa-1974.en.html \
  -o oval-definition_1974.xml

2.2.3 Configuration of Debian OVAL Generator

There are several properties to configure the generation process. See the section 4 for how to specify the values.

Configuration Properties for Debian OVAL Generation

Property name Description Sample values
six.oval.debian.dsc (optional) Location of the Debian package description (dsc) files. The value is a directory path or an URL. The description files are assumed to be located immediate under this location. A dsc file is required to retrieve the epoch, version, and release, and binary names. If this property is not specified, dsc files are obtained from the Debian site. This property can be used for off-line processing. /usr/local/src/deb/dsc

3. OVAL Domain Model

The Domain Model is a set of Java classes which reflects the OVAL Definition, System Characteristics, and Results schema. In this model, several interfaces and abstract classes, that are not appear in the OVAL schema, are introduced from an object-oriented point of view.

TODO: UML diagrams ...

Figure 4: OVAL Domain Model (Definition)

UML_OVAL-Definition


3. OVAL Data Store

This feature supports persistence of OVAL objects. That is, it is possible to save/load the OVAL Definitions and the Results to/from a relational database. Query features are now in developing stage.

In combination with the SIX OVAL Interpreter, it is possible to build a security assessment system in a client-server style.

TODO: .....


4. Runtime Configuration

SIX OVAL can be configured by Java properties.

The Java system properties have higher priority. The details of the properties are described in the related sections.


Akihito Nakamura, <nakamura-akihito @ aist.go.jp >

National Institute of Advanced Industrial Science and Technology (AIST)
Information Technology Research Institute
AIST Tsukuba Central 2, 1-1, Umezono 1-Chome, Tsukuba-shi, Ibaraki-ken, 305-8568 JAPAN

© 2010 Akihito Nakamura. Term of Use.

Valid XHTML 1.0 Strict