A schema to structure the gathering and reporting of system information. Approved for Public Release; Distribution Unlimited. Case Number 09-0183 (c)2009 The MITRE Corporation. All rights reserved. Root element of the Open Checklist Reporting Language (OCRL). May hold any number of individual report definitions Each report definition must have its own unique id field within a given file Denotes an individual report, with its own set of data sources, formatting and instructions. A single ReportDefintion block will be responsible for the creation of a single output report file (for offline reports). Represents the name of the file to which an offline report should be written. The id of this report definition, for use when referencing by external tools or files. The id must be unique within each ReportDefinitions file, but need not be globally unique. Instructions to the reader of the report on how the report's contents should be evaluated in order to determine compliance with the recommendation. The text of the recommendation for which the report is generated. The report should provide some or all of the information necessary for an administrator to make a determination as to whether the recommendation has been followed. The title of this report. In most tool implementations, this would appear at the top of the report output. Indicate whether this is an online or offline report. The different ways to display a report. Each data source's id must be unique within its ReportDefintion so that it can be referenced by Select elements in the Reporting secition The datasourceid attribute of Select statements must refer to the id of some data source. This element contains a complete list of all the data sources that feed the report generation. Data sources represent information gathered from a single source. The contents of a data source are subdivided into "instances" which represent logical groupings of data. Each instance is made of a number of "properties", which are simply name-value pairs. Instances within a data source may all contain properties with the same name but an individual instance may not. This structuring of a data source into instances and properties is used when formatting the report. Abstract class that is the root of all data source types. The id of the data source. This is used to identify a data source in the Reporting section. This is the only data common to all data sources Elements used to define how to recognized Instances and Properties in a parsed data source such as a File or Executable data source. Holds definitions of Instances that may be reused in InstanceRef elements Declare the context in which Instances might be found in a file. Must include at least one instance, either through direct definition or through references Make sure that all InstanceRefs in this segment refer to some other Instance in the InstanceDefs segment Make sure all Instance classid values are unique here Data source for a file. This describes not only which file to read but how to break the file up into logical blocks (instances) and how to extract items of interest (properties) from these blocks. Holds the name and directory of the file that should be parsed for this data source Data source to execute some command-line application and parse the result. The result is parsed just as a file would, using Instance elements to identify logical blocks and Property elements to extract specific values. Specify the name of the executable to run. It is assumed that the executable writes its results to standard output. If this is not the case, the author will need to add parameters to pipe output to the standard output interface. Auguments passed to the executable. If no arguments elements are present, then the executable is called without arguments. Must include at least one instance, either through direct definition or through references. Used to organize the command's output just as with a file. Represents either the definition of an Instance element or an InstanceRef that refers to a defined instance If true, the regular expression matching will be case insensitive. Otherwise, patterns are case sensitive. An Instance element is used to explicitly identify and record structure within a file data source. (Other types of data sources may have their instances defined implicitly.) The Instance expects to identify a contiguous block of text within a file and extract its properties from this block. It does this by identifying where the block starts and ends and using child Property elements to identify how to locate where to extract property values. Instances may also define sub-instances, which identify logical blocks of text within a parent block. Contains a regular expression that identifies the starting line of a block of text that represents an instance within a file. (This corresponds to line number 0 for the Line element of a Property.) If absent, this instance will start at the beginning of the parent Instance (or the beginning of the source file if no parent Instance is defined) Contains a regular expression that identifies the last line of a block of text that represents an instance within a file. If absent, an instance is assumed to end 1) when the end of the file is reached or 2) when the pattern given in the begin attribute of this Instance definition is encountered again (in which case the tool would start gathering data for the new instance from that point), 3) when the begin or end pattern of this instance's parent Instance is encountered, 4) when the begin or end pattern of this instance's grandparent Instance is encountered, etc. The body of an Instance may contain any number of Property and child Instance definitions. The order in which these appear does not affect processing. May include child instances, either through direct definition or through references Defines how to identify and extract properties of this instance from the text. Properties are identified by line number and/or regular expression. Note that it is possible that the conditions identifying a given property may never be met within an instance's block of text (a regular expression may never match) in which case the named property will not be included in that particular instance. Note also that it is permissible for multiple Properties in an Instance to match on the same line (usually capturing different parts of that line). The Property element may use a Line element, a PatternMatch element, or both to identify from the text to extract as the property's value. Sets the name of this property. This name will be used to identify the property within the Reporting section This defines value for a special property of an instance named "classid". All instances that are defined using the same Instance element will have the same value for their classid property. This allows authors who define multiple types of instances within a file to identify which instance definition was used for a given instance in a data source. Note that while the begin values of Instance definitions in a given generation must be different, the begin values of child and parent Instances may be identical, in which case context will determine which of these instances is collected. Within any given Instance definition, all the Property elements must have unique names. (Note that it is perfectly valid for different Instance definitions to reuse Property names. Specifies the line number on from which to extract this property's value. If it appears alone, the text of the entire line becomes the value of this property. If a regular expression is also used, the regular expression will be applied and, if it matches, the regular expression will determine what part of the line of text will become the value of this property. Specifies that any text within the instance block that matches the pattern contains a value for this property. If the regular expression contains a capture block (un-escaped parenthesis) then the value of the first capture block becomes the value of the property. If the regular expression matches but contains no capture block, the text of the entire matching line becomes the value of this property. A reference to a pre-defined Instance element. Identifies the class id of the target Instance definition. Data source for a WMI query. The WMI query return will be structured into zero or more instances, each with zero or more properties automatically so there is no need to structure them here. The namespace target of the WMI query Allows the user to specify a full query string for the WMI query Instead of providing the full WMI query in one shot users may describe the query piecemeal. The resulting query will look like: "SELECT _properties_ FROM _class_ WHERE _where_clause_" Specify the class from which the properties will be selected. (SELECT _properties_ FROM _class_ ...) Specify the properties to select in the query. (SELECT _property_ FROM...) Multiple Property elements may be specified in which case all the listed properties will be selected. If no Property elements are present, the query will request all properties (SELECT * FROM...) Optional element to include a WHERE qualifier in the query. If present, the contents of this element will appear after a WHERE in the query to the WMI provider (SELECT _properties_ FROM _class_ WHERE _where_clause_). If absent, no WHERE clause will be added to the query Data source for extracting information via OVAL. Specifies an OVAL object id. (Note - not a definition or a test.) The result will be returned as one instance per system data item from the OVAL SystemCharateristics schema. The properties of the instances correspond to the elements in item substitution group children from the the various platforms SystemCharacteristics schems, where the property name corresponds to the element name and the property value corresponds to the value (body) of this element. Holds the ID of an OVAL object. The filename attribute provides a specific path and file from where the identified OVAL object should be located. Optional element to specify the name of a preexisting OVAL SystemCharacteristics file from which the relevant information can be read. Convenience type for specifying a file and path. Optional specification of the directory in which to locate the given file. If absent, assume the file will be in the current working directory. The reporting section contains structures that describe how to organize the information collected in the DataSources section as well as addition free text to help clarify the meanings of report elements. The body of the Reporting element may contain any number of Select and Text elements in any order. Child elements at this top level of the Reporting body will only be evaluated once. All the variables defined within a Reporting section should have unique names relative to each other. Each data source is composed of one or more instances. These instances represent collections of related data. A Select element in the reporting section identifies a data source, which subset of its instances should be processed and, through its child elements, how the properties of each chosen instance in the data source should be presented to the user. From a programmatic viewpoint, a Select could be viewed like a for-each loop where, for each chosen instance in the given data source, the contained elements of the Select will be applied to that instance. If seven Instances are selected from a given data source, then the child elements of the Select would be applied seven times, once to each of the instances. Select elements may be nested within each other in, which can be viewed programmatically as a pair of nested for-each loops, where the inner loop (inner Select) would be processed in its entirety (choosing a set of Instances from a given data source and applying its child elements to each instance in turn) for each iteration of the outer loop. Select elements may also have a Qualifier as their first child. The conditions in the qualifier are further use to restrict the instances over which the Select element iterates as only instances for which the conditions of the qualifier were met would be among the list of iterated instances. The children of a Select may start with an optional Qualifier or equivalent element. To make the syntax of a Select a little more familiar to those familiar with SQL, the schema allows the use of Where as a synonym for Qualifier within a Select. (This substitution is not allowed elsewhere.) After the optional qualifier, a Select may contain any number of Text, Select, or Item children in any order. These child elements will be evaluated in the order in which they appear. Identifies a datasource within this ReportDefinition by its id. The Select element will then process all the instances of this data source, as filtered by the "instances" attribute. The datasourceid attribute may be absent ONLY in a Select element that is itself a child of another Select element. When the datasourceid attribute is absent, this indicates that this Select element iterates over the child instances of the "current instance" of the outer Select element. (Recall that Select blocks can be viewed like a for-each, where the Select applies its child elements to each of its data source's instances in turn. As such, each time a child Select is reached, the parent Select would be processing one of its data source's instances. It is the "current instance" being processed in each iteration through the parent Select's instances that would be checked for child instances each time a child Select with no datasourceid is encountered. Provides an initial way to filter the instances of a data source. Possible values are "all", indicating that all instances should be considered, "first", indicating that only the first instance in the data source should be considered, and "last", indicating that only the last instance in the data source should be considered. Note that this attribute only performs a very rough level of filtering. For more precise filtering, a Qualifier element should be used. If a Qualifier element is present, any filtering dictated by the instances attribute would occur first with the Qualifier element further refining the selection. The supported ways to restrict the which instances in a data source are processed by a Select element. Used by the "instances" attribute of the Select element. Used to insert raw text within the output of a Report. Within each Select element, the given text will appear at the location it appears within the Select element's children once for each instance processed by the Select. If an Instance element corresponds to an instance within a data source, then an Item element corresponds to a property within an instance. All Item elements must appear within a Select element and must include a name attribute that identifies a property within the "current instance" of the Select's data source. (Recall that the Select is like a for-each loop with each iteration corresponding to a single instance within the data source. As such, an Item element would be processed once for each of the chosen instances in a Select.) If there is no property within the current instance that matches the given name, the Item is skipped without further processing. If there is a property with the given name, then this property will be included in the report. The exact appearance of how this property is included in a report will vary between interpreters, but in general will look something like: "property_name = property_value". Note that an Item element may contain a Qualifier element in which case the Item would be skipped if the named property did not exist within the current instance OR if the condition in the Qualifier evaluated to false. The name of the property in some the "current instance" of the enclosing Select element's data source. If present, the value of the property named in this item will be associated with a variable whose name is the value of this attribute. This feature can be useful if a particular property must be part of the output of a child Select since Item elements only refer to properties of their own instances and not the instances of a parent Select. However, variables are globally visible within the Select element (and its children) where they are defined, so by setting a variable equal to the value of a particular property, that property's values becomes usable within child Select. If true, then this Item does not result in the display of the named property's value and does not leave any visible mark on the output (online or offline). This attribute is primarily used in conjunction with the setvariable attribute, allowing a variable to be defined and set without causing the Item that sets the variable to appear in the report at the location the variable is set. A Qualifier defines a condition to be evaluated. A Qualifier consists of two operands (child elements) as well as an operator attribute, that describes how the two operands are to be compared, as well as an operatortype attribute which identifies the datatype of the operands (and therefore influences the nature of the comparison). Use the value of the named variable as an operand. Use the value of the named property from the current instance (within the immediately enclosing Select) as an operand Allow a comparison to be made to static text/numers. The operator that should be used to compare the two operands The supported ways to compare two operands within a Qualifier. The data type of the two operands. The supported data types for comparison within a Qualifier. The XML type shared by all operands children of a qualifier Allows only a substring of this string to be utilized. The regular expression in the body of this element should have a group (parenthesis) that captures some part of the value of the original operand. The first captured group becomes the value used in the actual comparison. The name of the variable or property whose value is to be gathered for comparison within a qualifier Negate the value of the contained conditional. Logical AND of the contained conditionals. (Only returns true if all contained conditionals are true.) Logical OR of the contained conditionals. (Returns true if any contained conditional is true.)