-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2 from openvex/depbreak
Break dependency on old chainguard/vex module
- Loading branch information
Showing
10 changed files
with
131 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,36 +1,131 @@ | ||
| # vexctl: A tool to make VEX work | ||
|
|
||
| `vexctl` is a tool to apply and attest VEX (Vulnerability Exploitability eXchange) | ||
| data. Its purpose is to "turn off" alerts of vulnerabilities known not to affect | ||
| a product. | ||
| `vexctl` is a tool to create, apply and attest VEX (Vulnerability Exploitability | ||
| eXchange) data. Its purpose is to help with the creation and management of | ||
| VEX documents that allow "turning off" security scanner alerts of vulnerabilities | ||
| known not to affect a product. | ||
|
|
||
| VEX can be though as a "negative security advisory". Using VEX, software authors | ||
| can communicate to their users that a vulnerable component has no security | ||
| implications for their product. | ||
|
|
||
| ## Operational Model | ||
|
|
||
| To achieve its mission, `vexctl` has two main modes of operation. One | ||
| helps the user create VEX statements, the second applies the VEX data | ||
| to scanner results. | ||
| To achieve its mission, `vexctl` has three main modes of operation: | ||
|
|
||
| 1. Create VEX documents | ||
| 2. Wrapping VEX documents in signed attestations | ||
| 2. Applying the VEX data to scanner results | ||
|
|
||
| ### 1. Create VEX Statements | ||
|
|
||
| #### Creating New VEX Documents | ||
|
|
||
| VEX data can be created to a file on disk or it can be captured in a | ||
| signed attestation which can be attached to a container image. | ||
|
|
||
| The easiest way to create a VEX document is using the `vexctl create` command: | ||
|
|
||
| ``` | ||
| vex ctl create --product="pkg:apk/wolfi/[email protected]?arch=x86_64" \ | ||
| --vuln="CVE-2023-12345" \ | ||
| --status="not_affected" \ | ||
| --justification="inline_mitigations_already_exist" | ||
| ``` | ||
|
|
||
|
|
||
| The previous invocations creates a vex document with a single statment asserting | ||
| that the WolfiOS package `git-2.38.1-r0` is not affected by CVE-2023-12345 because | ||
| it has already been mitigated in the distribution. | ||
|
|
||
| This is the resulting document: | ||
|
|
||
| ```json | ||
| { | ||
| "@context": "https://openvex.dev/ns", | ||
| "@id": "https://openvex.dev/docs/public/vex-cfaef18d38537412a0307ec266bed56aa88fa58b7c1f2c6b8c9ef997028ba4bd", | ||
| "author": "Unknown Author", | ||
| "role": "Document Creator", | ||
| "timestamp": "2023-01-10T20:24:50.498233798-06:00", | ||
| "version": "1", | ||
| "statements": [ | ||
| { | ||
| "vulnerability": "CVE-2023-12345", | ||
| "products": [ | ||
| "pkg:apk/wolfi/[email protected]?arch=x86_64" | ||
| ], | ||
| "status": "not_affected", | ||
| "justification": "component_not_present" | ||
| } | ||
| ] | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| vexctl can create VEX documents from three different sources: | ||
|
|
||
| 1. From the command line, as shown | ||
| 2. From a _golden file_ of predefined rules | ||
| 3. From merging other vex documents into a new one | ||
|
|
||
| The data is generated from a known rule set (the Golden Data) which is | ||
| reused and reapplied to new releases of the same project. | ||
|
|
||
| #### Generation Examples | ||
| #### Merging Existing Documents | ||
|
|
||
| When more than one stake holder is issuing VEX metadata about a piece of software, | ||
| vexctl can merge the documents to get the most up-to-date impact assessment of | ||
| a vulnerability. The following example can be run using the test documents found | ||
| in this repository: | ||
|
|
||
| ``` | ||
| vexctl merge --product=pkg:apk/wolfi/[email protected] \ | ||
| pkg/ctl/testdata/document1.vex.json \ | ||
| pkg/ctl/testdata/document2.vex.json | ||
| ``` | ||
| The resulting document combines the VEX statements that express data about | ||
| `[email protected]` into a single document that tells the whole story of how CVE-1234-5678 | ||
| was `under_investigation` and then `fixed` four hours later: | ||
|
|
||
| ```json | ||
| { | ||
| "@context": "https://openvex.dev/ns", | ||
| "@id": "https://openvex.dev/docs/public/merged-vex-67124ea942ef30e1f42f3f2bf405fbbc4f5a56e6e87684fc5cd957212fa3e025", | ||
| "author": "Unknown Author", | ||
| "role": "Document Creator", | ||
| "timestamp": "2023-01-10T20:36:55.524170935-06:00", | ||
| "version": "1", | ||
| "statements": [ | ||
| { | ||
| "vulnerability": "CVE-1234-5678", | ||
| "timestamp": "2022-12-22T16:36:43-05:00", | ||
| "products": [ | ||
| "pkg:apk/wolfi/[email protected]" | ||
| ], | ||
| "status": "under_investigation" | ||
| }, | ||
| { | ||
| "vulnerability": "CVE-1234-5678", | ||
| "timestamp": "2022-12-22T20:56:05-05:00", | ||
| "products": [ | ||
| "pkg:apk/wolfi/[email protected]" | ||
| ], | ||
| "status": "affected" | ||
| } | ||
| ] | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| #### 2. Attesting Examples | ||
|
|
||
| ``` | ||
| # Attest and attach vex statements in mydata.vex.json to a container image: | ||
| vexctl attest --attach --sign mydata.vex.json cgr.dev/image@sha256:e4cf37d568d195b4.. | ||
| ``` | ||
|
|
||
| ### 2. VEXing a Results Set | ||
| ### 3. VEXing a Results Set | ||
|
|
||
| Using statements in a VEX document or from an attestation, `vexctl` will filter | ||
| security scanner results to remove _vexed out_ entries. | ||
|
|
@@ -91,14 +186,14 @@ will be filtered out. | |
|
|
||
| ## Build vexctl | ||
|
|
||
| To build `vexctl` clone this repository and run simply run make. | ||
| To build `vexctl`, clone this repository and run simply run make. | ||
|
|
||
| ```console | ||
| git clone [email protected]:chainguard-dev/vex.git | ||
| git clone [email protected]:openvex/vexctl | ||
| cd vex | ||
| make | ||
|
|
||
| ./vexctl version | ||
| /vexctl version | ||
| _ _ _____ __ __ _____ _____ _ | ||
| | | | || ___|\ \ / // __ \|_ _|| | | ||
| | | | || |__ \ V / | / \/ | | | | | ||
|
|
@@ -107,11 +202,11 @@ make | |
| \___/ \____/ \/ \/ \____/ \_/ \_____/ | ||
| vexctl: A tool for working with VEX data | ||
|
|
||
| GitVersion: devel | ||
| GitCommit: unknown | ||
| GitTreeState: unknown | ||
| BuildDate: unknown | ||
| GoVersion: go1.19 | ||
| GitVersion: v0.1.0-6-gf32c652-dirty | ||
| GitCommit: f32c65225aa93f03c6bd84af5dec9294c9b8ed3a | ||
| GitTreeState: dirty | ||
| BuildDate: 2023-01-11T02:11:56Z | ||
| GoVersion: go1.19.4 | ||
| Compiler: gc | ||
| Platform: linux/amd64 | ||
| ``` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters