Skip to main content

OHDF Schema Basics

Charles Hu6/10/24About 7 min

A Look Ahead

In this section, we will cover:

An Overview of the OHDF Schema

In order to make an OHDF mapper, it is important to understand the specifics of how OHDF is actually structured through the OHDF schema.

The OHDF schema is designed to provide a simple, structured, and hierarchal view of security tool results. OHDF actually consists of several related schema formats; however, the Exec JSON format is the most common and is typically the one being referred to when speaking of the OHDF schema. Any file or object that implements the schema can be broken down into a hierarchy of four main object structures. These structures are:

1. Exec JSON

This is the top level object structure that contains the security data (which is stored in the Profiles structure and related substructures), relevant metadata on the tool used to generate the OHDF file itself (stored in structures such as Platform, Version, and Statistics), and miscellaneous information that does not neatly fit in the previous structures (stored in the Passthrough structure).

Before we discuss the Profiles structure and its related substructures, here is a brief introduction to the latter object structures contained by the Exec JSON superstructure:

  • Platform: This structure contains metadata involving the platform or tool that is producing the OHDF file.

  • Version: This structure contains metadata involving the version of the platform or tool that is producing the OHDF file.

  • Statistics: This structure contains metadata involving the specific statistics of the original run that produced the export.

  • Passthrough: The primary purpose of the Passthrough structure is to contain and transport any piece of information that cannot be properly stored in the other Exec JSON substructures. Unlike other object structures in the OHDF schema, there is no formal schema declaration for the specific fields that exist in Passthrough. This means that Passthrough is fluid and capable of accommodating user-defined object fields as needed. There are, however, commonly agreed upon fields for specific capabilities, such as data preservation, that are discussed further in the next section.

A basic representation of this structure in JSON is as so:

{
  execjson: {
    platform: {...},
    version: ...,
    statistics: {...},
    profiles: [...],
    passthrough: {...}
  }
}

2. Profiles

This structure contains metadata on the target system of the original security tool export and on the specific run performed by the security tool. Through this, the Profiles structure provides a high-level overview of the security tool result and the targeted system, which are formatted in a manner that is digestible and immediately accessible to the assessor. There is typically only one Profiles instance in a single Exec JSON structure (represented as a single element in an array of Profiles). Further instances of Profiles are additional overlays.

A basic representation of this structure in JSON is as so:

{
  execjson: {
    profiles: [...],
    ...
  }
}

3. Controls

Controls are security requirements that are used to prevent, mitigate, and address various security risks to sensitive information, systems, and infrastructure. In the case of OHDF, the Controls structure is a collection of requirements tested for by an external security tool to ensure that the target complies with vulnerability and weakness prevention standards. Any given Profiles structure contains some number of Controls structures (i.e., an array of Controls) which were tested against the target system during the original security tool run.

A basic representation of this structure in JSON is as so:

{
  profiles: [
    {
      controls: [...],
      ...
    },
    ...
  ],
  ...
}

4. Results

The Results structure contains information on the results of specific tests ran by the security tool on the target system against a single security requirement/control. These results will always correlate to a certain instance of a Controls structure and can report either passed, failed, skipped, or error to indicate the test status. Any given Controls structure contains some number of Results structures (i.e., an array of Results) which reflect the implemented tests to check if the target system is actually meeting the overall requirement/control. The test statuses of these results cumulatively influence the determined compliance level of the target system for some set of requirements/controls.

A basic representation of this structure in JSON is as so:

{
  controls: [
    {
      results: [...],
      ...
    },
    ...
  ],
  ...
}

Overall Hierarchy

These aforementioned main object structures cumulatively result in the following general structure:

{
  execjson: {
    platform: {...},
    version: ...,
    statistics: {...},
    profiles: [
      {
        controls: [
          {
            results: [...],
            ...
          },
          ...
        ],
        ...
      },
      ...
    ],
    passthrough: {...}
  }
}

A Look Back

In this section, we covered:

  • Core structures of the OHDF schema:

    • Exec JSON

      • This is the top level object structure that acts as a container for all of the other object structures that are specialized for specific sets of information.

    • Profiles

      • This structure is for containing high-level metadata on the security tool run.

    • Controls

      • This structure is for containing information pertaining to the set of controls/requirements that were ran against the target system in the original security tool run.

    • Results

      • This structure is for containing information pertaining to the specific test results of the application of the control/requirement set against the target system.

  • A look at the overall OHDF schema hierarchy

Knowledge Check

Describe the relationship between Profiles, Controls, and Results.

The Profiles object structure contains one or more Controls structures (represented as a controls array within a profiles element).

The Controls object structure contains one or more Results structures (represented as a results array within a controls element).

Say that we map from Format A to OHDF and have data elements left over in Format A that are still uncorrelated. What do we do with those data elements?

We perform data preservation and place the uncorrelated data elements from Format A into the Passthrough structure in OHDF (the explicit field to use will be defined later).

Knowledge Review

Now that we're familiar with the general layout of an OHDF file, let's briefly look at an actual OHDF file generated from a Twistlock security scan export. This OHDF file in particular was created through the OHDF Converters library embedded in the Heimdall visualizer.

Since we have not yet gone over the specific OHDF schema fields, try to focus on the actual information being stored by file instead and ask yourself:

  • What is the purpose of this specific piece of data? What is it trying to convey (file metadata, vulnerability alerts, check results, etc.)?

  • Does this piece of data fit in with the general purpose of the structure that contains it?

  • Would this piece of data fit better in another structure?

Twistlock-to-OHDF Sample

This file has been truncated for pedagogical purposes. For the full file, see here

Twistlock-to-OHDF Sample
{
  "platform": {
    "name": "Heimdall Tools",
    "release": "2.6.29",
    "target_id": "registry.io/test:1a7a431a105aa04632f5f5fbe8f753bd245add0a"
  },
  "version": "2.6.29",
  "statistics": {},
  "profiles": [
    {
      "name": "Twistlock Scan",
      "title": "Twistlock Project: All / TEST-COLLECTION",
      "summary": "Package Vulnerability Summary: 97 Application Compliance Issue Total: 0",
      "supports": [],
      "attributes": [],
      "groups": [],
      "status": "loaded",
      "controls": [
        {
          "tags": {
            "nist": ["SI-2", "RA-5"],
            "cci": ["CCI-002605", "CCI-001643"],
            "cveid": "CVE-2021-43529"
          },
          "refs": [],
          "source_location": {},
          "title": "CVE-2021-43529",
          "id": "CVE-2021-43529",
          "desc": "DOCUMENTATION: A remote code execution flaw was found in the way NSS verifies certificates. This flaw allows an attacker posing as an SSL/TLS server to trigger this issue in a client application compiled with NSS when it tries to initiate an SSL/TLS connection.  Similarly, a server application compiled with NSS, which processes client certificates, can receive a malicious certificate via a client, triggering the flaw. The highest threat to this vulnerability is confidentiality, integrity, as well as system availability.              STATEMENT: The issue is not limited to TLS. Any applications that use NSS certificate verification are vulnerable; S/MIME is impacted as well.  Similarly, a server application compiled with NSS, which processes client certificates, can receive a malicious certificate via a client.  Firefox is not vulnerable to this flaw as it uses the mozilla::pkix for certificate verification. Thunderbird is affected when parsing email with the S/MIME signature.  Thunderbird on Red Hat Enterprise Linux 8.4 and later does not need to be updated since it uses the system NSS library, but earlier Red Hat Enterprise Linux 8 extended life streams will need to update Thunderbird as well as NSS.             MITIGATION: Red Hat has investigated whether a possible mitigation exists for this issue, and has not been able to identify a practical example. Please update the affec",
          "impact": 0.9,
          "code": "{\n  \"id\": \"CVE-2021-43529\",\n  \"status\": \"affected\",\n  \"cvss\": 9.8,\n  \"description\": \"DOCUMENTATION: A remote code execution flaw was found in the way NSS verifies certificates. This flaw allows an attacker posing as an SSL/TLS server to trigger this issue in a client application compiled with NSS when it tries to initiate an SSL/TLS connection.  Similarly, a server application compiled with NSS, which processes client certificates, can receive a malicious certificate via a client, triggering the flaw. The highest threat to this vulnerability is confidentiality, integrity, as well as system availability.              STATEMENT: The issue is not limited to TLS. Any applications that use NSS certificate verification are vulnerable; S/MIME is impacted as well.  Similarly, a server application compiled with NSS, which processes client certificates, can receive a malicious certificate via a client.  Firefox is not vulnerable to this flaw as it uses the mozilla::pkix for certificate verification. Thunderbird is affected when parsing email with the S/MIME signature.  Thunderbird on Red Hat Enterprise Linux 8.4 and later does not need to be updated since it uses the system NSS library, but earlier Red Hat Enterprise Linux 8 extended life streams will need to update Thunderbird as well as NSS.             MITIGATION: Red Hat has investigated whether a possible mitigation exists for this issue, and has not been able to identify a practical example. Please update the affec\",\n  \"severity\": \"critical\",\n  \"packageName\": \"nss-util\",\n  \"packageVersion\": \"3.67.0-7.el8_5\",\n  \"link\": \"https://access.redhat.com/security/cve/CVE-2021-43529\",\n  \"riskFactors\": [\n    \"Remote execution\",\n    \"Attack complexity: low\",\n    \"Attack vector: network\",\n    \"Critical severity\",\n    \"Recent vulnerability\"\n  ],\n  \"impactedVersions\": [\n    \"*\"\n  ],\n  \"publishedDate\": \"2021-12-01T00:00:00Z\",\n  \"discoveredDate\": \"2022-05-18T12:24:22Z\",\n  \"layerTime\": \"2022-05-16T23:12:25Z\"\n}",
          "results": [
            {
              "status": "failed",
              "code_desc": "Package \"nss-util\" should be updated to latest version above impacted versions [\"*\"]",
              "message": "Expected latest version of \"nss-util\"\nDetected vulnerable version \"3.67.0-7.el8_5\" of \"nss-util\"",
              "start_time": "2022-05-18T12:24:22Z"
            },
            {
              "status": "failed",
              "code_desc": "Package \"nss-sysinit\" should be updated to latest version above impacted versions [\"*\"]",
              "message": "Expected latest version of \"nss-sysinit\"\nDetected vulnerable version \"3.67.0-7.el8_5\" of \"nss-sysinit\"",
              "start_time": "2022-05-18T12:24:22Z"
            },
            {
              "status": "failed",
              "code_desc": "Package \"nss\" should be updated to latest version above impacted versions [\"*\"]",
              "message": "Expected latest version of \"nss\"\nDetected vulnerable version \"3.67.0-7.el8_5\" of \"nss\"",
              "start_time": "2022-05-18T12:24:22Z"
            },
            {
              "status": "failed",
              "code_desc": "Package \"nss-softokn\" should be updated to latest version above impacted versions [\"*\"]",
              "message": "Expected latest version of \"nss-softokn\"\nDetected vulnerable version \"3.67.0-7.el8_5\" of \"nss-softokn\"",
              "start_time": "2022-05-18T12:24:22Z"
            },
            {
              "status": "failed",
              "code_desc": "Package \"nss-softokn-freebl\" should be updated to latest version above impacted versions [\"*\"]",
              "message": "Expected latest version of \"nss-softokn-freebl\"\nDetected vulnerable version \"3.67.0-7.el8_5\" of \"nss-softokn-freebl\"",
              "start_time": "2022-05-18T12:24:22Z"
            }
          ]
        }
      ],
      "sha256": "807c8ef1534bb7f3e428db4a40667a6dd37d89f8a48dc6d1f6bb2426ff53f97f"
    }
  ],
  "passthrough": {
    "auxiliary_data": [
      {
        "name": "Twistlock",
        "data": {
          "results": [
            {
              "id": "sha256:b1c0237ebd29860066656372da10d8d7da33b34715986f74b3d5a7e4ba060d1b",
              "distro": "Red Hat Enterprise Linux release 8.6 (Ootpa)",
              "distroRelease": "RHEL8",
              "digest": "sha256:c0274cb1e0c6e92d2ccc1e23bd19b7dddedbaa2da26861c225d4ad6cec5047f4",
              "packages": [
                {
                  "type": "os",
                  "name": "nss-util",
                  "version": "3.67.0-7.el8_5",
                  "licenses": ["MPLv2.0"]
                },
                {
                  "type": "os",
                  "name": "nss-softokn",
                  "version": "3.67.0-7.el8_5",
                  "licenses": ["MPLv2.0"]
                },
                {
                  "type": "os",
                  "name": "nss",
                  "version": "3.67.0-7.el8_5",
                  "licenses": ["MPLv2.0"]
                },
                {
                  "type": "os",
                  "name": "nss-softokn-freebl",
                  "version": "3.67.0-7.el8_5",
                  "licenses": ["MPLv2.0"]
                },
                {
                  "type": "os",
                  "name": "nss-sysinit",
                  "version": "3.67.0-7.el8_5",
                  "licenses": ["MPLv2.0"]
                }
              ],
              "applications": [
                {
                  "name": "asp.net-core",
                  "version": "5.0.17",
                  "path": "/usr/lib64/dotnet/dotnet"
                },
                {
                  "name": ".net-core",
                  "version": "5.0.17",
                  "path": "/usr/lib64/dotnet/dotnet"
                }
              ],
              "complianceScanPassed": true,
              "vulnerabilityScanPassed": true,
              "history": [
                {
                  "created": "2022-05-03T08:38:31Z"
                },
                {
                  "created": "2022-05-03T08:39:27Z"
                },
                {
                  "created": "2022-05-16T23:12:02Z",
                  "instruction": "ARG GOPROXY=http://nexus-repository-manager.nexus-repository-manager.svc.cluster.local:8081/repository/goproxy/ HTTP_PROXY=http://localhost:3128 http_proxy=http://localhost:3128"
                },
                {
                  "created": "2022-05-16T23:12:02Z",
                  "instruction": "ARG GOPROXY=http://nexus-repository-manager.nexus-repository-manager.svc.cluster.local:8081/repository/goproxy/ GOSUMDB=sum.golang.org http://nexus-repository-manager.nexus-repository-manager.svc.cluster.local:8081/repository/gosum HTTP_PROXY=http://localhost:3128 http_proxy=http://localhost:3128"
                }
              ],
              "scanTime": "2022-05-18T12:24:32.855444532Z",
              "scanID": "6284e580d9600f8d0db159e2"
            }
          ],
          "consoleURL": "https://twistlock.test.net/#!/monitor/vulnerabilities/images/ci?search=sha256%3Ab1c0237ebd29860066656372da10d8d7da33b34715986f74b3d5a7e4ba060d1b"
        }
      }
    ]
  }
}
Apache-2.0 | Copyright © 2022 - The MITRE Corporation
Copyright © 2025 Charles Hu