vex2doc 0.1.0

VEX documentation tool

VEX2DOC

VEX2DOC documents and summarises the components within a VEX (Vulnerability Expolitability eXchange) document). VEXs are supported in a number of formats including CSAF and CycloneDX, OpenVEX and SPDX

Installation

To install use the following command:

pip install vex2doc

Alternatively, just clone the repo and install dependencies using the following command:

pip install -U -r requirements.txt

The tool requires Python 3 (3.8+). It is recommended to use a virtual python environment especially if you are using different versions of python. virtualenv is a tool for setting up virtual python environments which allows you to have all the dependencies for the tool set up in a single environment, or have different environments set up for testing using different versions of Python.

Usage

usage: vex2doc [-h] [-i INPUT_FILE] [--debug] [-f {console,excel,html,json,markdown,pdf}] [-o OUTPUT_FILE] [-V]

VEX2doc generates documentation for a VEX artefact.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Input:
  -i INPUT_FILE, --input-file INPUT_FILE
                        Name of VEX file

Output:
  --debug               add debug information
  -f {console,excel,html,json,markdown,pdf}, --format {console,excel,html,json,markdown,pdf}
                        Output format (default: output to console)
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        output filename (default: output to stdout)

Operation

The --input-file option is used to specify the VEX to be processed. The type of file VEX is automatically determined by checking for content in the following order:

• CSAF
• CycloneDX
• OpenVEX
• SPDX

The --output-file option is used to control the destination of the output generated by the tool. The default is to report to the console, but it can also be stored in a file (specified using --output-file option).

Selecting the html format option will create a HTML body document which uses the Bootstrap framework.

The --include-license option is used to indicate if the text for the licenses is to be included in the output.

Example

Given the following VEX (acme.json) in CycloneDX format

{
  "$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:9f41c36d-ce5c-4a94-b25c-229d66d55bf5",
  "version": 2,
  "metadata": {
    "timestamp": "2024-07-29T22:34:03Z",
    "tools": {
      "components": [
        {
          "name": "lib4vex",
          "version": "0.2.0",
          "type": "application"
        }
      ]
    },
    "authors": [
      {
        "name": "Fred Flintstone",
        "email": "[e-mail]"
      }
    ],
    "properties": [
      {
        "name": "Revision_1",
        "value": "Initial version"
      },
      {
        "name": "Revision_2",
        "value": "Product Review initiated."
      }
    ],
    "component": {
      "type": "application",
      "supplier": {
        "name": "APH_Division"
      },
      "version": "1.0",
      "bom-ref": "CDXRef-DOCUMENT",
      "name": "ACME-Infusion"
    }
  },
  "vulnerabilities": [
    {
      "bom-ref": "pyyaml@6.0.1",
      "id": "CVE-2023-12345",
      "source": {
        "name": "NVD",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2023-12345"
      },
      "published": "2024-07-29T22:34:03Z",
      "updated": "2024-07-29T22:34:03Z",
      "analysis": {
        "state": "not_affected",
        "justification": "code_not_reachable"
      },
      "affects": [
        {
          "ref": "urn:cdx:b355491d-a6e7-499e-a273-071b2ef3d086/1#pyyaml-6.0.1",
          "versions": {
            "version": "6.0.1",
            "status": "unaffected"
          }
        }
      ]
    },
    {
      "bom-ref": "pkg:pypi/defusedxml@0.7.1",
      "id": "CVE-2024-1234",
      "source": {
        "name": "NVD",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2024-1234"
      },
      "published": "2024-07-29T18:22:43Z",
      "updated": "2024-07-29T22:34:03Z",
      "analysis": {
        "state": "in_triage"
      },
      "affects": [
        {
          "ref": "urn:cdx:b355491d-a6e7-499e-a273-071b2ef3d086/1#pkg:pypi/defusedxml@0.7.1"
        }
      ]
    }
  ]
}

The following command will generate a summary of the contents of the VEX to the console.

vex2doc --input-file acme.json 

╭─────────────╮
│ VEX Summary │
╰─────────────╯
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Item              ┃ Details                                                                                                            ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ VEX File          │ acme.json                                                                                                          │
│ VEX Type          │ cyclonedx                                                                                                          │
│ Version           │ 1.6                                                                                                                │
│ Type              │ cyclonedx                                                                                                          │
│ Uuid              │ urn:uuid:9f41c36d-ce5c-4a94-b25c-229d66d55bf5                                                                      │
│ Bom_version       │ 2                                                                                                                  │
│ Created           │ 2024-07-29T22:34:03Z                                                                                               │
│ Creator           │ [['tool', 'lib4vex#0.2.0'], ['person', 'Fred Flintstone#[e-mail]']]                                 │
│ Name              │ ACME-Infusion                                                                                                      │
│ Metadata_type     │ application                                                                                                        │
│ Bom-ref           │ CDXRef-DOCUMENT                                                                                                    │
│ Metadata_version  │ 1.0                                                                                                                │
│ Metadata_supplier │ APH_Division                                                                                                       │
│ Property          │ [{'name': 'Revision_1', 'value': 'Initial version'}, {'name': 'Revision_2', 'value': 'Product Review initiated.'}] │
│ Supplier          │ Fred Flintstone                                                                                                    │
│ Supplier_url      │ [e-mail]                                                                                            │
└───────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╭─────────────────╮
│ Product Summary │
╰─────────────────╯
┏━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Item    ┃ Details       ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ Name    │ ACME-Infusion │
│ Version │ 1.0           │
└─────────┴───────────────┘
╭─────────────────────────╮
│ Vulnerabilities Summary │
╰─────────────────────────╯
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Bom-ref                   ┃ Product             ┃ Release ┃ Id             ┃ Source-name ┃ Source-url                   ┃ Created              ┃ Updated              ┃ Status       ┃ Justification      ┃ Bom_link                     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ pyyaml@6.0.1              │ pyyaml              │ 6.0.1   │ CVE-2023-12345 │ NVD         │ https://nvd.nist.gov/vuln/d… │ 2024-07-29T22:34:03Z │ 2024-07-29T22:34:03Z │ not_affected │ code_not_reachable │ urn:cdx:b355491d-a6e7-499e-… │
│ pkg:pypi/defusedxml@0.7.1 │ pkg:pypi/defusedxml │ 0.7.1   │ CVE-2024-1234  │ NVD         │ https://nvd.nist.gov/vuln/d… │ 2024-07-29T18:22:43Z │ 2024-07-29T22:34:03Z │ in_triage    │                    │ urn:cdx:b355491d-a6e7-499e-… │
└───────────────────────────┴─────────────────────┴─────────┴────────────────┴─────────────┴──────────────────────────────┴──────────────────────┴──────────────────────┴──────────────┴────────────────────┴──────────────────────────────┘

Licence

Licenced under the Apache 2.0 Licence.

Limitations

The tool has the following limitations

• Invalid VEX documents will result in unpredictable results.

Feedback and Contributions

Bugs and feature requests can be made via GitHub Issues.