   	

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

         OVAL XML Definition Interpreter

    Copyright (c) 2005 - The MITRE Corporation

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

The MITRE Corporation developed the Open Vulnerability and 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 configuration issues, and generate a list of
Common Vulnerabilities and Exposures (CVE) identifiers and/or OVAL
identifiers for those vulnerabilities and/or configuration issues 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/bsd_license.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
  VIII USEFUL LINKS


-- 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 have 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 Definition
	           Interpreter
       ovaldi - Definition Interpreter binary

       Libraries:
       libxerces-c.so.23.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_3_0.dll - Xerces XML 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 Data Files page on
     the OVAL Web Site before running the Interpreter to ensure
     that you are using the most up-to-date Definitions.  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" email 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 tool and service developers,
     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, go to the Free Newsletters page 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 command-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 Characteristics 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 For more information on 
     the uses of the results file look on the OVAL web site at:
     http://oval.mitre.org/about/faqs.html#f9
     


-- IV -- PCRE --

The Definition Interpreter uses the open source PCRE library.  The
binary was compiled with version 4.4 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.5 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 to oval@mitre.org with a brief description
of the problem, the version of the Definition Interpreter, and the
platform upon which the problem was detected.  The version of the
Definition Interpreter can be found in a banner at the top of any
output.

-- VIII  USEFUL LINKS --

OVAL Web site -- http://oval.mitre.org

Definition Interpreters -- http://oval.mitre.org/oval/download/interpreter.html

Data Files -- http://oval.mitre.org/oval/download/datafiles.html

Terms of Use -- http://oval.mitre.org/oval/termsofuse.html

CVE List -- http://cve.mitre.org

OVA-Data-Updates e-Newsletter -- http://oval.mitre.org/news/newsletters.html



----------------------------------------------------------
OVAL is sponsored by US-CERT at the U.S. Department of Homeland
Security. OVAL and the OVAL logo are trademarks of The MITRE
Corporation. Copyright 2005, The MITRE Corporation (www.mitre.org).
