From 46f922078eab4ed9a849d494dd779eca0d7bc9c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adolfo=20Garc=C3=ADa=20Veytia=20=28Puerco=29?= Date: Tue, 10 Jan 2023 20:10:52 -0600 Subject: [PATCH 1/3] Pull openvex/vex @ HEAD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Adolfo García Veytia (Puerco) --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index ae170f1..07cf3ec 100644 --- a/go.mod +++ b/go.mod @@ -3,8 +3,8 @@ module github.com/openvex/vexctl go 1.19 require ( - chainguard.dev/vex v0.1.0 github.com/google/go-containerregistry v0.12.1 + github.com/openvex/vex v0.1.1-0.20230110080744-b295df0b0ef1 github.com/owenrumney/go-sarif v1.1.1 github.com/secure-systems-lab/go-securesystemslib v0.4.0 github.com/sigstore/cosign v1.13.1 diff --git a/go.sum b/go.sum index 4b1b79f..88e208f 100644 --- a/go.sum +++ b/go.sum @@ -2,8 +2,6 @@ bazil.org/fuse v0.0.0-20180421153158-65cc252bf669/go.mod h1:Xbm+BRKSBEpa4q4hTSxo bitbucket.org/creachadair/shell v0.0.6/go.mod h1:8Qqi/cYk7vPnsOePHroKXDJYmb5x7ENhtiFtfZq8K+M= bitbucket.org/creachadair/shell v0.0.7 h1:Z96pB6DkSb7F3Y3BBnJeOZH2gazyMTWlvecSD4vDqfk= bitbucket.org/creachadair/shell v0.0.7/go.mod h1:oqtXSSvSYr4624lnnabXHaBsYW6RD80caLi2b3hJk0U= -chainguard.dev/vex v0.1.0 h1:nxOUH65+OjBQ2Vph+8u5qpf7YRyT2XUtLnp27Q43XcM= -chainguard.dev/vex v0.1.0/go.mod h1:uNzgmAtDI3UkKkzJrVetp5bq6bpJ5vvYU4JybJxaF6I= cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw= cloud.google.com/go v0.34.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw= cloud.google.com/go v0.38.0/go.mod h1:990N+gfupTy94rShfmMCWGDn0LpTmnzTp2qbd1dvSRU= @@ -1039,6 +1037,8 @@ github.com/opentracing/opentracing-go v1.0.2/go.mod h1:UkNAQd3GIcIGf0SeVgPpRdFSt github.com/opentracing/opentracing-go v1.1.0/go.mod h1:UkNAQd3GIcIGf0SeVgPpRdFStlNbqXla1AfSYxPUl2o= github.com/opentracing/opentracing-go v1.2.0 h1:uEJPy/1a5RIPAJ0Ov+OIO8OxWu77jEv+1B0VhjKrZUs= github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc= +github.com/openvex/vex v0.1.1-0.20230110080744-b295df0b0ef1 h1:MlPltqDIi3Q2eshmLhJ7Hhvne4mR2lGnvb7z+rC5Akk= +github.com/openvex/vex v0.1.1-0.20230110080744-b295df0b0ef1/go.mod h1:I3ZjbXZAjc3jM+qCXhA3lu0neNmPEzpH8ZwAjfW4TG0= github.com/openzipkin-contrib/zipkin-go-opentracing v0.4.5/go.mod h1:/wsWhb9smxSfWAKL3wpBW7V8scJMt8N8gnaMCS9E/cA= github.com/openzipkin/zipkin-go v0.1.6/go.mod h1:QgAqvLzwWbR/WpD4A3cGpPtJrZXNIiJc5AZX7/PBEpw= github.com/openzipkin/zipkin-go v0.2.1/go.mod h1:NaW6tEwdmWMaCDZzg8sh+IBNOxHMPnhQw8ySjnjRyN4= From f32c65225aa93f03c6bd84af5dec9294c9b8ed3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adolfo=20Garc=C3=ADa=20Veytia=20=28Puerco=29?= Date: Tue, 10 Jan 2023 20:11:56 -0600 Subject: [PATCH 2/3] Shift dependency to openvex/vex MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit breaks the dependency on the old chainguard/vex module and changes it to the new openvex modules. Signed-off-by: Adolfo García Veytia (Puerco) --- internal/cmd/attest.go | 2 +- internal/cmd/create.go | 2 +- internal/cmd/filter.go | 7 ++++--- internal/cmd/merge.go | 5 +++-- pkg/ctl/ctl.go | 6 +++--- pkg/ctl/ctl_test.go | 4 ++-- pkg/ctl/implementation.go | 6 +++--- 7 files changed, 17 insertions(+), 15 deletions(-) diff --git a/internal/cmd/attest.go b/internal/cmd/attest.go index 5ffb805..4a3a0e1 100644 --- a/internal/cmd/attest.go +++ b/internal/cmd/attest.go @@ -11,7 +11,7 @@ import ( "fmt" "os" - "chainguard.dev/vex/pkg/ctl" + "github.com/openvex/vexctl/pkg/ctl" "github.com/spf13/cobra" ) diff --git a/internal/cmd/create.go b/internal/cmd/create.go index 673d279..897e361 100644 --- a/internal/cmd/create.go +++ b/internal/cmd/create.go @@ -13,7 +13,7 @@ import ( "github.com/spf13/cobra" - "chainguard.dev/vex/pkg/vex" + "github.com/openvex/vex/pkg/vex" ) type createOptions struct { diff --git a/internal/cmd/filter.go b/internal/cmd/filter.go index d74f062..873d847 100644 --- a/internal/cmd/filter.go +++ b/internal/cmd/filter.go @@ -14,9 +14,10 @@ import ( "github.com/spf13/cobra" - "chainguard.dev/vex/pkg/ctl" - "chainguard.dev/vex/pkg/sarif" - "chainguard.dev/vex/pkg/vex" + "github.com/openvex/vex/pkg/sarif" + "github.com/openvex/vex/pkg/vex" + + "github.com/openvex/vexctl/pkg/ctl" ) type filterOptions struct { diff --git a/internal/cmd/merge.go b/internal/cmd/merge.go index 2945ef9..1c62652 100644 --- a/internal/cmd/merge.go +++ b/internal/cmd/merge.go @@ -12,8 +12,9 @@ import ( "github.com/spf13/cobra" - "chainguard.dev/vex/pkg/ctl" - "chainguard.dev/vex/pkg/vex" + "github.com/openvex/vex/pkg/vex" + + "github.com/openvex/vexctl/pkg/ctl" ) type mergeOptions struct { diff --git a/pkg/ctl/ctl.go b/pkg/ctl/ctl.go index d995043..5550c85 100644 --- a/pkg/ctl/ctl.go +++ b/pkg/ctl/ctl.go @@ -9,9 +9,9 @@ import ( "context" "fmt" - "chainguard.dev/vex/pkg/attestation" - "chainguard.dev/vex/pkg/sarif" - "chainguard.dev/vex/pkg/vex" + "github.com/openvex/vex/pkg/attestation" + "github.com/openvex/vex/pkg/sarif" + "github.com/openvex/vex/pkg/vex" ) type VexCtl struct { diff --git a/pkg/ctl/ctl_test.go b/pkg/ctl/ctl_test.go index d29d6a5..d23f4be 100644 --- a/pkg/ctl/ctl_test.go +++ b/pkg/ctl/ctl_test.go @@ -11,8 +11,8 @@ import ( "github.com/stretchr/testify/require" - "chainguard.dev/vex/pkg/sarif" - "chainguard.dev/vex/pkg/vex" + "github.com/openvex/vex/pkg/sarif" + "github.com/openvex/vex/pkg/vex" ) func TestVexReport(t *testing.T) { diff --git a/pkg/ctl/implementation.go b/pkg/ctl/implementation.go index b1cc264..9f4080c 100644 --- a/pkg/ctl/implementation.go +++ b/pkg/ctl/implementation.go @@ -30,9 +30,9 @@ import ( "github.com/sirupsen/logrus" "sigs.k8s.io/release-utils/util" - "chainguard.dev/vex/pkg/attestation" - "chainguard.dev/vex/pkg/sarif" - "chainguard.dev/vex/pkg/vex" + "github.com/openvex/vex/pkg/attestation" + "github.com/openvex/vex/pkg/sarif" + "github.com/openvex/vex/pkg/vex" ) const IntotoPayloadType = "application/vnd.in-toto+json" From 0c5490164bec6cc8e401e7ef5aca6d9f4d721a2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adolfo=20Garc=C3=ADa=20Veytia=20=28Puerco=29?= Date: Tue, 10 Jan 2023 20:44:16 -0600 Subject: [PATCH 3/3] Update README to openvex org and latest features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Adolfo García Veytia (Puerco) --- README.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 111 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 257a7ac..d55b4b5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ # 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 @@ -10,19 +11,113 @@ 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/git@2.38.1-r0?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/trivy@0.36.1-r0?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/bash@1.0.0 \ + pkg/ctl/testdata/document1.vex.json \ + pkg/ctl/testdata/document2.vex.json +``` +The resulting document combines the VEX statements that express data about +`bash@1.0.0` 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/bash@1.0.0" + ], + "status": "under_investigation" + }, + { + "vulnerability": "CVE-1234-5678", + "timestamp": "2022-12-22T20:56:05-05:00", + "products": [ + "pkg:apk/wolfi/bash@1.0.0" + ], + "status": "affected" + } + ] +} + +``` + +#### 2. Attesting Examples ``` # Attest and attach vex statements in mydata.vex.json to a container image: @@ -30,7 +125,7 @@ vexctl attest --attach --sign mydata.vex.json cgr.dev/image@sha256:e4cf37d568d19 ``` -### 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 git@github.com:chainguard-dev/vex.git +git clone git@github.com: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 ```