SIX OVAL: Users Guide (version 0.5.0)

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

1. Domain Model

1.1 Introduction

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

• representing configuration information of systems for testing,
• analyzing the system for the presence of the specified machine state (vulnerability, configuration, patch state, etc.), and
• reporting the results of this assessment.

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 schemas, respectively. These schemas are defined using W3C's XML Schema.

The Domain Model of SIX OVAL is a set of Java classes which reflects the OVAL Definition, System Characteristics, and Results schemas. 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.

1.2 Java Class Mapping

Table 1 represents the mapping from the OVAL namespaces to the Java packages.

The naming of Java classes and their properties are straightforward. We keep the following regulations to have respect for Java naming convensions:

• The postfix "Type" of the OVAL schema's type name is removed in the corresponding Java class name. For example, the OVAL "DefinitionType" type is mapped to the Java "Definition" class.
• Underscores are removed and the camel cases are used. For example, the OVAL "oval_definitions" element is mapped to the Java "OvalDefinitions" class.
• The Java reserved words and well-known names are avoided. For example, the OVAL "ObjectType" type is mapped to the Java "SystemObject" class.

1.3 OVAL Definition Model

The main entities of the OVAL Definition schema, Definition, Test, Object, State, and Variable, are defined as subclasses of the abstract classes as shown in Figure 1.

• OvalElement is the abstract base class for all the objects which have OVAL id and version properties. id and version are renamed ovalID and ovalVersion, respectively. ovalGlobalID property is derived from ovalID and ovalVersion.
• The OVAL ObjectType type is renamed SystemObject.

1.4 OVAL System Characteristics Model

Figure 2 shows the OVAL System Characteristics Model.

• The OVAL InterfaceType type is renamed NetInterface because the interface is a reserved words in Java.
• The OVAL CollectedObjectsType and ObjectType types are renamed CollectedSystemObjects and CollectedSystemObject, respectively.

1.5 OVAL Results Model

Figure 3 shows the OVAL Results Model. Some types are renamed so that the names are not doubled ones in the Definitions model.

• The OVAL ResultsType and SystemType types are renamed SystemResults and SystemResult, respectively.
• The OVAL DefinitionsType and DefinitionType types are renamed DefinitionResults and DefinitionResult, respectively.
• The OVAL TestsType and TestType types are renamed TestResults and TestResult, respectively.

3. Object-XML Mapping (OXM)

This feature supports marshalling/unmarshalling of OVAL objects. That is, it is possible to serialize/deserialize the OVAL objects to/from an XML document.

Listing 1 shows how to read OVAL objects from an XML file. Since the argument type of the unmarshal method is InputStream, the source to read from is not limited to a file.

import jp.go.aist.six.oval.core.service.OvalContext;
import jp.go.aist.six.oval.core.xml.OvalXml;
import jp.go.aist.six.oval.model.definitions.Definition;
import jp.go.aist.six.oval.model.definitions.OvalDefinitions;
import java.io.File;
import java.io.FileInputStream;

OvalContext  context = new OvalContext();
OvalXml  mapper = context.getXml();

File  file = new File( "oval-def.xml" );
OvalDefinitions  defs = (OvalDefinitions)mapper.unmarshal( new FileInputStream( file ) );
for (Definition  def : defs.getDefinitions()) {
    .....
}

Listing 2 shows how to write OVAL model objects to an XML file.

import jp.go.aist.six.oval.core.service.OvalContext;
import jp.go.aist.six.oval.core.xml.OvalXml;
import jp.go.aist.six.oval.model.definitions.OvalDefinitions;
import java.io.File;
import java.io.FileOutputStream;

OvalDefinitions  defs = .....;

OvalContext  context = new OvalContext();
OvalXml  mapper = context.getXml();

File  file = new File( "oval-def.xml" );
mapper.marshal( defs, new FileOutputStream( file ) );

4. Object-Relational Mapping (ORM)

This feature supports persistence of OVAL objects. That is, it is possible to save/load the OVAL objects to/from a relational database, and to retrieve objects in a programmatic way.

Limitation: In this version, only MySQL is supported.

4.1 Database Setup

Before using the ORM feature, you must create a database to store the OVAL objects and a user account with the full privileges. Then, create the tables in the database using the SQL script file in src/sql/mysql/create-tables.sql. Note that the MySQL use statement in the file must be corrected to reflect the database name.

• ER diagram [ PNG | PDF ]

4.2 Castor Configuration

Several configuration parameters must be set into the Castor JDO configuration file. A template file is src/java/six-oval_castor-jdo-conf.xml (Listing 3). The file name can't be changed but located in any directory in the Java classpath. Here, the attribute values like "@...@" must be set to reflect the environment. Listing 4 shows example configuration parameters.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jdo-conf PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                          "http://castor.org/jdo-conf.dtd">

<jdo-conf>
    <database name="oval" engine="@six.db.engine@" >
        <data-source class-name="org.apache.commons.dbcp.BasicDataSource">
            <param name="driver-class-name" value="@six.db.driver@"/>
            <param name="url"               value="@six.db.url@"/>
            <param name="max-active"        value="8"/>
            <param name="validation-query"  value="SELECT 1"/>
            <param name="username"          value="@six.db.username@"/>
            <param name="password"          value="@six.db.password@"/>
        </data-source>
        <mapping href="six-oval_castor-jdo-mapping.xml"/>
    </database>

    <transaction-demarcation mode="local">
        <transaction-manager name="local" />
    </transaction-demarcation>
</jdo-conf>

six.db.driver    =com.mysql.jdbc.Driver
six.db.url       =jdbc:mysql://localhost/oval
six.db.username  =oval
six.db.password  =oval-admin
six.db.database  =oval
six.db.engine    =mysql

4.3 Basic Operations

Listing 5 shows a code snippet to save/load an OVAL object. Here, pid returned from the create method is the database primary key.

import jp.go.aist.six.oval.core.service.OvalContext;
import jp.go.aist.six.oval.core.store.OvalStore;
import jp.go.aist.six.oval.model.definitions.OvalDefinitions;

OvalContext  context = new OvalContext();
OvalStore  store = context.getStore();

OvalDefinitions  defs1 = .....;
String  pid = store.create( OvalDefinitions.class, defs1 );

.....
OvalDefinitions  defs2 = store.get( OvalDefinitions.class, pid );

Listing 6 shows a code snippet to save an OVAL entity. Here, the sync method is used to save the object whether it already exists in the database or not. With the create method, if the same object already exists in the database, an Exception is thrown. Since the OVAL entities --- Definitions, Tests, SystemObjects, States, and Variables --- may be used in multiple OVAL documents, the sync method is preferable.

import jp.go.aist.six.oval.core.service.OvalContext;
import jp.go.aist.six.oval.core.store.OvalStore;
import jp.go.aist.six.oval.model.definitions.Definition;

OvalContext  context = new OvalContext();
OvalStore  store = context.getStore();

Definition  def = .....;
store.sync( Definition.class, def );

4.4 Queries

The objects in the database can be retrieved using the find method as shown in Listing 7. Here, filter1 selects all the Definition objects which have reference to the specified CVE ID. On the other hand, filter2 selects all the Definitions of the vulnerability class. The query result list2 is sorted according to OVAL IDs and contains at most 10 objects.

import jp.go.aist.six.oval.core.service.OvalContext;
import jp.go.aist.six.oval.core.store.OvalStore;
import jp.go.aist.six.oval.model.definitions.Definition;
import jp.go.aist.six.util.search.Binding;
import java.util.List;

OvalContext  context = new OvalContext();
OvalStore  store = context.getStore();

Binding  filter1 = RelationalBinding.equalBinding( "metadata.reference.refID", "CVE-2009-4019" );
List<Definition>  list1 = store.find( Definition.class, filter1 );

Binding  filter2 = RelationalBinding.equalBinding( "definitionClass", DefinitionClass.VULNERABILITY );
List<Order>  ordering = new ArrayList();
ordering.add( new Order( "ovalID" ) );
Limit  limit = new Limit( 10 );
List<Definition>  list2 = store.find( Definition.class, filter2, ordering, limit );

4. Runtime Configuration

T.B.D.

document version: $Id: users-guide-0_5_0.html 1091 2010-11-05 03:44:24Z akihito $

© 2010 Akihito Nakamura. Term of Use.