- OCIL Schema -
Element Dictionary

• Schema: OCIL
• Version: 1.1
• Release Date: May 20, 2009

VERSION 1.1

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.

---

---

< ocil >

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.

Attributes:
-	scope		inter:ScopeType		(optional -- default='FULL')

Child Elements	Type	MinOccurs	MaxOccurs
generator	inter:GeneratorType	1	1
document	inter:DocumentType	0	1
inter:questionnaire	[ extends ] inter:CompoundTestActionType	1	unbounded
inter:test_action	inter:ItemBaseType	1	unbounded
inter:question	inter:QuestionType	1	unbounded
inter:choice_group	n/a	0	unbounded
inter:results	n/a	0	1

 

---

---

< questionnaire >

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.

Attributes:
-	id		inter:QuestionnaireIDPattern		(required)
-	priority		inter:PriorityType		(optional -- default='LOW')
-	child_only		xsd:boolean		(optional -- default='false')

 

---

---

< question >

Type: inter:QuestionType

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.

 

---

---

< boolean_question >

Substitution Group: inter:question

A boolean_question is a type of question with valid responses of either {TRUE, FALSE} or {YES, NO}.

Attributes:
-	default_answer		xsd:boolean		(optional)
-	model		inter:BooleanQuestionModelType		(optional -- default='MODEL_YES_NO')

 

---

---

< choice_question >

Substitution Group: inter:question

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.

Attributes:
-	default_answer_ref		inter:ChoiceIDPattern		(optional)

 

---

---

< numeric_question >

Substitution Group: inter: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.

Attributes:
-	default_answer		xsd:decimal		(optional)

 

---

---

< string_question >

Substitution Group: inter:question

A string_question is a type of question element that requires a string answer.

Attributes:
-	default_answer		xsd:string		(optional)

 

---

---

< test_action >

Type: inter:ItemBaseType

This is a common base element for the question_test_action element.

 

---

---

< question_test_action >

Substitution Group: inter:test_action

Type: inter:QuestionTestActionType

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..)

 

---

---

< boolean_question_test_action >

Substitution Group: inter:question_test_action

A boolean_question_test_action element references a boolean_question and includes handlers for TRUE (YES) or FALSE (NO) responses.

Child Elements	Type	MinOccurs	MaxOccurs
when_true	inter:ResultChoiceType	1	1
when_false	inter:ResultChoiceType	1	1

 

---

---

< choice_question_test_action >

Substitution Group: inter:question_test_action

A choice_question_test_action element references a choice_question and includes handlers for the various choices set out in the choice_question.

Child Elements	Type	MinOccurs	MaxOccurs
inter:when_choice	[ extends ] inter:ResultChoiceType	1	unbounded

 

---

---

< numeric_question_test_action >

Substitution Group: inter:question_test_action

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.

 

---

---

< string_question_test_action >

Substitution Group: inter:question_test_action

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.

Child Elements	Type	MinOccurs	MaxOccurs
inter:when_pattern	[ extends ] inter:ResultChoiceType	1	unbounded

 

---

---

< results >

The results element stores information about the results of processing the questionnaires, test_actions, and questions in a document.

Attributes:
-	start_time		xsd:dateTime		(optional)
-	end_time		xsd:dateTime		(optional)

Child Elements	Type	MinOccurs	MaxOccurs
title	inter:TextType	0	1
target	xsd:string	0	unbounded
target_address	xsd:string	0	unbounded
questionnaire_result	n/a	0	unbounded
inter:question_result	inter:QuestionResultType	0	unbounded
test_action_result	n/a	0	unbounded

 

---

---

< question_result >

Type: inter:QuestionResultType

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.)

 

---

---

< boolean_question_result >

Substitution Group: inter:question_result

A boolean_question_result element contains a reference to a boolean_question, the user's response, and whether the question was successfully posed.

Child Elements	Type	MinOccurs	MaxOccurs
answer	xsd:boolean	1	1

 

---

---

< choice_question_result >

Substitution Group: inter:question_result

A choice_question_result element contains a reference to a choice_question, the user's response, and whether the question was successfully posed.

Child Elements	Type	MinOccurs	MaxOccurs
answer	n/a	1	1

 

---

---

< numeric_question_result >

Substitution Group: inter:question_result

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.

Child Elements	Type	MinOccurs	MaxOccurs
answer	xsd:decimal	1	1

 

---

---

< string_question_result >

Substitution Group: inter:question_result

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.

Child Elements	Type	MinOccurs	MaxOccurs
answer	xsd:string	1	1

 

-- ScopeType --

Value	Description
FULL	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.
SHORT	The SHORT value indicates that once a result value can be computed for a questionnaire, then it is safe to stop asking questions.

 

-- BooleanQuestionModelType --

Provides the acceptable models (i.e. set of acceptable responses) for a boolean_question.

Value	Description
MODEL_YES_NO	MODEL_YES_NO represents a response set of {YES, NO}.
MODEL_TRUE_FALSE	MODEL_TRUE_FALSE represents a response set of {TRUE, FALSE}.

 

-- OperatorType --

Value	Description
AND	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.
OR	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.

 

---

---

== CompoundTestActionType ==

The CompoundTestActionType type describes the structures used to combine multiple test_action elements into a single result.

 

---

---

== GeneratorType ==

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.

Child Elements	Type	MinOccurs	MaxOccurs
product_name	xsd:string	0	1
product_version	xsd:string	0	1
author	n/a	0	unbounded
schema_version	xsd:decimal	1	1
timestamp	xsd:dateTime	1	1

 

== DocumentType ==

This type describes structures used to provide document-level information, including title, descriptions, and notices.

Child Elements	Type	MinOccurs	MaxOccurs
title	xsd:string	1	1
description	xsd:string	0	unbounded
notice	xsd:string	0	unbounded

 

---

---

== ItemBaseType ==

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.

Child Elements	Type	MinOccurs	MaxOccurs
notes	xsd:string	0	unbounded

 

---

---

== OperationType ==

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.

Attributes:
-	operation		inter:OperatorType
-	negate		xsd:boolean
-	priority		inter:PriorityType		(optional -- default='LOW')

Child Elements	Type	MinOccurs	MaxOccurs
inter:test_action_ref	inter:TestActionRefValuePattern	1	unbounded

 

---

---

== PatternType ==

The pattern element specifies a regular expression against which a string will be compared.

Attributes:

Simple Content

xsd:string

 

---

---

-- PriorityType --

This type provides the possible priorities of a set of test_actions.

Value	Description
HIGH
MEDIUM
LOW

 

---

---

== QuestionTestActionType ==

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.

 

---

---

== QuestionResultType ==

The QuestionResultType complex type defines structures that hold information about a question and the user's response to it.

Attributes:
-	question_ref		inter:QuestionIDPattern		(required)
-	response		inter:UserResponseType		(optional -- default='ANSWERED')

 

---

---

== QuestionType ==

The QuestionType complex type defines a structure to describe a question and any instructions to help in determining an answer.

 

---

---

== RangeType ==

This type describes structures to define a range against which a numeric user response is to be compared.

Child Elements	Type	MinOccurs	MaxOccurs
min	n/a	0	1
max	n/a	0	1

 

---

---

== ResultChoiceType ==

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.

Child Elements	Type	MinOccurs	MaxOccurs
result	inter:ResultType	1	1
inter:test_action_ref	inter:TestActionRefValuePattern	1	1

 

-- ExceptionalResultType --

The possible exceptional results of a question

Value	Description
UNKNOWN	An UNKNOWN value indicates that the result of a test cannot be determined.
ERROR	An ERROR value indicates that an error occured while processing the check. Among other causes, this can indicate an unexpected response from the user.
NOT_TESTED	A NOT_TESTED value indicates that the check has not been tested yet.
NOT_APPLICABLE	A NOT_APPLICABLE value indicates that the check is not relevant and can be skipped.

 

---

---

-- ResultType --

The ResultType simple type defines acceptable result values for questionnaires and test_actions.

Value	Description
PASS	A PASS value indicates that the check passed its test.
FAIL	A FAIL value indicates that the check did not pass its test.
UNKNOWN	An UNKNOWN value indicates that the result of a test cannot be determined.
ERROR	An ERROR value indicates that an error occured while processing the check. Among other causes, this can indicate an unexpected response from the user.
NOT_TESTED	A NOT_TESTED value indicates that the check has not been tested yet.
NOT_APPLICABLE	A NOT_APPLICABLE value indicates that the check is not relevant and can be skipped.

The following table shows how the result is computed if the operator is AND:

Pass	Fail	Error	Unkn	Not Tstd	N/A
1+	0	0	0	0	0+	Pass
0+	1+	0+	0+	0+	0+	Fail
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

The following table shows how the result is computed if the operator is OR:

Pass	Fail	Error	Unkn	Not Tstd	N/A
1+	0+	0+	0+	0+	0+	Pass
0	1+	0	0	0	0+	Fail
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

 

 

 

---

---

-- UserResponseType --

 

Value	Description
ANSWERED	An ANSWERED value indicates the user provided an evaluatable response to the question
UNKNOWN	An UNKNOWN value indicates that the result of a test cannot be determined.
ERROR	An ERROR value indicates that an error occured while processing the check. Among other causes, this can indicate an unexpected response from the user.
NOT_TESTED	A NOT_TESTED value indicates that the check has not been tested yet.
NOT_APPLICABLE	A NOT_APPLICABLE value indicates that the check is not relevant and can be skipped.

---

---

== TextType ==

The TextType complex type defines an element that holds any information.

 

---

---

-- QuestionnaireIDPattern --

ID values for questionnaires must match this pattern.

ocil:[A-Za-z0-9_\-\.]+:questionnaire:[1-9][0-9]*

 

---

---

-- QuestionIDPattern --

ID values for questions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:question:[1-9][0-9]*

 

---

---

-- QuestionTestActionIDPattern --

ID values for test_actions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:testaction:[1-9][0-9]*

 

---

---

-- TestActionRefValuePattern --

A test_action_ref may refer to either a test_action or a questionnaire. This type represents the union of these two ID patterns.

ocil:[A-Za-z0-9_\-\.]+:testaction:[1-9][0-9]*

 

---

---

-- ChoiceIDPattern --

ID values for choices in choice_questions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:choice:[1-9][0-9]*

 

-- ChoiceGroupIDPattern --

ID values for choice_group references in choice_questions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:choicegroup:[1-9][0-9]*

 

---

---

< test_action_ref >

The test_action_ref element holds a reference (id) to a test_action or questionnaire.

 

---

---

< when_choice >

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.

Child Elements	Type	MinOccurs	MaxOccurs
choice_ref	inter:ChoiceIDPattern	1	unbounded

 

---

---

< choice >

A choice element holds information about one acceptable answer to a choice_question.

 

< choice_group >

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.

Attributes:
-	id		inter:ChoiceGroupIDPattern		(required)

Child Elements	Type	MinOccurs	MaxOccurs
inter:choice	n/a	1	unbounded

 

---

---

< when_equals >

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.

Child Elements	Type	MinOccurs	MaxOccurs
value	xsd:decimal	1	unbounded

 

---

---

< when_range >

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.

Child Elements	Type	MinOccurs	MaxOccurs
range	inter:RangeType	1	unbounded

 

< when_pattern >

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.

Child Elements	Type	MinOccurs	MaxOccurs
pattern	inter:PatternType	1	unbounded

 

---

---

== ReferenceType ==

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.

 

---

---

== StepType ==

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.

Attributes:
-	is_done		xsd:boolean
-	is_required		xsd:boolean

Child Elements	Type	MinOccurs	MaxOccurs
description	inter:TextType	0	1
reference	inter:ReferenceType	0	unbounded
inter:step	inter:StepType	0	unbounded

 

---

---

< step >

Type: inter:StepType

The step element describes one step in the procedures a user should undertake in order to answer an encapsulating question.

 

---

---

< instructions >

The instructions element contains a step by step procedure to guide the user in answering a question.

Child Elements	Type	MinOccurs	MaxOccurs
title	inter:TextType	1	1
inter:step	inter:StepType	1	unbounded