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

             OVAL Query Interpreter

              for Microsoft Windows

    Copyright (c) 2003 - The MITRE Corporation

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

The MITRE Corporation developed this Query Interpreter to demonstrate
the usability of OVAL queries.  The interpreter is a freely available
reference implementation of the Open Vulnerability Assessment Language
(OVAL), able to collect all information from a computer necessary to
process the OVAL queries for that platform, and then evaluate those
queries.  The Query Interpreter accomplishes this by instantiating the
OVAL Schema in an SQLite database; populating this schema by
collecting information about registry keys, process information, etc.;
and evaluating the queries against this schema.  The interpreter will
then provide you with a list of the CVE identifiers determined by OVAL
to be present on the system.

You may download the interpreter to any computer you wish, and as many
computers as you wish.  The download consists of the OVAL Schema,
insert statements, and all ACCEPTED and INTERIM queries for a
supported platform.

BY USING THE QUERY INTERPRETER, YOU SIGNIFY YOUR ACCEPTANCE OF THE
TERMS AND CONDITIONS USE.  IF YOU DO NOT AGREE TO THESE TERMS, DO NOT
USE THE INTERPRETER.  See the terms.txt file included with the
interpreter, or http://oval.mitre.org/oval/termsofuse.html.


-- 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 Datafiles
      D. Quick Usage Guide
      E. Advanced Usage
  III SQLite
  IV  TROUBLESHOOTING
  V   REPORTING PROBLEMS

-- I -- INSTALLATION --

Download the appropriate installation files from the OVAL Web site.

  A. Red Hat Installation

       The OVAL Query Interpreter is capable of running on Red
       Hat Linux 9 and Red Hat Enterprise Linux 3.  To install the
       Query Interpreter, download and install the RPM file,
       ovalqi-1.0.0-1.0.i386.rpm, which can be found on the OVAL
       Web site at:

       http://oval.mitre.org/oval/interpreter.html

       Install the RPM simply by running the following command:

       # rpm -ivh ovalqi-1.0.0-1.0.i386.rpm

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

       ovalqi.sh			  -- Script to run ovalqi with 
					     good arguments.  RUN THIS!
       ovalqi                             -- Query Interpreter binary
       readme.txt                         -- This file
       terms.txt                          -- License and Terms of Use
       version.txt                        -- Explains the changes that were 
                                             made in each new version of the
                                             Query Interpreter
       definitions.xml                    -- Red Hat INTERIM and ACCEPTED
                                             OVAL queries (See "Obtaining
                                             Updated Data Files" below)
       libsqlite.so.0.8.6                 -- The SQLite database engine
					     See http://www.sqlite.org/

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

       To run the query interpreter, run:

       # /usr/sbin/ovalqi.sh

       Results will be output to the screen; detailed results and related
       data also can be found in /var/log/ovalqi.
		



  B. Solaris Installation

       Not yet supported.


  C. Windows Installation

       The OVAL Query Interpreter is capable of running on 
       Windows NT 4.0, Windows 2000, Windows 2003, and Windows XP.
       To install the Query Interpreter run the installation
       program 'OVALqisetup.exe' which can be downloaded from the
       OVAL Web site at:

       http://oval.mitre.org/oval/interpreter.html

       This is a self-extracting zip archive that prompts the user
       for an installation directory 
       ('C:\Program Files\OVAL\ovalqi\' by default)
       and installs the Query Interpreter and its supporting files.
       They are:

       ovalqi.exe       -- The Query Interpreter binary
       readme.txt       -- This file
       terms.txt        -- License and Terms of Use
       version.txt      -- Explains the changes that were made in 
                           each new version of the Query Interpreter
       definitions.sql  -- Schema, Insert statements, ACCEPTED and
                           INTERIM OVAL queries for Windows
       sqlite.dll       -- The SQLite database engine
                           See http://www.sqlite.org/


-- II -- USING THE INTERPRETER --

The OVAL Query Interpreter is a command-line utility.  To run the
interpreter, first open a command window in the installation
directory.

  A. Required Privileges -- IMPORTANT NOTE:

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

     Certain system data included in the OVAL Schema and referenced by
     OVAL queries is only available to privileged processes.  This
     includes information about running processes, and potentially
     registry key and file information (depending on local security
     settings).  It is possible to run the Query Interpreter as a
     non-privileged user, but it may be unable to correctly evaluate
     the vulnerability status of the computer.

     IF THE QUERY INTERPRETER IS RUN AS NON-ADMINISTRATOR, QUERY
     RESULTS MAY NOT BE ACCURATE.


  B. Data Protection -- IMPORTANT NOTE:

     The Query Interpreter collects system configuration data only
     available to Administrator.  That data is stored locally in a
     database file.  In addition, the vulnerability status of the
     system can optionally be written to a file.  SINCE THIS IS
     SENSITIVE INFORMATION, IT IS STRONGLY RECOMMENDED THAT THE QUERY
     INTERPRETER FOLDER BE RESTRICTED TO ADMINISTRATOR ACCESS ONLY.


  C. Obtaining Updated Datafiles:

     Since OVAL queries are produced and modified often, the datafile
     contained in the Query Interpreter installer may not be the most
     recent.  Up-to-date datafiles and their checksums are available
     on the OVAL Web site at:

     http://oval.mitre.org/oval/download/datafiles.html
     
     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
     see:

     http://oval.mitre.org/news/newsletters.html

  D. Quick Usage Guide:

     Run the interpreter, supplying the MD5 checksum:

     C:\Program Files\OVAL> ovalqi MD5Hash

     Linux:
     /usr/sbin/ovalqi.sh MD5Hash

     where "MD5Hash" is the datafile checksum obtained in 2) above.

     After verifying the integrity of the datafile using the MD5
     checksum, for each OVAL query in the file the interpreter will
     print to the screen whether the vulnerability is present on the
     system.


  E. Advanced Usage:

     The Query Interpreter accepts a number of command-line options which
     work under both Windows and Linux:

     C:\Program Files\Oval>ovalqi -h

     Command Line: > ovalqi [option] MD5Hash

     Options:
        -d <string> = save data to the specified SQLite database file DEFAULT="data.slt"
        -h          = show options available from command line
        -i <string> = use data from input SQLite database file
        -m          = do not verify the *.sql file with an MD5 hash
        -o <string> = path to the *.sql file
        -r <string> = save results in a HTML file DEFALUT="results.html"
        -v          = print all information and error messages
        -z          = return md5 of current definitions.sql

     In detail:

     -d -- Specifies the pathname of the SQLite database file to create
           which stores system data under the OVAL Schema, and against
           which OVAL queries are evaluated.  The default is data.slt.
           See Section III "SQLite" below for more information.

     -h -- Displays usage synopsis.

     -i -- Specifies the pathname of an input SQLite database file to be
           used for analysis. The Query Interpreter optionally allows a 
           user to provide a populated OVAL database for analysis.  It is 
           possible to take a database file from another system and have
           it analyzed.  If this option is used a data will not be 
           collected on the local system. Only the data in the provided
           input database will be analyzed. The schema version of the OVAL
           schema used in the input database must match the schema version
           of the definitions.sql file being used for analysis.  No default.

     -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 contents of the datafile,
           which ensures the file has not been tampered with.

           The -m option is only recommended for testing your own draft
           queries before submitting them to the OVAL Community Forum for
           public review.

     -o -- Specifies the pathname of the definitions file to use.  Query
           Interpreter definitions files contain the OVAL Schema, insert
           statements, and INTERIM and ACCEPTED queries for a platform.
           The default is definitions.sql.

     -r -- Specifies the pathname of the HTML results file.  The default
           is results.html

     -v -- Verbose output, including all information and error messages.

     -z -- Calculates and prints to the screen the MD5 checksum of the
           current datafile (definitions.sql 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 datafile
           (definitions.sql by default, or as specified by the -o option).
           The interpreter calculates the actual checksum of the
           datafile, and compares it to this value provided on the
           command line, to verify the datafile's integrity.  Checksums
           are available from the OVAL Web site at:

           http://oval.mitre.org/oval/download/datafiles.html

           The checksum verification ensures that the datafile has not
           been modified: that the OVAL queries 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 -- SQLite --

The OVAL Query Interpreter uses the open source SQLite.  From the
SQLite Web site:

  "SQLite is a C library that implements an embeddable SQL database
  engine...SQLite is not a client library used to connect to a big
  database server.  SQLite is the server.  The SQLite library reads
  and writes directly to and from the database files on disk."

By default, the database file created by the OVAL Query Interpreter is
called 'data.slt'.

For more information about SQLite, or to download the source code for
the database engine, please visit the SQLite Web site at
www.sqlite.org.

-- IV -- TROUBLESHOOTING --

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

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

    A:

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

    ovalqi 897237212305b2d7a4dd5fa6b4e226fc

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

    ovalqi -i results.html -v 897237212305b2d7a4dd5fa6b4e226fc

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

    ovalqi -m

Be careful when using the -m option.  A datafile 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 OVAL Query Interpreter.

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

I ran the OVAL Query 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:

The datafile contains a number of INSERT statements that tell the OVAL
Query Interpreter 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 query, it
searches the database for information about this registry key.  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.

-- V -- REPORTING PROBLEMS --

To report a problem with the OVAL Query Interpreter, please send an
email with a brief description of the problem to oval@mitre.org.
Include the platform the interpreter was run on, and the version of
the Query Interpreter and datafile.
