The following is a description of the elements, types, and attributes that compose the core schema for encoding Open Vulnerability and Assessment Language (OVAL) Results. Each of the elements, types, and attributes that make up the Core Results Schema are described in detail and should provide the information necessary to understand what each object represents. This document is intended for developers and assumes some familiarity with XML. A high level description of the interaction between these objects is not outlined here.
The OVAL Schema is maintained by The MITRE Corporation and developed by the public OVAL Community. For more information, including how to get involved in the project and how to submit change requests, please visit the OVAL website at http://oval.mitre.org.
The oval_results element is the root of an OVAL Results Document. Its purpose is to bind together the four major sections of a results file - generator, directives, oval_definitions, and results - which are the children of the root element. It must contain exactly one generator section, one directives section, and one results section.
Child Elements Type MinOccurs MaxOccurs generator oval:GeneratorType 1 1 directives oval-res:DirectivesType 1 1 oval-def:oval_definitions n/a 0 1 results oval-res:ResultsType 1 1 ds:Signature n/a 0 1
The DirectivesType complex type presents flags describing what information has been included in the results file. There are six possible results (true, false, unknown, error, not evaluated, and not applicable) for an evaluation of an OVAL Definition. The directives state which of these results are being reported in the results file. For example, a results file dealing with vulnerabilities might only present to the user the definitions that returned a true result meaning the vulnerability exists. A different result file dealing with compliance definitions might want to report the results of all definitions except those not evaluated.
Child Elements Type MinOccurs MaxOccurs definition_true oval-res:DirectiveType 1 1 definition_false oval-res:DirectiveType 1 1 definition_unknown oval-res:DirectiveType 1 1 definition_error oval-res:DirectiveType 1 1 definition_not_evaluated oval-res:DirectiveType 1 1 definition_not_applicable oval-res:DirectiveType 1 1
Each directive determines whether or not certain results are included in the results file. The required reported attribute controls this by providing a true or false for the specific directive. The optional content attribute controls how much information about the specific result is provided. For example, thin content would only be the id of the definition and the result, while a full content set would be the definition id with the result along with results for all the individual tests and extended definitions. Please refer to the ContentEnumeration for details about the different content options.
Attributes:
- reported xsd:boolean (required) - content oval-res:ContentEnumeration (optional -- default='full')
The ResultsType complex type is a container for one or more system elements. Each system element defines the results associated with an individual system. Please refer to the description of SystemType for more information about an individual system element.
Child Elements Type MinOccurs MaxOccurs system oval-res:SystemType 1 unbounded
The SystemType complex type holds the evaluation results of the definitions and tests, as well as a copy of the OVAL System Characteristics used to perform the evaluation. The definitions section holds the results of the definitions and the tests section holds the results of the tests. The oval_system_characteristics section is a copy of the system characteristics file used to perform the evaluation of the OVAL Definitions. Note that the oval_definitions part of the system characteristics file should be left out as the definition information has already been included at the top of the results file.
Child Elements Type MinOccurs MaxOccurs definitions oval-res:DefinitionsType 0 1 tests oval-res:TestsType 0 1 oval-sc:oval_system_characteristics n/a 1 1
The DefinitionsType complex type is a container for one or more definition elements. Each definition element holds the result of the evaluation of an OVAL Definition. Please refer to the description of DefinitionType for more information about an individual definition element.
Child Elements Type MinOccurs MaxOccurs definition oval-res:DefinitionType 1 unbounded
The DefinitionType complex type holds the result of the evaluation of an OVAL Definition. The message element holds an error message or some other string that the analysis engine wishes to pass along. In addition, the optional criteria element provides the results of the individual pieces of the criteria. Please refer to the description of the CriteriaType for more information.
The required definition_id attribute is the OVAL id of the definition. The required version attribute is the specific version of the OVAL Definition used during analysis. The optional variable_instance attribute is a unique id that differentiates each unique instance of a definition. Capabilities that use OVAL may reference the same definition multiple times and provide different sets of variable values each time the definition is referenced. This will result in multiple instances of a definition being included in the OVAL Results file (definitions that do not use variables can only have one unique instance). The inclusion of a unique instance identifier will allow the OVAL Results file to report the correct item associated with an object for each combination of supplied values. The required result attribute holds the result of the evaluation. Please refer to the description of the ResultEnumeration for details about the different result values.
Attributes:
- definition_id oval:DefinitionIDPattern (required) - version xsd:nonNegativeInteger (required) - variable_instance xsd:nonNegativeInteger (optional -- default='1') - result oval-res:ResultEnumeration (required)
Child Elements Type MinOccurs MaxOccurs message oval:MessageType 0 unbounded criteria oval-res:CriteriaType 0 1
The CriteriaType complex type describes the high level container for all the tests and represents the meat of the definition. Each criteria can contain other criteria elements in a recursive structure allowing complex logical trees to be constructed. Each referenced test is represented by a criterion element. Please refer to the description of the CriterionType for more information about and individual criterion element. The optional extend_definition element allows existing definitions to be included in the criteria. Refer to the description of the ExtendDefinitionType for more information.
The required operator attribute provides the logical operator that binds the different statements inside a criteria together. The optional negate attribute signifies that the result of an extended definition should be negated during analysis. For example, consider a definition that evaluates TRUE if a certain software is installed. By negating the definition, it now evaluates to TRUE if the software is NOT installed. The required result attribute holds the result of the evaluation of the criteria. Note that this would be after any negation operation has been applied. Please refer to the description of the ResultEnumeration for details about the different result values.
Attributes:
- operator oval:OperatorEnumeration (required) - negate xsd:boolean (optional -- default='false') - result oval-res:ResultEnumeration (required)
Child Elements Type MinOccurs MaxOccurs criteria oval-res:CriteriaType 1 1 criterion oval-res:CriterionType 1 1 extend_definition oval-res:ExtendDefinitionType 1 1
The CriterionType complex type identifies a specific test that is included in the definition's criteria.
The required test_id attribute is the actual id of the included test. The required version attribute is the specific version of the OVAL Test used during analysis. The optional variable_instance attribute differentiates between unique instances of a test. This can happen when a test includes a variable reference and different values for that variable are used by different definitions. The optional negate attribute signifies that the result of an individual test should be negated during analysis. For example, consider a test that evaluates to TRUE if a specific patch is installed. By negating this test, it now evaluates to TRUE if the patch is NOT installed. The required result attribute holds the result of the evaluation. Please refer to the description of the ResultEnumeration for details about the different result values.
Attributes:
- test_ref oval:TestIDPattern (required) - version xsd:nonNegativeInteger (required) - variable_instance xsd:nonNegativeInteger (optional -- default='1') - negate xsd:boolean (optional -- default='false') - result oval-res:ResultEnumeration (required)
The ExtendDefinitionType complex type identifies a specific definition that has been extended by the criteria.
The required definition_ref attribute is the actual id of the extended definition. The required version attribute is the specific version of the OVAL Definition used during analysis. The optional variable_instance identifier is a unique id that differentiates each unique instance of a definition in the OVAL Results file based on the combination of variable values used. Capabilities that use OVAL may reference the same definition multiple times and provide different sets of variable values each time the definition is referenced. This will result in multiple instances of a definition being included in the OVAL Results file (definitions that do not use variables can only have one unique instance). The inclusion of a unique instance identifier will allow the OVAL Results file to report the correct item associated with an object for each combination of supplied values. The optional negate attribute signifies that the result of an extended definition should be negated during analysis. For example, consider a definition that evaluates TRUE if certain software is installed. By negating the definition, it now evaluates to TRUE if the software is NOT installed. The required result attribute holds the result of the evaluation. Please refer to the description of the ResultEnumeration for details about the different result values.
Attributes:
- definition_ref oval:DefinitionIDPattern (required) - version xsd:nonNegativeInteger (required) - variable_instance xsd:nonNegativeInteger (optional -- default='1') - negate xsd:boolean (optional -- default='false') - result oval-res:ResultEnumeration (required)
The TestsType complex type is a container for one or more test elements. Each test element holds the result of the evaluation of an OVAL Test. Please refer to the description of TestType for more information about an individual test element.
Child Elements Type MinOccurs MaxOccurs test oval-res:TestType 1 unbounded
The TestType complex type provides a reference to every item that matched the object section of the original test as well as providing an overall test result based on those items. The optional message element holds an error message or some other string that the analysis engine wishes to pass along. The optional tested_variable elements hold the value of each variable used by the test during evaluation. This includes the values used in both OVAL Objects and OVAL States. If a variable represents an array of values, then multiple tested_variable elements would exist with the same variable_id attribute. Please refer to the description of TestedVariableType for more information.
The required test_id attribute identifies the test, and must conform to the format specified by the TestIDPattern simple type. The required version attribute is the specific version of the OVAL Test used during analysis. The optional variable_instance attribute differentiates between unique instances of a test. This can happen when a test includes a variable reference and different values for that variable are used by different definitions.
The optional check_existence attribute is used in determining the overall result by signifying how many matching items must exist. The optional check attribute is also used in determining the overall result by specifying how many of the matching items must meet the supplied OVAL State. For example, should the test check that all files match a specified version or that at least one file matches the specified version? If the test does not contain any references to OVAL States, then the check attribute has no meaning and can be ignored during evaluation.
The optional state_operator attribute provides the logical operator that combines the evaluation results from each referenced state. The combined state evaluation result for all items is then considered based on the specified check attribute value to determine the overall state evaluation result. If the test does not contain any references to OVAL States, then the state_operator attribute has no meaning and can be ignored during evaluation. The valid values for the check_existence, check, and state_operator attributes are explained in the simple type declarations found in the oval-common-schema.
The required result attribute holds the result of the evaluation after all referenced items have been examined and the various evaluation control attributes have been applied. Please refer to the description of the ResultEnumeration for details about the different result values. The overall result of the OVAL Test is determined by the results of each matching item and the different check attributes. If you are using an OVAL System Characteristics file, then the following rules apply: If a collected_object is not found the result for the OVAL Test should be "unknown". When the flag attribute of the collected_object is "error", the result for the OVAL Test should be set to "error". When the flag attribute is "complete", the result of the OVAL Test is determined by first evaluating the check_existence attribute on the OVAL Test and then evaluating the check attribute. The check attribute only needs to be considered if the result of evaluating the check_existence attribute is "true". When the flag attribute is "does not exist", the result of the OVAL Test is determined by examining the check_existence attribute's value and if the check_existence attribute is "none_exist" or "any_exist" the OVAL Test should evaluate to "true", for all other values of the check_existence attribute the OVAL Test should evaluate to "false". When the flag attribute is "not collected" the result of the OVAL Test should be set to "unknown". When the flag attribute is "not applicable" the result for the OVAL Test should be set to "not applicable". When the flag attribute is "incomplete", it may not be possible to determine a result other than "unknown" for the OVAL Test. However, in some cases, when the flag attribute is "incomplete", it will be possible to determine a result. These cases are: 1) when the check_existence attribute on a test is set to "none_exist" and the collected object has 1 or more item references with a status of "exists", a result of "false" should be reported; 2) when the check_existence attribute is set to "only_one_exists", the collected object has more than 1 item reference with a status of "exists", a result of "false" should be reported; 3) if after evaluating the check_existence attribute a non "true" result has not been determined, the check attribute must be considered as follows: 3a) if the check attribute evaluation results in "false", then the OVAL Test result should be set to "false"; 3b) if the check attribute is set to "at_least_one_satisfies" and its evaluation results in "true", the OVAL Test result should be set to "true". For all other cases when the collected_object flag is "incomplete", the OVAL Test result should be set to "unknown".
Attributes:
- test_id oval:TestIDPattern (required) - version xsd:nonNegativeInteger (required) - variable_instance xsd:nonNegativeInteger (optional -- default='1') - check_existence oval:ExistenceEnumeration (optional -- default='at_least_one_exists') - check oval:CheckEnumeration (required) - state_operator oval:OperatorEnumeration (optional -- default='AND') - result oval-res:ResultEnumeration (required)
Child Elements Type MinOccurs MaxOccurs message oval:MessageType 0 unbounded tested_item oval-res:TestedItemType 0 unbounded tested_variable oval-res:TestedVariableType 0 unbounded
The TestedItemType complex type holds a reference to a system characteristic item that matched the object specified in a test. Details of the item can be found in the oval_system_characteristics section of the OVAL Results file by using the required item_id. The optional message element holds an error message or some other message that the analysis engine wishes to pass along. The required result attribute holds the result of the evaluation of the individual item as it relates to the state specified by the test. If the test did not include a state reference then the result attribute will be set to 'not evaluated'. Please refer to the description of the ResultEnumeration for details about the different result values.
Attributes:
- item_id oval:ItemIDPattern (required) - result oval-res:ResultEnumeration (required)
Child Elements Type MinOccurs MaxOccurs message oval:MessageType 0 unbounded
The TestedVariableType complex type holds the value to a variable used during the evaluation of a test. Of special importance are the values of any external variables used since these values are not captured in either the definition or system characteristic files. If a variable is represented by an array of values, then multiple elements of TestedVariableType, each with the same variable_id attribute, would exist. The required variable_id attribute is the unique id of the variable that was used.
Attributes:
- variable_id oval:VariableIDPattern (required)
Simple Content xsd:anySimpleType
The ContentEnumeration defines the valid values for the directives controlling the amount of expected depth found in the results file. Each directive specified at the top of an OVAL Results file defines how much information should be included in the document for each of the different result types. The amount of content that is expected with each value is defined by Schematron statements embedded throughout the OVAL Results Schema. Currently, the enumeration defines two values: thin and full. Please refer to the documentation of each individual value of this enumeration for more information about what each means.
Value Description thin
A value of 'thin' means only the minimal amount of information will be provided. This is the id associated with an evaluated OVAL Definition and the result of the evaluation. The criteria child element of a definition should not be present when providing thin results. In addition, system characteristic information for the objects used by the given definition should not be presented.
full
A value of 'full' means that very detailed information will be provided allowing in-depth reports to be generated from the results. In addition to the results of the evaluated definition, the results of all extended definitions and tests included in the criteria as well as the actual information collected off the system must be presented.
The ResultEnumeration defines the acceptable result values for the DefinitionType, CriteriaType, CriterionType, ExtendDefinitionType, TestType, and TestedItemType constructs.
Value Description true
When evaluating a definition or test, a result value of 'true' means that the characteristics being evaluated match the information represented in the system characteristic file. When evaluating a tested_item, and a state exists, a result value of 'true' indicates that the item matches the state.
false
When evaluating a definition or test, a result value of 'false' means that the characteristics being evaluated do not match the information represented in the system characteristic file. When evaluating a tested_item, and a state exists, a result value of 'false' indicates that the item does not match the state.
unknown
When evaluating a definition or test, a result value of 'unknown' means that the characteristics being evaluated cannot be found in the system characteristic file (or the characteristics can be found but collected object flag is 'not collected'). For example, assume that a definition tests a file, but data pertaining to that file cannot be found and is not recorded in the system characteristics file. The lack of an item (in the system_data section) for this file in the system characteristics file means that no attempt was made to collect information about the file. In this situation, there is now way of knowing what the result would be if the file was collected. Note that finding a collected_object element in the system characteristic file is not the same as finding a matching element of the system. When evaluating an OVAL Test, the lack of a matching object on a system (for example, file not found) does not cause a result of unknown since an test considers both the state of an item and its existence. In this case the test result would be based on the existence check specified by the check_existence attribute on the test. When evaluating a tested_item, and a state exists, a result value of 'unknown' indicates that it could not be determined whether or not the item and state match. For example, if a registry_object with a hive equal to HKEY_LOCAL_MACHINE, a key with the xsi:nil attribute set to 'true', and a name with the xsi:nil attribute set to 'true' was collected and compared against a registry_state with key entity equal to 'SOFTWARE', the tested_item result would be 'unknown' because an assertion of whether or not the item matches the state could not be determined since the key entity of the item was not collected.
error
When evaluating a definition or test, a result value of 'error' means that the characteristics being evaluated exist in the system characteristic file but there was an error either collecting information or in performing analysis. For example, if there was an error returned by an api when trying to determine if an object exists on a system. Another example would be: xsi:nil might be set on an object entity, but then the entity is compared to a state entity with a value, thus producing an error. When evaluating a tested_item, and a state exists, a result value of 'error' indicates that there was either an error collecting the item or there was an error analyzing the item against the state. For example, a tested_item will receive a result value of 'error' if an attempt is made to compare a state entity against an item entity that has a status of 'error'.
not evaluated
When evaluating a definition or test, a result value of 'not evaluated' means that a choice was made not to evaluate the given definition or test. The actual result is not known since if evaluation had occurred the result could have been either true or false. When evaluating a tested_item, a result value of 'not evaluated' indicates that a state was not specified and is equivalent to an existence check.
not applicable
When evaluating a definition or test, a result value of 'not applicable' means that the definition or test being evaluated is not valid on the given platform. For example, trying to collect Linux RPM information on a Windows system. Another example would be in trying to collect RPM information on a linux system that does not have the RPM packaging system installed.