Writing OVAL Content

SCAP-Security-Guide Authoring Conventions

Understanding the following conventions will make it easier to navigate the SCAP-Security-Guide repository and author SCAP content.

• OVAL definitions are written as source OVAL pseudo-XML files using a shorthand syntax. This shorthand syntax is unique to ComplianceAsCode.
• Each source OVAL file defines one vulnerability assessment definition. (A definition of one vulnerability can test multiple criteria.)
• OVAL files are either located in the oval subdirectory of the rule's directory.
• source OVAL files are transformed into OVAL XML files during the project's build process.
• source OVAL files applicable to a single version of software are named accordingly, e.g. fedora.xml, rhel7.xml.
• source OVAL files applicable to a multiple versions of software have the shared.xml filename.

Creating the Stub Source OVAL File

1. Navigate to the rule directory for which the OVAL definition will be authored.
2. Choose the most appropriate stub template - all OVALs have a definition and at least one test. You can find examples of OVALs in oval subdirectories of rule directories.
3. Decide the name/id of the definition following the suggested id convention in the template's definition tag.
4. Copy the example you have chosen in the first step to the oval subdirectory and name it according to whether it is shared across different products or versions.
5. Edit the source OVAL file, and make sure that you don't forget to replace the definition tag's id attribute.

Example (Linux)

# Navigate to the SSG source OVAL directory
cd RHEL/7/input/oval/
# Choose templates/template_package_removed as most appropriate template
# Decide the name of OVAL definition will be "package_ntpdate_removed"
# Copy the stub template file to 
cp templates/template_package_removed ./package_ntpdate_removed.xml
# Edit the SSG source OVAL XML file definition tag's id attribute to have name "package_ntpdate_removed.xml"

(NOTE: If you authoring a test applicable to more than one software package or version thereof, navigate instead /shared/oval.)

Customizing the SSG Source OVAL XML File

TBD

Testing a SSG Source OVAL XML File While Coding

Most developers these days author code interactively. The Python script, testcheck.py, provides all the necessary transformations to test an OVAL definition in isolation during authorship. (testcheck.py is conveniently located in all software_name/version/input/oval/ directories.)

testcheck.py will build the final OVAL XML definition file, place it somewhere under a /tmp/$$ directory, and use OpenSCAP to evaluate the system against the definition.

If the OVAL definition requires some OVAL variable (e.g. if there's <external_variable ... /> element defined within that oval check), testcheck.py will printout if the OVAL definition expects a variable. Define an appropriately named environmental value before running testcheck.py.

Example (Linux)

./testoval.py package_ntpdate_removed.xml

Example with OVAL variable (Linux)

export var_password_pam_dcredit=3
./testoval.py accounts_password_pam_dcredit.xml