SIX OVAL: Users Guide (version 0.6.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:

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.

Table 1: OVAL Namespaces and Java Packages

OVAL Namespace(s) Java Package
http://oval.mitre.org/XMLSchema/oval-common-5 jp.go.aist.six.oval.model.common
http://oval.mitre.org/XMLSchema/oval-definitions-5 jp.go.aist.six.oval.model.definitions
http://oval.mitre.org/XMLSchema/oval-definitions-5#independent
http://oval.mitre.org/XMLSchema/oval-system-characteristics-5#independent
jp.go.aist.six.oval.model.independent
http://oval.mitre.org/XMLSchema/oval-definitions-5#linux
http://oval.mitre.org/XMLSchema/oval-system-characteristics-5#linux
jp.go.aist.six.oval.model.linux
http://oval.mitre.org/XMLSchema/oval-results-5 jp.go.aist.six.oval.model.results
http://oval.mitre.org/XMLSchema/oval-system-characteristics-5 jp.go.aist.six.oval.model.sc
http://oval.mitre.org/XMLSchema/oval-definitions-5#unix
http://oval.mitre.org/XMLSchema/oval-system-characteristics-5#unix
jp.go.aist.six.oval.model.unix
http://oval.mitre.org/XMLSchema/oval-definitions-5#windows
http://oval.mitre.org/XMLSchema/oval-system-characteristics-5#windows
jp.go.aist.six.oval.model.windows

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

There are few exceptions which do not follow the above conventions. One of them is the different types with the same name. For example, two types with the same name "DefinitionType" are defined in the Definition and Results schemas, respectively. Such naming may cause trouble. Therefore, we append the prefix "Result" to the type to the latter: "DefinitionResult".

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.

Figure 1: OVAL Definition Model (basic part)

UML: OVAL Definitions Model

1.4 OVAL System Characteristics Model

Figure 2 shows the OVAL System Characteristics Model.

Figure 2: OVAL System Characteristics Model

UML: OVAL System Characteristics Model

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.

Figure 3: OVAL Results Model

UML: OVAL Results Model


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.

Listing 1: Unmarshalling


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.

Listing 2: Marshalling


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.

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.

Listing 3: Castor JDO Configuration (six-oval_castor-jdo-conf.xml)


<?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>

Listing 4: Castor JDO Configuration Parameters (example)


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.

Listing 5: Save/Load Example


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.

Listing 6: Synchronization Example


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.

Listing 7: Query Examples


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_6_0.html 1094 2010-11-05 08:05:27Z akihito $

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