VERSION 1.0 The Open Checklist Interactive Language (OCIL) is a language to express a set of questions to be presented to a user and procedures to interpret responses to these questions for the purpose of developing security checklists. Although its intended domain of use is IT security, its generic nature allows for other applications. For instance, it could be used for authoring research surveys, academic course exams, and instructional walkthroughs. This document was originally developed by David Waltermire (The Center for Internet Security) and has been revised by The MITRE Corp with input from the security benchmark community. It is intended for developers and assumes familiarity with XML. This namespace is required for xml:lang support. The ocil element is the root XML element of an OCIL document. It contains information about one or more questionnaires. It may also contain results elements to store prior responses. The generator element contains information related to the generation of the file. Specifically, a generator contains information about the application used to create the file, when it was created, and the schema to use to validate it. This element contains document-level information, including title, descriptions, and notices. A questionnaire contains a set of questions that determines compliance with a check. Each questionnaire returns a value based on the responses to the various questions that it references. Each questionnaire should represent a single compliance check, such as might be referenced by an XCCDF Rule. The test_action element contains information about what action to take based on the answer to a referenced question element within a questionnaire. It can be a compound_test_action, boolean_question_test_action, choice_question_test_action, numeric_question_test_action, or string_question_test_action. The question element contains information for a single question to be answered. Based on the data type of acceptable answers to the question, it can be a boolean_question, choice_question, numeric_question, or string_question. Holds choice groups which represent possible sets of choices for choice_questions. Choice_groups may be reused across multiple choice_questions. The results element contains the results of an evaluation of the OCIL file. This includes records of all questionnaire results, question results, and test_action results. This specifies the test_actions referenced by the questionnaires in this document should be evaluated. If a value of FULL is provided, then all test_actions in a questionnaire will be evaluated regardless of whether the result can be known ahead of time. If a value of SHORT is provided a questionnaire will stop evaluating test_actions as soon as the final result has been determined. (For example, if one test_action evaluates to FAIL and the test_actions of a questionnaire are being ANDed together, the result is immediately known to be FAIL regardless of the results of other test_actions. If the scope is FULL, even though it is known that the questionnaire will return FAIL, the other test_actions will still be evaluated. If the scope is SHORT, no further test_actions would be evaluated since the final result had been determined.) test_actions include question_test_action and compound_test_action (Questionnaires are CompoundTestAction) A questionnaire represents specific question or set of questions that evaluate to a single result. A questionnaire may contain multiple test_actions. test_actions may be nested and aggregated thru some acceptable operation to produce the result of a check. Each questionnaire is required to have a unique identifier that conforms to the definition of NCName in the Recommendation "Namespaces in XML 1.0", i.e., all XML 1.0 names that does not contain colons. Priority is an optional attribute that can either be HIGH, MEDIUM or LOW. It specifies the importance of a paritcular test action reference. This attribute specifies whether or not this questionnaire should only appear as a child of another questionnaire. All questionnaires must be defined within the body of the ocil element and, by default, interpreters might simply grab all questionnaires and present them to a user. However, questionnaires can reference other questionnaires through a test_action_ref. If an author references a questionnaire in this way they may not wish that the questionnaire be presented to a user except as a child of another questionnaire. By setting the child_only attribute to true, the author is indicating that the given questionnaire should not be a "top-level" questionnaire but should instead only be presented as the child of another questionnaire. A question elements contains information one question that needs to be answered by a user. It can be a boolean_question, choice_question, numeric_question, or string_question depending on the set of acceptable answers. A boolean_question is a type of question with valid responses of either {TRUE, FALSE} or {YES, NO}. The default_answer attribute specifies the default value of the boolean_question. Its value may be set to true or false. The model attribute specifies whether to the user should respond with {True, False} or {YES, NO}. If the value of this attribute is not set, then it defaults to MODEL_YES_NO (i.e. response can either be YES or NO). A choice_question is a type of question element with one or more acceptable answers specified by the author. The user will select one of these specified answers as their response. Acceptable answers are specified either explicitly using the choice element or implicitly using the choice_group_ref element to reference a choice_group element. Choices are presented in the order in which they are provided. All the choices in a choice_group are inserted in the order in which they appear within the choice_group. Holds the information associated with one of the possible responses to this choice_question. Holds a reference to a choice_group. The questions described in this choice group are used as possible responses for this choice_question. The default_answer_ref specifies the choice id of the default answer to the question. A numeric_question is a type of question_element that requires a numeric answer. Acceptable values may be positive or negative and may include decimals. An optional default value may be specified as the answer. A string_question is a type of question element that requires a string answer. An optional default value may be specified as the answer. This is a common base element for the question_test_action element. The question_test_action element contains a reference to a single question along with a set of handlers that indicate how processing should proceed based on the answer provided by the user. This element is abstract and is implemented in a document as a boolean_test_action, choice_test_action, numeric_test_action, or string_test_action. The type of question_test_action must match the type of question referenced. (E.g. a boolean_test_action MUST reference a boolean_question, etc..) A boolean_question_test_action element references a boolean_question and includes handlers for TRUE (YES) or FALSE (NO) responses. The element when_true specifies the action to do when the answer is true. The element when_false specifies the action to do when the answer is false. A choice_question_test_action element references a choice_question and includes handlers for the various choices set out in the choice_question. Specifies the action to perform when the indicated choice is selected by the user. Ensure that no choice_test_action has multiple branches for a single choice A numeric_question_test_action element references a numeric_question and includes handlers that indicate actions to perform based on whether the user's response matches a particular value or falls within a particular range. This structure is used to ensure that any number of when_equals and when_range handlers may appear, but there must be at least one handler (of one type or the other) and any when_equals handlers must precede any when_range. This element holds information on what to do when the answer matches the specified value. This element holds information on what to do when the answer is within a specified range of values. This element holds information on what to do when the answer is within a specified range of values. A string_question_test_action element references a string_question and includes handlers that indicate actions to perform based on whether the user's response matches a given regular expression. This element holds information on what to do when the answer matches a specified regular expression pattern. The results element stores information about the results of processing the questionnaires, test_actions, and questions in a document. The title element contains a descriptive heading or caption describing the result set. The target element contains identifying information about the host that was targeted by the assessment. The target_address element contains address information about the host that was targeted by the assessment. The questionnaire_result element contains information about the result of a particular questionnaire. The questionnaire_ref attribute identifies a particular questionnaire using its id. The result attribute holds the result of evaluating the specified questionnaire. A question_result element contains result information associated with a specific question. One of these elements (or rather, one of its derrived elements) will appear for each question evaluated. The test_action_result element contains the result of a test_action evaluation. One of these elements will appear for each test_action evaluated. The test_action_ref attribute identifies a specific test_action using its id. The result attribute holds the result of evaluating the specified test_action specified. The start_time attribute is an optional attribute the specifies when the evaluation of this OCIL file started. The end_time attribute is an optional attribute the specifies when the evaluation of this OCIL file ended. A question_result element contains result information associated with a specific question. The specific type of question_result (boolean_question_result, choice_question_result, etc.) depends on the type of the associated question (boolean_question, choice_question, etc.) A boolean_question_result element contains a reference to a boolean_question, the user's response, and whether the question was successfully posed. The value of the answer to the boolean_question. It could either be TRUE or FALSE. A choice_question_result element contains a reference to a choice_question, the user's response, and whether the question was successfully posed. The answer element contains a choice_ref attribute that identifies the choice selected by the user. The choice_ref attribute specifies an id of the choice selected by the user. A numeric_question_result element contains a reference to a numeric_question, the result provided by the user, and whether the question was successfully posed. The decimal value of the answer to a numeric_question as provided by the user. A string_question_result element contains a reference to a string_question, the string provided by the user in response, and whether the question was successfully posed. The string value of the answer to a string_question provided by the user. The FULL value indicates that all questions must be asked regardless of whether or not it they are all needed to produce a result for a questionnaire. The SHORT value indicates that once a result value can be computed for a questionnaire, then it is safe to stop asking questions. Provides the acceptable models (i.e. set of acceptable responses) for a boolean_question. MODEL_YES_NO represents a response set of {YES, NO}. MODEL_TRUE_FALSE represents a response set of {TRUE, FALSE}. The AND operator produces a true result if every argument is true. If one or more arguments are false, the result of the AND is false. See the truth table provided in the ResultType type for a complete list of how the various result types are combined by an AND operation. The OR operator produces a true result if one or more arguments is true. If every argument is false, the result of the OR is false. See the truth table provided in the ResultType type for a complete list of how the various result types are combined by an AND operation. The CompoundTestActionType type describes the structures used to combine multiple test_action elements into a single result. The title element contains a descriptive heading for this set of test_actions. The description element contains a caption describing the set of test_actions. The reference element contains information about any external references related to this step. Examples could include references to other standards such as CVE, CCE, or CPE. The actions element holds one or more test_action elements along with the operators used to combine them into a single result. The GeneratorType type defines an element that is used to hold information about when a particular OCIL document was generated, what version of the schema was used, what tool was used to generate the document, and what version of the tool was used. Additional generator information is also allowed although it is not part of the official OCIL language. Individual organizations can place generator information that they feel are important. The optional product_name specifies the name of the application used to generate the file. The optional product_version specifies the version of the application used to generate the file. Identifies one of the authors of this document Optionally, identify the organization for whom this author works. The required schema_version specifies the version of the OCIL schema that the document has been written in and that should be used for validation. The required timestamp specifies when the particular OCIL document was generated. The format for the timestamp is yyyy-mm-ddThh:mm:ss. This type describes structures used to provide document-level information, including title, descriptions, and notices. Used to provide a title for this document Each description element contains part of an overall description for the entire document. (Note that questionnaires contain their own description for questionnaire specific descriptions.) Each notice contains a notice or warning to the user of this document. The ItemBaseType complex type defines structures allowing a set of notes to be included. This type is inherited by many of the elements in the OCIL language. An optional set of notes to describe additional information. The OperationType type defines structures that hold a set of test_actions and provide instructions as to how to aggregate their individual results into a single result. The test_action_ref elements holds the identifier of a test_action element. At least one test_action_ref must be included. The operation attribute describes how to aggregate the results of a set of testActions. Its value defaults to the Boolean operator "AND". The negate attribute can be used to specify whether to toggle the result from PASS to FAIL, and vice versa. A result other than PASS or FAIL (e.g. ERROR, NOT_TESTED, etc.) will be unchanged by a negate operation. Priority is an optional attribute that can either be HIGH, MEDIUM or LOW. It specifies the importance of the referenced set of test_action elements. The pattern element specifies a regular expression against which a string will be compared. This contents of this field must be a Perl Compatable Regular Expression (PCRE). This type provides the possible priorities of a set of test_actions. The QuestionTestActionType type defines structures that are used to hold handlers for non-standard results (UNKNOWN, NOT_TESTED, NOT_APPLICABLE, and ERROR) received from a referenced question. All children of question_test_action extend this type. The title element contains a descriptive heading for this set of handlers. The when_unknown element contains processing instructions for when when the received result is UNKNOWN. The when_not_tested element contains processing instructions for when when the received result is NOT_TESTED. The when_not_applicable element contains processing instructions for when when the received result is NOT_APPLICABLE. The when_error element contains processing instructions for when when the received result is ERROR. The question_ref attribute contains the id value of a question element. Each item is required to have a unique identifier that conforms to the definition of NCName in the Recommendation "Namespaces in XML 1.0", i.e., all XML 1.0 names that does not contain colons. The QuestionResultType complex type defines structures that hold information about a question and the user's response to it. The question_ref attribute contains the id of a question. The success attribute indicates whether a question was successfully posed to the user. A value of true indicates a successfully posed question. A value of false indicates that there was a problem posing the question and will lead to an ERROR result state. The QuestionType complex type defines a structure to describe a question and any instructions to help in determining an answer. Provides the text of the question to pose to the user. An optional instructions field may be included to hold additional instructions to assist the user in determining the answer to the question. Each item is required to have a unique identifier that conforms to the definition of NCName in the Recommendation "Namespaces in XML 1.0", i.e., all XML 1.0 names that does not contain colons. This type describes structures to define a range against which a numeric user response is to be compared. The min element contains a minimum value. The inclusive attribute specifies whether the minimum value should be in the specified range. The default is true, indicating it is included. The max element contains a maximum value. The inclusive attribute specifies whether the minimum value should be included in the range. The default is true, indicating it is included. The ResultChoiceType complex type specifies processing instructions - either produce a result or move on to another test. The ResultChoiceType is extended by all handlers ("when_...") in test_actions. This element indicates that a final value (i.e. PASS, FAIL, ERROR, UNKNOWN, NOT_TESTED, NOT_APPLICABLE) should be returned if the encapsulating handler is invoked. This element indicates that a new test_action should be processed if the encapsulating handler is invoked. The ResultType simple type defines acceptable result values for questionnaires and test_actions. || P | F | E | U | NT | NA || ---------------||-----------------------------||------------------||------------------------------------------ || 1+ | 0 | 0 | 0 | 0 | 0+ || Pass || 0+ | 1+ | 0+ | 0+ | 0+ | 0+ || Fail AND || 0+ | 0 | 1+ | 0+ | 0+ | 0+ || Error || 0+ | 0 | 0 | 1+ | 0+ | 0+ || Unknown || 0+ | 0 | 0 | 0 | 1+ | 0+ || Not Tested || 0 | 0 | 0 | 0 | 0 | 1+ || Not Applicable || 0 | 0 | 0 | 0 | 0 | 0 || Not Tested ---------------||-----------------------------||------------------||------------------------------------------ || 1+ | 0+ | 0+ | 0+ | 0+ | 0+ || Pass || 0 | 1+ | 0 | 0 | 0 | 0+ || Fail OR || 0 | 0+ | 1+ | 0+ | 0+ | 0+ || Error || 0 | 0+ | 0 | 1+ | 0+ | 0+ || Unknown || 0 | 0+ | 0 | 0 | 1+ | 0+ || Not Tested || 0 | 0 | 0 | 0 | 0 | 1+ || Not Applicable || 0 | 0 | 0 | 0 | 0 | 0 || Not Tested A PASS value indicates that the check passed its test. A FAIL value indicates that the check did not pass its test. An UNKNOWN value indicates that the result of a test cannot be determined. An ERROR value indicates that an error occured while processing the check. Among other causes, this can indicate an unexpected response from the user. A NOT_TESTED value indicates that the check has not been tested yet. A NOT_APPLICABLE value indicates that the check is not relevant and can be skipped. The TextType complex type defines an element that holds any information. This attribute specifies the language in which to interpret the information. ID values for questionnaires must match this pattern. ID values for questions must match this pattern. Each ID must be unique within an OCIL document. ID values for test_actions must match this pattern. Each ID must be unique within an OCIL document. A test_action_ref may refer to either a test_action or a questionnaire. This type represents the union of these two ID patterns. ID values for choices in choice_questions must match this pattern. Each ID must be unique within an OCIL document. ID values for choice_group references in choice_questions must match this pattern. Each ID must be unique within an OCIL document. The test_action_ref element holds a reference (id) to a test_action or questionnaire. The negate attribute can be used to specify whether to toggle the result from PASS to FAIL, and vice versa. A result other than PASS or FAIL (e.g. ERROR, NOT_TESTED, etc.) will be unchanged by a negate operation. Priority is an optional attribute that can either be HIGH, MEDIUM or LOW. It specifies the importance of a priority test action reference. The element when_choice specifies the action to take in a choice_test_action when a particular choice is selected by a user in response to a choice_question. The choice_ref element specifies the id of a choice. A choice element holds information about one acceptable answer to a choice_question. All choices are tagged with a unique identifier that may be referenced by a choice_test_action referencing the encapsulating choice_question. A choice_group defines a group of choices that may then be reused in multiple choice_question elements. For example, a document may include multiple choice_questions with the options of "Good", "Fair", or "Poor". By defining these choices in a single choice_group, the author would not need to list them out explicitly in every choice_question. Holds the information associated with one of the possible responses for a choice_question. Holds the id of this choice group. This id is referenced within choice_question elements to include the choices contained in a group. The element when_equals specifies the action to take in a numeric_test_action when a particular value is given by a user in response to a numeric_question. Each value holds what is to be matched. The element when_range specifies the action to take in a numeric_test_action when a value given by a user in response to a numeric_question falls within the indicated range. Each range element holds a single numeric range. The element when_pattern specifies the action to take in a string_test_action when a string given by a user in response to a string_question matches the given regular expression. Each pattern element holds a regular expression against which the user's response string is to be compared. The ReferenceType complex type defines structures used to hold information about an external reference given its URI and description. This structure may be used to reference other standards such as CVE, CCE, or CPE. To do so, the href attribute would give the relevant namespace. For example, the namespace of the current version of CPE is http://cpe.mitre.org/dictionary/2.0 and the body of this element would hold a specific CPE identifier. References to other information (documents, web pages, etc.) are also permitted. The href attribute holds the URI of an external reference. This may be the namespace associated with the information in the body or a web URL containing relevant information. The StepType complex type defines structures that describe one step (out of possibly multiple steps) that a user should take in order to respond to a question. The steps would appear as parts of the question's instructions element. The description element contains some information about this step. The reference element contains information about any external references related to this step. The step element contains substeps for this particular step. The is_done attribute indicates whether this step has been done. The value is true when it is done. Otherwise, it is false, It is an optional attribute that defaults to false. The is_required attribute indicates whether a step is required or not. If it is not, then it can be skipped. It is an optional attribute that defaults to true. The step element describes one step in the procedures a user should undertake in order to answer an encapsulating question. The instructions element contains a step by step procedure to guide the user in answering a question. The title element contains a descriptive heading for the instructions. The step element contains information about one step of the instructions.