Authoring Style Guide

Introduction

This is a living document that details the stylistic decisions that have been made for content in the OVAL Repository. As new decisions are made and questions are answered on the oval-discussion-list this document will be updated.

For information on submitting new and modified content to the OVAL Repository please review the Submission Guidelines.

General

• Comments should always be used on definition criteria, tests, objects, states, and variables. When writing comments keep in mind that they may be displayed in various tool user interfaces. Since many items are reused across multiple tests and definitions make sure that each comment has enough detail to stand alone. Comments are also searchable in the OVAL Repository.
• Additional metadata beyond what is defined by the OVAL Language and the OVAL Repository Metadata Schema is not permitted in the OVAL Repository.
• When creating a new item care should be taken to ensure that any preexisting item is reused. Reusing items cuts down on content maintenance cost and greatly reduces the effort required to write a new OVAL definition.

Definitions

• Do not set a comment on the definition's root criteria element.
• Do set a comment on all other criteria, criterion, and extend_definition elements.
  • On a criterion element the comment should match the comment on the referenced test.
  • On a extend_definition element the comment should match the title on the extended definition.
  • On a criteria element the comment should summarize the comments of its contents.
• Do not include the negate attribute on criteria, criterion, or extend_definition elements when the element is not negated. Setting negate to false simply reduces readablity.
• Patch definitions:
  • Patch based OVAL definitions have their class attribute set to "patch".
  • Patch based OVAL definitions should include checks for all items that a patch includes. If a patch includes 6 files and sets 2 registry keys the corresponding OVAL definition should include 6 file_tests and 2 registry_key tests.
  • Patch based OVAL definitions include a reference to the patch binary name for which the definition was written. This means that there may be many OVAL definitions written for a given security bulletin.
  • Patch based OVAL definitions have a one to one relationship with a given patch binary name.
• Vulnerablity definitions:
  • Vulnerability based OVAL definitions have their class attribute set to "vulnerability".
  • Vulnerability based OVAL definitions should include only the checks required to determine the presence of a vulnerability on a given host.
  • Vulnerability based OVAL definitions include a CVE reference.
  • Vulnerability based OVAL definitions have a one to one relationship with a given CVE name.

Tests

• Always include the check_existence attribute on tests. The check_existence attribute was added to version 5.3 of the OVAL Language and has a default value of "at_least_one". Since this is a new attribute on tests we have decided to always include it in the OVAL Repository, even when the desired value is the default value.

Objects

• Do not set datatype and operation attributes on the child elements of an object when they are the default values. This greatly improves readability.
• Avoid using regular expressions in objects. Regular expressions have historically been error prone, are not always easy to understand, and their evaluation during data collection can be costly.

States

• States tend to be the exception to the reuse rule mentioned above. We have made the decision to allow duplicate states in the OVAL Repository to accommodate situations where a given state may have different meanings. For example, a registry_state with a value of 1 might mean some setting is enabled when paired with one object in some test and might mean some application has a version of 1 when paired with another object in some other test. We feel that this will help us cut down on content maintenance costs over time. Inappropriate reuse of states in the OVAL Repository will likely make content maintenance more difficult. As a rule of thumb when in doubt create a new state.
• Do not set the operator attribute on the state element if it is the default value. Setting this attribute does not improve readability.
• Do not set datatype and operation attributes on the child elements of a state when they are the default values. This greatly improves readability.

Variables

• External variables should make use of the possible_value and possible_restriction elements to tightly restrict the allowable set of input values. This will assist tools in processing the variable and help other content authors when reviewing the variable.

Page Last Updated: May 28, 2008