Extended VEX Spec v0.1.0

Welcome to the VexGen wiki!

Introduction

The Extended Vulnerability Exploitability eXchange (VEX) provides as much information as possible about a vulnerability. Using as base a Vulnerability Exploitability eXchange (VEX) in OpenVEX format, helping to make vulnerability status reporting a less complex process.

Extended VEX Documents

A Extended VEX document contains structured information grouped into different statements, one for each statement (vulnerability) appearing in the VEX.

A Sample Scenario

As an example, consider the following hypothetical scenario:

1. The author of a software is notified of a new CVE related to his product.
2. The author has to verify whether the CVE actually affects the product.
3. Once verified, it specifies the status and other properties in the VEX, for the users of the product.

The problem is that step 2 is a human task that becomes a complex process. By providing CVE-related information such as current exploits, CWEs and attack vector, the complexity of the task could be reduced. And further, one could prioritise those more acute cases that should be dealt with first.

Extended VEX Example

{
  "@context": "https://github.com/GermanMT/vexgen/wiki/Extended-VEX-Spec-v0.1.0",
  "@id": "https://github.com/GermanMT/VexGen",
  "author": "",
  "role": "Generate Automated VEX with Depex",
  "timestamp": "2023-01-08T18:02:03.647787998-06:00",
  "last_updated": "2023-01-08T18:02:03.647787998-06:00",
  "version": 1,
  "tooling": "https://github.com/GermanMT/vexgen",
  "extended_statements": [
    {
      "affected_component": "pycrypto",
      "affected_component_version": "2.0.1",
      "vulnerability": {
        "@id": "https://nvd.nist.gov/vuln/detail/CVE-2018-6594",
        "name": "CVE-2018-6594",
        "description": "lib/Crypto/PublicKey/ElGamal.py in PyCrypto through 2.6.1 generates weak ElGamal key parameters, which allows attackers to obtain sensitive information by reading ciphertext data (i.e., it does not have semantic security in face of a ciphertext-only attack). The Decisional Diffie-Hellman (DDH) assumption does not hold for PyCrypto's ElGamal implementation.",
        "CVSS": {
          "vuln_impact": 3.6,
          "version": "3.0",
          "attack_vector": "CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N"
        },
        "CWEs": [
          {
            "@id": "https://cwe.mitre.org/data/definitions/416326.html",
            "name": "326",
            "description": "A weak encryption scheme can be subjected to brute force attacks that have a reasonable chance of succeeding using current attack methods and resources.",
            "consequences": {
              "Scope": [
                "Access Control",
                "Confidentiality"
              ],
              "Impact": [
                "Bypass Protection Mechanism",
                "Read Application Data"
              ],
              "Note": "An attacker may be able to decrypt the data using brute force attacks."
            },
            "detection_methods": {
              "@Detection_Method_ID": "DM-14",
              "Method": "Automated Static Analysis",
              "Description": "Automated static analysis, commonly referred to as Static Application Security Testing (SAST), can find some instances of this weakness by analyzing source code (or binary/compiled code) without having to execute it. Typically, this is done by building a model of data flow and control flow, then searching for potentially-vulnerable patterns that connect \"sources\" (origins of input) with \"sinks\" (destinations where the data interacts with external components, a lower layer such as the OS, etc.)",
              "Effectiveness": "High"
            },
            "potential_mitigations": {
              "Phase": "Architecture and Design",
              "Description": "Use an encryption scheme that is currently considered to be strong by experts in the field."
            }
          }
        ]
      },
      "recheable_code": [
        {
          "path_to_file": "vulnerability_assisting_information/main/files/paramiko_test.py",
          "used_artifacts": [
            {
              "artifact_name": "Transport",
              "used_in_lines": [
                3,
                21
              ]
            }
          ]
        }
      ],
      "exploits": [
        {
          "@id": "https://www.seebug.org/vuldb/ssvid-60160",
          "description": "BUGTRAQ  ID: 53687\r\nCVE ID: CVE-2012-2417\r\n\r\nPyCrypto\u662f\u4f7f\u7528Python\u7f16\u5199\u7684\u52a0\u5bc6\u5de5\u5177\u5305\u3002\r\n\r\nPyCrypto 2.5\u4e4b\u524d\u7248\u672c\u5728\u4f7f\u7528ElGamal\u65b9\u6848\u751f\u6210\u5bc6\u94a5\u65f6\u5b58\u5728\u9519\u8bef\uff0c\u53ef\u9020\u6210\u7f29\u51cf\u5bc6\u94a5\u7a7a\u95f4\uff0c\u53ef\u88ab\u5229\u7528\u751f\u6210\u79c1\u94a5\uff0c\u83b7\u53d6\u654f\u611f\u4fe1\u606f\u3002\n0\npython 2.5.x\n\u5382\u5546\u8865\u4e01\uff1a\r\n\r\nPython\r\n------\r\n\u76ee\u524d\u5382\u5546\u5df2\u7ecf\u53d1\u5e03\u4e86\u5347\u7ea7\u8865\u4e01\u4ee5\u4fee\u590d\u8fd9\u4e2a\u5b89\u5168\u95ee\u9898\uff0c\u8bf7\u5230\u5382\u5546\u7684\u4e3b\u9875\u4e0b\u8f7d\uff1a\r\n\r\nwww.python.org",
          "payload": ""
        }
      ],
      "priority": 2.8,
      "timestamp": "2023-01-08T18:02:03.647787998-06:00",
      "last_updated": "2023-01-08T18:02:03.647787998-06:00",
      "status": "not_affected",
      "justification": "component_not_present"
    }
  ]
}

Extendad VEX Struct Fields

The following table lists the fields in the document struct:

Field	Required	Description
@context	✓	The URL linking to the Extended VEX context definition.
@id	✓	The IRI identifying the VEX document.
author	✓	Author is the identifier for the author of the VEX statement. This field should ideally be a machine readable identifier such as an IRI, email address, etc. author MUST be an individual or organization. author identity SHOULD be cryptographically associated with the signature of the VEX document or other exchange mechanism.
role	✕	role describes the role of the document author.
timestamp	✓	Timestamp defines the time at which the document was issued.
last_updated	✕	Date of last modification to the document.
version	✓	Version is the document version. It must be incremented when any content within the Extended VEX document changes.
tooling	✕	Tooling expresses how the VEX document and contained VEX statements were generated. It may specify tools or automated processes used in the document or statement generation.

Statement Assiting Information

The following table lists the fields in the assisting information statement struct:

Field	Required	Description
affected_component	✓	The name of the affected third party component.
affected_component_version	✓	The version of the affected third party component.
vulnerability	✓	The basic information about the vulnerability.
reachable_code	✕	Code where de affected component is used. Taking into account that the artefact of the affected component is listed in the vulnerability information.
exploits	✕	Exploits found for the vulnerability.
priority	✓	The priority with which vulnerability should be addressed.
status	✓	A statement MAY convey information about how status was determined and MAY reference other VEX information. See Status Labels below for valid values.
justification	✓	or statements conveying a not_affected status, a VEX statement MUST include either a status justification informing why the product is not affected by the vulnerability. Justifications are fixed labels defined by VEX. See Status Justifications below for valid values.

Vulnerability Fields

The following table lists the fields in the vulnerability struct:

Field	Required	Description
@id	✓	The IRI identifying the CVE.
name	✓	The CVE ID of the vulnerability.
description	✓	The description of the CVE.
CVSS	✕	The impact score and the attack vector provided by the CVSS.
CWEs	✕	The list of CWEs.

CWE Fields

The following table lists the fields in the CWE struct:

Field	Required	Description
@id	✓	The IRI identifying the CWE.
name	✓	The CWE ID of the vulnerability.
description	✓	The description of the CWE.
background_detail	✕	The background deatils about a CWE.
consequences	✕	Risk consequences of a CWE.
detection_methods	✕	Methods to detect a CWE.
potential_mitigations	✕	Mitigation strategies for vulnerabilities related to a CWE. For each stage of the software development lifecycle.
demonstrative_examples	✕	Examples of code demonstrating how to exploit or patch CWE-related vulnerabilities.

Reachable Code Fields

The following table lists the fields in the reachable code struct:

Field	Required	Description
path_to_file	✕	The path to the file where artefacts of the affected component have been found.
used_artifacts	✕	The name of the used artefact and the lines where it has been used.

Exploit Fields

The following table lists the fields in the exploit struct:

Field	Required	Description
@id	✕	The IRI identifying the exploit.
description	✕	The description of the exploit.
payload	✕	The payload code of the exploit.

Status Labels

Status labels inform the impact of a vulnerability in the products listed in a statement. Security tooling such as vulnerability scanners consuming OpenVEX documents can key on the status labels to alter their behavior when a vulnerable component is detected. Security dashboards can provide users and auditors with contextual data about the evolution of the vulnerability impact.

Label	Description
not_affected	No remediation is required regarding this vulnerability. A not_affected status required the addition of a justification to the statement.
affected	Actions are recommended to remediate or address this vulnerability.
fixed	These product versions contain a fix for the vulnerability.
under_investigation	It is not yet known whether these product versions are affected by the vulnerability. Updates should be provided in further VEX documents as knowledge evolves.

Status Justifications

When assessing risk, consumers of a not_affected software product can know why the vulnerability is not affected by reading the justification label associated with the VEX statement. These labels are predefined and machine-readable to enable automated uses such as deployment policies. The current label catalog was defined by the VEX Working Group and published in the Status Justifications document on July 2022.

Label	Description
component_not_present	The product is not affected by the vulnerability because the component is not included. The status justification may be used to preemptively inform product users who are seeking to understand a vulnerability that is widespread, receiving a lot of attention, or is in similar products.
vulnerable_code_not_present	The vulnerable component is included in artifact, but the vulnerable code is not present. Typically, this case occurs when source code is configured or built in a way that excluded the vulnerable code.
vulnerable_code_not_in_execute_path	The vulnerable code (likely in subcomponents) can not be executed as it is used by the product. Typically, this case occurs when the product includes the vulnerable subcomponent but does not call or use the vulnerable code.
vulnerable_code_cannot_be_controlled_by_adversary	The vulnerable code cannot be controlled by an attacker to exploit the vulnerability. This justification could be difficult to prove conclusively.
inline_mitigations_already_exist	The product includes built-in protections or features that prevent exploitation of the vulnerability. These built-in protections cannot be subverted by the attacker and cannot be configured or disabled by the user. These mitigations completely prevent exploitation based on known attack vectors. This justification could be difficult to prove conclusively. History is littered with examples of mitigation bypasses, typically involving minor modifications of existing exploit code.