****************************************************

         OVAL XML Definition Interpreter

    Copyright (c) 2005 - The MITRE Corporation

****************************************************

The MITRE Corporation developed the Open Vulnerability Assessment
Language (OVAL) XML Definition Interpreter to provide the OVAL Community
with an open source reference implementation of the language and its
Definitions.  The Definition Interpreter uses OVAL Definitions to gather
security relevant configuration information on a computer (e.g. rpm
parameters, registry keys, file information, etc.), analyze the information
for vulnerabilities, and generate a list of Common Vulnerabilities and
Exposures (CVE) identifiers for those vulnerabilities found.

You may download the Interpreter to any computer you wish, and to as
many computers as you wish.  

BY USING THE DEFINITION INTERPRETER, YOU SIGNIFY YOUR ACCEPTANCE OF THE
TERMS AND CONDITIONS OF USE.  IF YOU DO NOT AGREE TO THESE TERMS, DO NOT
USE THE INTERPRETER.

Please refer to the terms.txt file or http://oval.mitre.org/oval/termsofuse.html
for more information.


-- CONTENTS --

  I   INSTALLATION
        A. Red Hat Linux 
        B. Sun Solaris
        C. Microsoft Windows 
  II  USING THE INTERPRETER
        A. Required Privileges
        B. Data Protection
        C. Obtaining Updated Data Files
        D. Quick Usage Guide
        E. Advanced Usage
  III INPUT AND OUTPUT
        A. Input
        B. Output
  IV  PCRE
  V   XERCES
  VI  TROUBLESHOOTING
  VII REPORTING PROBLEMS


-- I -- INSTALLATION --

  Download an appropriate installation file from the OVAL Web site,
  (http://oval.mitre.org) by following the 'Download' link to the
  Interpreters.  Once you've downloaded the Interpreter, follow the
  corresponding instructions to install the Definition Interpreter on
  your system.

  A. Red Hat Linux Installation

       The OVAL Definition Interpreter can be installed and run on Red
       Hat Linux 9 and Red Hat Enterprise Linux 3.

       Install the RPM simply by running the following command:

       # rpm -ivh <Definition Interpreter RPM>

       The RPM places the following files on the system.  To learn their
       exact location after install, run:  rpm -ql ovaldi.

       Executables:
       ovaldi.sh - Shell Script to simplify execution of the Definiton Interpreter
       ovaldi - Definition Interpreter binary

       Libraries:
       libxerces-c.so.26.0 - Xerces XML library
       libpcre.so.0.0.1 - PCRE Regular Expression library

       Documentation:
       README.txt - This file
       terms.txt - License and Terms of Use
       version.txt - Definition Interpreter change log

       XML:
       definitions.xml - INTERIM and ACCEPTED OVAL definitions
			  (See "Obtaining Updated Data Files" below)

       XML Schema:
       oval-schema.xsd - Core OVAL Schema
       redhat-schema.xsd - Red Hat extensions to the Core Schema
       solaris-schema.xsd - Solaris extensions to the Core Schema
       windows-schema.xsd - Microsoft Windows extensions to the Core Schema

       system-characteristics-schema.xsd - Schema for raw configuration data 
					   collected by the Interpreter
       redhat-characteristics-schema.xsd - Red Hat extensions to the System
					   Characteristics Schema
       solaris-characteristics-schema.xsd - Solaris extensions to the System
					   Characteristics Schema
       windows-characteristics-schema.xsd - Microsoft Windows extensions to the
					    System Characteristics Schema

       oval-results-schema.xsd - Schema for the Interpreter Assessment results
       redhat-results-schema.xsd - Red Hat extensions to the Results Schema
       solaris-results-schema.xsd - Solaris extensions to the Results Schema
       windows-results-schema.xsd - Microsoft Windows extensions to the Results Schema

 
       The .so file for the Xerces library must be made accessible to
       the Definition Interpreter binary.  The ovaldi RPM places a 
       pre-compiled version in /usr/lib/ovaldi/ and appends this directory
       to your /etc/ld.so.conf file.

       To run the definition interpreter, run:

       # /usr/sbin/ovaldi.sh

       A result summary will be output to the screen, and detailed System
       Characteristic and Output Results will be output to /var/log/ovaldi.
		

  B. Sun Solaris Installation

       Not yet supported.


  C. Microsoft Windows Installation
     
       The OVAL Definition Interpreter can be installed and run on
       Microsoft Windows NT 4.0/2000/XP/Server 2003.

       Install the Definition Interpreter by running the installer
       executable - OVALdisetup.exe

       The installer is a self-extracting zip archive that prompts
       the user for an installation directory 
       ('C:\Program Files\OVAL\ovaldi\' by default)
       and installs the Definition Interpreter and its supporting
       files.

       Executables:
       ovaldi.exe - Definition Interpreter binary

       Libraries:
       xerces-c_2_6_0.dll - Xerces XML library
       pcre.dll - PCRE library

       Documentation:
       README.txt - This file
       terms.txt - License and Terms of Use
       version.txt - Definition Interpreter change log

       XML:
       definitions.xml - INTERIM and ACCEPTED OVAL definitions
			  (See "Obtaining Updated Data Files" below)

       XML Schema:
       oval-schema.xsd - Core OVAL Schema
       redhat-schema.xsd - Red Hat extensions to the Core Schema
       solaris-schema.xsd - Solaris extensions to the Core Schema
       windows-schema.xsd - Microsoft Windows extensions to the Core Schema

       system-characteristics-schema.xsd - Schema for raw configuration data 
					   collected by the Interpreter
       redhat-characteristics-schema.xsd - Red Hat extensions to the System
					   Characteristics Schema
       solaris-characteristics-schema.xsd - Solaris extensions to the System
					   Characteristics Schema
       windows-characteristics-schema.xsd - Microsoft Windows extensions to the
					    System Characteristics Schema

       oval-results-schema.xsd - Schema for the Interpreter Assessment results
       redhat-results-schema.xsd - Red Hat extensions to the Results Schema
       solaris-results-schema.xsd - Solaris extensions to the Results Schema
       windows-results-schema.xsd - Microsoft Windows extensions to the Results Schema


-- II -- USING THE INTERPRETER --

  A. Required Privileges -- IMPORTANT NOTE:

     In order to collect all of the system configuration data required
     to correctly evaluate OVAL Definitions, the Definition 
     Interpreter MUST BE RUN WITH ADMINISTRATOR/ROOT PRIVILEGES.

     Certain system data referenced by OVAL Definitions is only
     available to privileged accounts.  This includes information
     about running processes, and potentially registry key and file
     information (depending on local security settings).  While, it is 
     possible to run the Definition Interpreter as a non-privileged
     user, the results of the analysis may not convey the true state of
     the system.


  B. Data Protection -- IMPORTANT NOTE:

     The Definition Interpreter collects system configuration data
     only available to a user with Administrator/root access.  That
     data may be stored locally in a XML file.  In addition, the
     vulnerability status of the system is written to a file.  
     SINCE THIS IS SENSITIVE INFORMATION, IT IS STRONGLY RECOMMENDED
     THAT THE DEFINITION INTERPRETER DIRECTORY BE RESTRICTED TO 
     ADMINISTRATOR ACCESS ONLY.


  C. Obtaining The Latest OVAL Definition Data Files:

     OVAL Definitions are created and modified on a regular basis,
     therefore, it is advised that you check the OVAL Web Site
     before running the Interpreter, to ensure that you are using
     the most up-to-date Definitions.  This can be done by
     following the 'Download' link to the data files.  Make sure
     to note the MD5 signature of the data file, as it will be
     needed to execute the Interpreter.

     Additionally it is recommended that you join the 
     "OVAL-DATA-UPDATE-LIST."  This list provides subscribers with
     reports of new OVAL definitions, updates, and other detailed
     technical information regarding OVAL.  This list is intended for
     heavy technical users of OVAL, such as vulnerability database 
     maintainers, or those who require timely notification of new
     definitions.  Messages are sent when new OVAL data is available,
     which is approximately once per week.  To subscribe to the list,
     follow the 'Free Newsletters' link on the OVAL Web Site.


  D. Quick Usage Guide:

  1) As the Interpreter is only a reference implementation, it has
     purposefully been designed as solely a commmand-line utility.
     Therefore, to execute the Interpreter, you will first have to
     open a command window, and change to the Interpreter installation
     directory.

  2) If you have downloaded a newer data file than the one bundled with
     the Interpreter, move the new data file into the Interpreter installation
     directory, and rename it to 'definitions.xml'.

  3) Run the Interpreter, supplying the MD5 checksum of the data file as
     a command line option.

     > ovaldi MD5Hash

     After verifying the integrity of the data file using the MD5
     checksum, the XML Definition Interpreter will read the 'definitions.xml'
     file to determine what data to collect from the system, will analyze the
     collected data against the 'definitions.xml' file, and will report its
     findings.


  E. Advanced Usage:

     The Definition Interpreter accepts a number of command-line 
     options:

     Command Line: ovaldi [options] MD5Hash

     Options:
     -c <string> = Analyze and collect data for definitions of the specified 
                   class. 
                   DEFAULT="vulnerability"
     -d filename = Save collected system configuration data to XML file. 
                   DEFAULT="system-characteristics.xml"
     -h          = Show options available from the command line.
     -i filename = Use data from input Systems Characterstics file.
     -m          = Do not verify MD5 of the definitions xml file.
     -o filename = Path to the definitions xml file. DEFAULT="definitions.xml"
     -r filename = Save results to XMl file. DEFAULT="results.xml"
     -f          = Check for flawed software on disk only.
     -s <string> = Analyze and collect data for definitions of a certain status.
                   An ordered bitmap indicating which status to include. 
                   Ordering as follows:
        INCOMPLETE, INITIAL SUBMISSION, DRAFT, INTERIM, ACCEPTED, DEPRECIATED
                   DEFAULT=\"000110\" or INTERIM, ACCEPTED
     -v          = Print all information and error messages.
     -z          = Return md5 of current definitions xml file.

In more detail: 
     -c -- Specifies what class of definitions to analyze and collect data for.
           Possible class options are "vulnerability", "compliance", 
           "deprecated", and "patch"

     -d -- Specifies the pathname of the file to which collected configuration
           data is to be saved. This data is stored in the format defined by 
           the Systems Characteristics Schema. 

     -h -- Displays command line options.

     -i -- Specifies the pathname of a System Characteristics file that
           is to be used as the basis of the analysis.  In this mode,
           the Interpreter does not perform data collection on the
           local system, but relies upon the input file, which may
           have been generated on another system.

     -m -- Run without requiring an MD5 checksum.  Running the
           interpreter with this option DISABLES an important security
           feature.  In normal usage, a trusted checksum provided on the
           command line is used to verify the integrity of the OVAL
           Definitions file.

           Use of this option is recommended only when testing your own draft
           definitions before submitting them to the OVAL Community 
           Forum for public review.

     -o -- Specifies the pathname of the OVAL Definition file to use.
           If none is specified than the interpreter will default to
           "definitions.xml" in the Interpreter directory.

     -p -- Specifies the pathname of the oval mapping xml file to use.
           If none is specified than the interpreter will default to
           "mapping.xml" in the Interpreter directory.
           
     -r -- Specifies the pathname of the file to which analysis results
           are to be saved.  This data is stored according to the format
           defined by the OVAL Results Schema.  If none is specified 
           than the interpreter will default to "results.xml" in the 
           Interpreter directory.

     -f -- Only perform flawed software on disk tests if this flag is 
           present.  By default the Definition Interpreter normally
           checks for both flawed software on disk and misconfigurations.
           By using this flag vulnerabilities are reported if flawed
           software is found, regardless of the system's configuration.

     -s -- Only analyze and collect data for definitions of a certain status. 
           This option accepts a six character long binary string. Each 
           character represents the status in the order listed below. 
           A "1" indicates you want to include the status and a "0"
           indicates you do not want the status. 
           The order in which the bits map to the status type is listed here: 
           "INCOMPLETE","INITIAL SUBMISSION","DRAFT","INTERIM","ACCEPTED", 
           "DEPRECIATED" Example: "101010" indicates"INCOMPLETE","DRAFT", 
           and "ACCEPTED" The default setting is "000110" or "INTERIM" and 
           "ACCEPTED" status. All "1"s would include all status types, all 
           "0"s would include none.

     -v -- Verbose output.  Print all information and error message to the 
           console.

     -z -- Calculates and prints to the screen the MD5 checksum of the
           current data file (definitions.xml by default, or as specified by
           the -o option).  This can be used to manually compare the
           current file with the trusted checksum available from the 
           OVAL Web site.

     MD5Hash -- The MD5 checksum expected for the current data file
           (definitions.xml by default, or as specified by the -o option).
           The Interpreter calculates the actual checksum of the
           Data file, and compares it to this value provided on the
           command line, to verify the data file's integrity.  Checksums
           are available from the OVAL Web site.

           The checksum verification ensures that the data file has not
           been modified: that the OVAL definitions have not been 
           tampered with, or potentially malicious content added.
           Unless the -m option is specified, the MD5Hash is REQUIRED to
           run the Interpreter.


-- III -- INPUT AND OUTPUT --

The input and the output formats used by the Definition Interpreter are
defined by individual XML Schemas. The data collected about a system is considered
input and its format is defined by System Characteristics Schema.  The
detailed results generated by a system analysis are considered output and
their format is defined by the OVAL Results Schema.  These XML Schemas
have been provided to allow other applications to more easily implement 
their own system information collection utilities and manipulate the results
of an analysis for inclusion in other applications.

  A. Input

     The Definition Interpreter analysis engine accepts an XML data
     model in the format defined by the System Characteristics Schema
     (system-characteristics-schema.xsd).  This data model can be
     generated locally by the Interpreter's data collection engine, or
     can be provided at runtime using the -i command line option.

     If the data model is provided at runtime, the only requirement is
     that it be formatted according to the System Characteristics
     Schema.  The data can be gathered using a tool other than
     the Definition Interpreter, on another system, running a
     different operating system, but as long as the data is in the
     correct format, analysis can be performed.  What this means is,
     not only can one system be used to run the analysis for a number
     of systems, but data models can be altered/fabricated to conduct
     'what-if' scenarios.

  B. Output

     The Definition Interpreter provides detailed output from an
     analysis according to the OVAL Results Schema.  This output includes
     the outcome of individual tests, as well as each Definition as a whole.

     The OVAL Results Schema is provided to allow the results of an
     analysis to be utilized by other applications.  For example, an
     application could convert the detailed results to HTML for
     display on a Web site, or use the detailed results to determine
     what if any patches should be applied to a system.  As mentioned
     above, the -r command line option may be used to redirect the
     output to a location other than the default.

     NOTE: A sample stylesheet has been provided in the xml directory
     that will transform the results of an analysis into an HTML table.
     The file is named: xml/results_table.xsl


-- IV -- PCRE --

The Definition Interpreter uses the open source PCRE library.  The
binary was compiled with version 5.0 of the pcre library.  
From the PCRE Web site:

  "Regular expression support is provided by the PCRE library 
   package, which is open source software, written by Philip Hazel,
   and copyright by the University of Cambridge, England."

For more information about PCRE visit:
    http://www.pcre.org

To download the source code for PCRE, please use the following ftp
site:
    ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/


-- V -- XERCES --

The Definition Interpreter uses the open source Xerces library.  The
binary was compiled with version 2.6 of the xerces-c library.  From
the Xerces Web site:

  "This product includes software developed by the Apache Software
  Foundation (http://www.apache.org/)."

For more information about Xerces visit:
    http://xml.apache.org

The source code is also available at the above Web site.


-- VI -- TROUBLESHOOTING --

*********************************** 

Q:

I am trying to run the OVAL Definition Interpreter but all I get is a
message saying "You must supply the MD5 hash for the data file or use
the -m command to skip the MD5 check."

A:

The Definition Interpreter is set up to validate that the
Data file has not been tampered with by checking the MD5 hash (or 
checksum) generated from the data file on your computer with an MD5
hash provided by MITRE on the OVAL Web site.  In order to start the
OVAL Definition Interpreter you must provide this MD5 hash.  From the
command line, type the program name 'ovaldi.exe' then add a space and
type the MD5 hash value from the OVAL Web site.  For example:

    ovaldi.exe 897237212305b2d7a4dd5fa6b4e226fc

If you want to use some of the advanced option flags, place them
between the program name and the MD5 hash.  For example:

    ovaldi.exe -i myData.xml -s 897237212305b2d7a4dd5fa6b4e226fc

If you do not want to supply the MD5 hash and are confident that the
Data file on your computer has not been tampered with, you can supply
the -m flag to skip the MD5 check.  For example:

    ovaldi.exe -m

Be careful when using the -m option.  A data file that has been
tampered with can cause misleading results to be generated.  MITRE
recommends that you always supply a valid MD5 hash from the OVAL Web
site when using the Definition Interpreter.

*********************************** 
Q:

I ran the Definition Interpreter with the -v flag and I got a bunch 
of errors.  Should I worry about them?  The program seemed to run 
fine.

A:

Most of the messages produced when the -v flag is set are the result
of registry keys and files not existing on your system.  This kind of
message is informational, rather than an error.  In more detail:

An OVAL Definition may have tests to retrieve information about
specified objects (files, registry keys, etc).  On some systems, 
these objects simply do not exist, perhaps because a particular
application or software component is not installed.

For example, installed patches are determined by the existence of
certain registry keys.  If a patch is not installed, then the 
registry key will not exist.  When the Interpreter evaluates an OVAL 
definition, it attempts to collect information about this registry
key on the system.  If the key is not found, the patch is not
installed.  Since these missing objects are not really errors, they
are not normally reported to the user, but appear when the -v option
is specified.

Scan through the list of messages produced by the -v flag and look 
for errors that are not common.  These could signify something that
is working incorrectly.


-- VII -- REPORTING PROBLEMS --

To report a problem with the OVAL XML Definition Interpreter, please
send an email with a brief description of the problem, the version of
the Definition Interpreter, and the platform upon which the problem was
detected, to oval@mitre.org.  The version of the Definition Interpreter
can be found in a banner at the top of any output.
