docs: documentation regarding vex commands (intel#4227)

ffontaine · Jul 8, 2024 · 12e655e · 12e655e
1 parent 377cf0f
commit 12e655e
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 5 deletions.
diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt
@@ -103,6 +103,7 @@ CQA
 crond
 cronie
 cryptsetup
+csaf
 csrc
 css
 csv
@@ -172,6 +173,7 @@ exfatprogs
 exim
 exiv
 expat
+exploitability
 Exploitablity
 f
 faad
@@ -481,6 +483,7 @@ openssh
 openssl
 opensuse
 openswan
+openvex
 openvpn
 openwrt
 ossl
@@ -580,6 +583,7 @@ runc
 rust
 sakshatshinde
 samba
+samplevex
 sandboxing
 sane
 sanketsaurav
@@ -692,6 +696,7 @@ utkarsh
 utm
 varnish
 venv
+VEXs
 vfy
 vim
 virtualenv
@@ -703,6 +708,8 @@ vorbis
 VPkg
 vsftpd
 Vulnerabity
+vulnerablities
+vulnerablity
 webkitgtk
 webserver
 website
@@ -723,6 +730,7 @@ wpa
 wsl
 www
 wzao
+Xchange
 XDRAGON
 xerces
 Xiph

diff --git a/README.md b/README.md
@@ -46,6 +46,7 @@ For more details, see our [documentation](https://cve-bin-tool.readthedocs.io/en
     - [Finding known vulnerabilities using the binary scanner](#finding-known-vulnerabilities-using-the-binary-scanner)
     - [Scanning an SBOM file for known vulnerabilities](#scanning-an-sbom-file-for-known-vulnerabilities)
     - [Generating an SBOM](#generating-an-sbom)
+    - [Generating a VEX](#generating-a-vex)
     - [Triaging vulnerabilities](#triaging-vulnerabilities)
     - [Using the tool offline](#using-the-tool-offline)
     - [Using CVE Binary Tool in GitHub Actions](#using-cve-binary-tool-in-github-actions)
@@ -120,6 +121,19 @@ The generated SBOM will include product name, version and supplier (where availa
 
 The [SBOM generation how-to guide](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/sbom_generation.md) provides additional SBOM generation examples.
 
+### Generating a VEX
+
+As well as scanning VEX, CVE Binary Tool can be used to generate an VEX from a scan as follows:
+
+```bash
+cve-bin-tool  --vex-type <vex_type> --vex-output <vex_filename> <other scan options as required>
+```
+
+Valid VEX types are [CSAF](https://oasis-open.github.io/csaf-documentation/), [CycloneDX](https://cyclonedx.org/capabilities/vex/) and [OpenVEX](https://edu.chainguard.dev/open-source/sbom/what-is-openvex/).
+
+
+The [VEX generation how-to guide](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/vex_generation.md) provides additional VEX generation examples.
+
 ### Triaging vulnerabilities
 
 The `--triage-input-file` option can be used to add extra triage data like remarks, comments etc. while scanning a directory so that output will reflect this triage data and you can save time of re-triaging (Usage: `cve-bin-tool --triage-input-file test.vex /path/to/scan`).
@@ -447,6 +461,9 @@ Input:
                         specify type of software bill of materials (sbom) (default: spdx)
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--sbom-file-sbom_file">--sbom-file SBOM_FILE</a>
                         provide sbom filename
+  <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#d--vex-file-vex_file">--vex-file VEX_FILE</a>
+                        provide vex filename used for triage processing, the type of vex will be automatically detected.
+
 
 Output:
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#quiet-mode">-q, --quiet</a>           suppress output
@@ -477,14 +494,16 @@ Output:
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#-b-distro_name-distro_version_name---backport-fix-distro_name-distro_version_name">-b [<distro_name>-<distro_version_name>], --backport-fix [<distro_name>-<distro_version_name>]</a>
                         Lists backported fixes if available from Linux distribution
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--affected-versions">--affected-versions</a>   Lists versions of product affected by a given CVE (to facilitate upgrades)
-  <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--vex-vex_file">--vex VEX</a>             Provide vulnerability exchange (vex) filename
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--sbom-output-sbom_output">--sbom-output SBOM_OUTPUT</a>
                         provide software bill of materials (sbom) filename to generate
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--sbom-type">--sbom-type {spdx,cyclonedx}</a>
                         specify type of software bill of materials (sbom) to generate (default: spdx)
   <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--sbom-format">--sbom-format {tag,json,yaml}</a>
                         specify format of software bill of materials (sbom) to generate (default: tag)
-
+  <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--vex-type">--vex-type {cyclonedx, csaf, openvex}</a>
+                        specify type of vulnerability exploitability exchange (vex) to generate (default: cyclonedx)
+  <a href="https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--vex-output-vex_output">--vex-ouptput VEX_OUTPUT</a>
+                        Provide vulnerability exploitability exchange (vex) filename to generate
 Merge Report:
   Arguments related to Intermediate and Merged Reports
 

diff --git a/doc/MANUAL.md b/doc/MANUAL.md
@@ -42,6 +42,7 @@
     - [-i INPUT\_FILE, --input-file INPUT\_FILE](#-i-input_file---input-file-input_file)
     - [--triage-input-file INPUT\_FILE](#--triage-input-file-input_file)
     - [--sbom-file SBOM\_FILE](#--sbom-file-sbom_file)
+    - [--vex-file VEX\_FILE](#--vex-file-vex_file)
     - [-L PACKAGE\_LIST, --package-list PACKAGE\_LIST](#-l-package_list---package-list-package_list)
     - [-C CONFIG, --config CONFIG](#-c-config---config-config)
       - [Yaml example file](#yaml-example-file)
@@ -58,10 +59,11 @@
     - [-A \[\<distro\_name\>-\<distro\_version\_name\>\], --available-fix \[\<distro\_name\>-\<distro\_version\_name\>\]](#-a-distro_name-distro_version_name---available-fix-distro_name-distro_version_name)
     - [-b \[\<distro\_name\>-\<distro\_version\_name\>\], --backport-fix \[\<distro\_name\>-\<distro\_version\_name\>\]](#-b-distro_name-distro_version_name---backport-fix-distro_name-distro_version_name)
     - [--affected-versions](#--affected-versions)
-    - [--vex VEX\_FILE](#--vex-vex_file)
     - [--sbom-output SBOM\_OUTPUT](#--sbom-output-sbom_output)
     - [--sbom-type](#--sbom-type)
     - [--sbom-format](#--sbom-format)
+    - [--vex-type](#--vex-type)
+    - [--vex-output VEX\_OUTPUT](#--vex-output)
     - [Output verbosity](#output-verbosity)
       - [Quiet Mode](#quiet-mode)
       - [Logging modes](#logging-modes)
@@ -77,6 +79,7 @@
     - [-x, --extract](#-x---extract)
     - [--report](#--report)
   - [SBOM](#sbom)
+  - [VEX](#vex)
   - [Language Specific checkers](#language-specific-checkers)
     - [Java](#java)
     - [Javascript](#javascript)
@@ -168,13 +171,16 @@ which is useful if you're trying the latest code from
       -b [<distro_name>-<distro_version_name>], --backport-fix [<distro_name>-<distro_version_name>]
                             Lists backported fixes if available from Linux distribution
       --affected-versions   Lists versions of product affected by a given CVE (to facilitate upgrades)
-      --vex VEX             Provide vulnerability exchange (vex) filename
       --sbom-output SBOM_OUTPUT
                             provide software bill of materials (sbom) filename to generate
       --sbom-type {spdx,cyclonedx}
                             specify type of software bill of materials (sbom) to generate (default: spdx)
       --sbom-format {tag,json,yaml}
                             specify format of software bill of materials (sbom) to generate (default: tag)
+      --vex-type {cyclonedx, csaf, openvex}
+                            specify type of vulnerability exploitability exchange (vex) to generate (default: cyclonedx)
+      --vex-output VEX_OUTPUT
+                            provide vulnerability exploitability exchange (vex) filename to generate
 
     Merge Report:
       Arguments related to Intermediate and Merged Reports
@@ -847,6 +853,19 @@ insensitive. To determine the format of the SBOM file, the following filename co
 
 The type of SBOM is assumed to be SPDX unless specified using the `--sbom` option.
 
+### --vex-file VEX_FILE
+
+This option is used as a part of a filtering/triaging process using Vulnerablity Exploitability eXchange (VEX) file. The tool supports VEX files in given formats including
+[CSAF](https://oasis-open.github.io/csaf-documentation/), [CycloneDX](https://cyclonedx.org/capabilities/vex/) and [OpenVEX](https://edu.chainguard.dev/open-source/sbom/what-is-openvex/)
+
+| SBOM Type | Format   | Filename extension |
+| --------- | -------- | ------------------ |
+| CycloneDX | JSON     | .json              |
+| CSAF      | JSON     | .json              |
+| OpenVEX   | JSON     | .json              |
+
+The type of VEX is automatically detected.
+
 ### -L PACKAGE_LIST, --package-list PACKAGE_LIST
 
 This option runs a CVE scan on installed packages listed in a package list. It takes a python package list (requirements.txt) or a package list of packages of systems that has dpkg, pacman or rpm package manager as an input for the scan. This option is much faster and detects more CVEs than the default method of scanning binaries.
@@ -1208,13 +1227,20 @@ ubuntu-xenial
 
 This options reports the versions of a product affected by a given CVE.
 
-### --vex VEX_FILE
+### --vex-output VEX_FILE
 
 This option allows you to specify the filename for a Vulnerability Exchange (VEX)
 file which contains all the reported vulnerabilities detected by the scan. This file is typically
 updated (outside of the CVE Binary tool) to record the results of a triage activity
 and can be used as a file with `--input-file` parameter.
 
+### --vex-type
+
+This option is used in combination with the `--vex-output` parameter and allows you to specify the
+type of Vulnerability Exploitability eXchange (VEX) to be generated. VEXs can be generated in [CSAF](https://oasis-open.github.io/csaf-documentation/), [CycloneDX](https://cyclonedx.org/capabilities/vex/) and [OpenVEX](https://edu.chainguard.dev/open-source/sbom/what-is-openvex/) formats.
+
+If this option is not specified, an CycloneDX VEX will be generated.
+
 ### --sbom-output SBOM_OUTPUT
 
 This option allows you to specify the filename for a Software Bill of Material (SBOM) file which contains all of the
@@ -1356,6 +1382,12 @@ SBOMs can be used for many purposes, such as tracking software licenses, identif
 
 You can find the current SBOM for CVE-BIN-TOOL which is updated weekly [here](https://github.com/intel/cve-bin-tool/tree/main/sbom)
 
+
+## VEX
+
+A VEX (Vulnerablity Exploitability eXchange) is document that lists all the vulnerablities found for all the components of a software product, VEX is a companion document to a Software Bill of Materials (SBOM) that helps communicate the exploitability of components with known vulnerabilities in a product and also used as part of filtering/triaging process.
+
+
 ## Language Specific checkers
 
 A number of checkers are available for finding vulnerable components in specific language packages.

diff --git a/doc/how_to_guides/vex_generation.md b/doc/how_to_guides/vex_generation.md
@@ -0,0 +1,44 @@
+# How do I use CVE Binary Tool to generate a VEX?
+
+The cve-bin-tool can be used to generate a Vulnerability Exploitability eXchange (VEX) file, which is a file that contains a list of all vulnerabilities detected by the scan in a standardized format.
+
+## VEX support
+
+The cve-bin-tool generates VEXs in the following formats
+
+| SBOM Type | Format   | Filename extension |
+| --------- | -------- | ------------------ |
+| CycloneDX | JSON     | .json              |
+| CSAF      | JSON     | .json              |
+| OpenVEX   | JSON     | .json              |
+
+
+Details of the formats for each of the supported VEX formats are available for [CSAF](https://oasis-open.github.io/csaf-documentation/), [CycloneDX](https://cyclonedx.org/capabilities/vex/) and [OpenVEX](https://edu.chainguard.dev/open-source/sbom/what-is-openvex/)
+
+## Usage
+
+To generate a VEX, run the tool as shown. See the examples below for details about optional arguments and default values used.
+
+```
+cve-bin-tool --vex-type <vex type> --vex-output <vex filename>
+```
+
+## Examples
+
+Generate a CSAF vex with the name samplevex.json
+
+```
+cve-bin-tool --vex-type csaf --sbom-output samplevex.json .
+```
+
+If the `--vex-type` option is omitted, a VEX is generated in the CycloneDX type. --vex-output is used for providing a filename for output vex file.
+
+```
+cve-bin-tool --vex-output samplevex.json
+```
+
+Generate a OpenVEX vex with the name samplevex.json
+
+```
+cve-bin-tool --vex-type openvex --vex-output samplevex.json
+```