chainguard-dev / vex

vexctl is a tool to attest VEX impact statements
Apache License 2.0
44 stars 11 forks source link

Add vexctl create subcommand #59

Closed puerco closed 1 year ago

puerco commented 1 year ago

This PR adds a new subcommand to vexctl to create simple one statement documents. The idea of this subcommand is to handle simple use cases and to help folks to get started with a minimal document. This is intended to address some points raised in https://github.com/chainguard-dev/vex/issues/38

This PR also introduces a canonicalization algorithm in f3f03f3546329d09dcd930b5278a3fdf12ef002a to generate a hash identifying the impact data in documents. The idea is to be able to generate a constant hash derived from the VEX information in the document that does not change if superfluous information does.

From the help text:

vexctl create: creates a new VEX document

The create subcommand generates a single statement document
from the command line. This is intended for simple use cases
or to get a base document to get started.

You can specify multiple products and customize the metadata of
the document via the command line flags. vexctl will honor the
SOURCE_DATE_EPOCH environment variable and use that date for 
the document (it can be formated in unix time or RFC3339).

If you don't specify an ID for the document, one will be generated
using its canonicalization hash.

Examples:

# Generate a document stating that CVE-2023-12345 was fixed in the 
# git package of Wolfi:

vexctl create "pkg:apk/wolfi/git@2.39.0-r1?arch=x86_64" CVE-2023-12345 fixed

# You can specify more than one product. vexctl will read one from
# the argument but you can control all parameters through command line
# flags. Here's an example with two products in the same document:

vexctl create --product="pkg:apk/wolfi/git@2.39.0-r1?arch=x86_64" \
              --product="pkg:apk/wolfi/git@2.39.0-r1?arch=armv7" \
              --vuln="CVE-2023-12345" \
              --status="fixed"

# not_affected statements need a justification:

vexctl create --product="pkg:apk/wolfi/trivy@0.36.1-r0?arch=x86_64" \
              --vuln="CVE-2023-12345" \
              --status="not_affected" \
              --justification="component_not_present"

Usage:
  vexctl create [flags] [product_id [vuln_id [status]]]