Requesting Changes to the OVAL Language

New Constructs| Changes to Existing Constructs| Deprecating Constructs| Submission Instructions

Introduction

Community members are welcome to propose changes to the OVAL Language. This includes requests to:

  • Add new OVAL Constructs (e.g., component schemas, core capabilities, tests, entities, or functions).
  • Modify existing OVAL Constructs.
  • Deprecate existing OVAL Constructs.

Requests should be submitted to the OVAL Developer's Forum for review by the OVAL community, or directly to oval@cisecurity.org. Guidelines for submitting change requests are included below.

Requests to Add New OVAL Constructs

To keep up with new technologies, platforms, and changing systems, it is often necessary to add new capabilities to the OVAL Language in order to support the collection of new system configuration information or to perform a new type of check. This may come in the form of new OVAL Component Schemas, Core Capabilities, Tests, Entities, or Functions. Guidelines for submitting such constructs are noted below.

Submitting a New OVAL Component Schema

An OVAL Component Schema is a collection of OVAL Tests, Objects, States, and Items that are related based on the platform for which they can check or describe configuration information. In order to extend the OVAL Language to a new platform, it is necessary to develop a new OVAL Component Schema for that platform. The following describes the guidelines for proposing a new OVAL Component Schema for inclusion in the OVAL Language.

  1. What platform is the OVAL Component Schema for? Why is it needed?
  2. Provide a brief overview of each OVAL Test included in the proposed OVAL Component Schema. Please see Submitting a New OVAL Test below for more information on what to include.
  3. Provide the OVAL Definitions and System Characteristics schemas for the proposed OVAL Component Schema.
  4. Provide sample content that demonstrates the proposed OVAL Component Schema usage.
  5. How can the OVAL Tests in the proposed OVAL Component Schema be implemented?
    1. Relevant APIs for each entity in the new OVAL Object, State, and Item
    2. Algorithms that can be followed
    3. Anything else that will help a developer implement support for the test
  6. Any additional information (references, caveats, etc.) that will be relevant in determining whether or not the OVAL Component Schema should be accepted as part of the OVAL Language.

Submitting a New OVAL Core Capability

The OVAL Core consists of the OVAL Definitions, System Characteristics, Results, Variables, and Directives Schemas. Additional functionality added to these schemas is considered a new OVAL Core Capability. The following describes the guidelines for proposing a new OVAL Core Capability to the OVAL Language.

  1. What is the proposed OVAL Core Capability? Why is it needed?
  2. What OVAL Core Schemas are affected by this new OVAL Core Capability?
  3. Are there multiple approaches to implementing the proposed OVAL Core Capability? If so, present each approach along with the relevant pros and cons.
  4. Does the proposed OVAL Core Capability represent a fundamental change to the OVAL Language?
  5. Provide sample content that demonstrates the proposed OVAL Core Capability use cases.
  6. Provide the relevant documentation associated with the proposed OVAL Core Capability.
  7. OPTIONAL: Implementing the proposal in the schema is recommended, but, not required.

Submitting a New OVAL Test

An OVAL Test is an OVAL Construct that correlates what OVAL Items on the system should be collected and how many of those OVAL Items must match the specified OVAL State(s) to evaluate to a result of 'true'. When proposing a new OVAL Test, it is necessary to also design the corresponding OVAL Object, State, and Item. The following describes the guidelines for proposing a new OVAL Test to the OVAL Language.

  1. What are the use cases for the proposed test? Why is it needed?
  2. What OVAL Component schema(s) are affected?
  3. What will the OVAL Object, State, and Item constructs look like?
    1. Documentation explaining what each construct does.
    2. For each entity specify the following:
      1. Name
      2. Documentation
        1. What information does the OVAL Entity hold?
        2. If it makes use of the xsi:nil attribute, what does it mean when xsi:nil='true'?
        3. Are there any special restrictions on what the OVAL Entity can hold?
      3. Datatype
      4. Restrictions on the available operations
      5. Minimum/maximum occurrences
      6. Values if bound by an enumeration
      7. Does it make use of the xsi:nil attribute?
      8. How to implement the entity
        1. Relevant APIs
        2. Algorithms that can be followed
        3. Anything else that will help a developer implement support for the entity
    3. OPTIONAL: Implementing the proposal in the schema is recommended, but, not required.
  4. Provide sample content that demonstrates the OVAL Test use cases.
  5. Any additional information (references, caveats, etc.) that will be relevant in determining whether or not the OVAL Test should be accepted as part of the OVAL Language.

Submitting a New OVAL Entity

An OVAL Entity is a system configuration property in the OVAL Language. When an OVAL Entity is used in an OVAL Object or State, it represents something being specified about that system configuration property. When an OVAL Entity is used in an OVAL Item, it represents the system configuration property as collected from the system. The following describes the guidelines for proposing a new OVAL Entity to the OVAL Language.

  1. What are the use cases for the proposed OVAL Entity? Why is it needed?
  2. What constructs will be affected? Does it break backwards compatibility with previous versions of the OVAL Language? If so, please propose a new OVAL Test following the guidelines in Submitting a New OVAL Test above.
  3. For each entity specify the following:
    1. Name
    2. Documentation
      1. What information does the OVAL Entity hold?
      2. If it makes use of the xsi:nil attribute, what does it mean when xsi:nil='true'?
      3. Are there any special restrictions on what the OVAL Entity can hold?
    3. Datatype
    4. Restrictions on the available operations
    5. Minimum/maximum occurrences
    6. Values if bound by an enumeration
    7. Does it make use of the xsi:nil attribute?
    8. How to implement the entity
      1. Relevant APIs
      2. Algorithms that can be followed
      3. Anything else that will help a developer implement support for the entity
    9. OPTIONAL: Implementing the proposal in the schema is recommended, but, not required.
  4. Any additional information (references, caveats, etc.) that will be relevant in determining whether or not the OVAL Entity should be accepted as part of the OVAL Language.

Adding a New OVAL Function

An OVAL Function is an OVAL Construct that is used to manipulate or perform some operation on a specified set of values at run-time. The following describes the guidelines for proposing a new OVAL Function to the OVAL Language.

  1. What does the function do? Why is it needed?
  2. Are there any requirements on the number of arguments or datatypes of those arguments?
  3. Any there any attributes necessary to drive the function?
  4. Provide documentation for the proposed OVAL Function
    1. What does the function do?
    2. How should the function process the arguments?
    3. Functionality of attributes (if applicable)
    4. Boundary and error conditions (if applicable)
    5. Restrictions on the number of arguments or their datatypes (if applicable)
    6. Other useful documentation
  5. Sample content that demonstrates its use cases.
  6. OPTIONAL: Implementing the proposal in the schema is recommended, but, not required.
Back to Top

Requests to Add New OVAL Constructs

  1. What construct needs to be modified? Why does it need to be modified (e.g. missing or ambiguous documentation, datatype does not match the value, incorrect minimum/maximum occurrences, etc.)?
  2. Does it break backwards compatibility with previous versions of the OVAL Language? If so, should it be considered under the Exceptions clause of the OVAL Language Versioning Methodology? Please see OVAL Language Versioning Methodology for more information.
  3. Present the improvements
    1. Revised or additional documentation
    2. Describe changes to the schema
    3. OPTIONAL: Implementing the changes in the schema is recommended, but not required.
Back to Top

Requests to Deprecate OVAL Constructs

When an OVAL Construct contains security issues, results in inconsistency, or uses obsoleted technologies or methodologies it may be desirable to deprecate it in the OVAL Language. For more information please see the OVAL Language Deprecation Policy. The following describes the guidelines for requesting the deprecation of OVAL Constructs in the OVAL Language.

  1. What OVAL Construct should be deprecated? Why should the OVAL Construct be deprecated?
  2. Should a new OVAL Construct be recommended to replace it? If so, please refer to relevant sub-section in Submitting a Request to Add New OVAL Constructs above.
Back to Top

Submission Instructions

  1. Draft an email message that contains the information described above.
  2. Attach any relevant documents to the message such as schema changes, sample content, etc.
  3. Attach the completed OVAL Proposal Form.

  4. Send the message to the OVAL Developers Forum at oval-developer-list@lists.mitre.org for review by the OVAL Community. Note that you must be a member of the OVAL Developer's Forum to send a message to the list.

    Alternatively, those wishing to submit sensitive information may send it directly to oval@cisecurity.org.

Back to Top