Move to automating VEX creation and add grype

Signed-off-by: Erick Bourgeois <erick@jeb.ca>

Author: ebourgeois

.claude/CHANGELOG.md

@@ -9,6 +9,201 @@ The format is based on the regulated environment requirements:
 
 ---
 
+## [2026-04-22 20:30] - Presence-based auto-VEX (roadmap Phase 2)
+
+**Author:** Erick Bourgeois
+
+### Added
+- `src/auto_vex_presence.rs` (library module, ~180 LOC) + `src/auto_vex_presence_tests.rs`
+  (20 unit tests, 100% positive/negative/exception coverage per project rule):
+  - `compute_presence_vex` — pure function that diffs Grype findings against
+    SBOMs and the already-triaged CVE set, emitting
+    `not_affected + component_not_present` statements for CVEs whose purl
+    is absent from every SBOM.
+  - `build_document` — wraps statements in the OpenVEX envelope.
+  - `load_triaged_from_vex_dir` — reads hand-authored `.vex/*.json` and
+    collects the set of `vulnerability.name` values (permissive on
+    missing dir, strict on malformed JSON).
+  - Typed deserializers for Grype JSON and CycloneDX SBOM subsets —
+    tolerant of unknown upstream fields.
+  - Output sorted by CVE id for deterministic, diffable artifacts.
+- `src/bin/auto_vex_presence.rs` — thin clap-driven CLI wrapping the
+  library. Reads `--grype-json`, one or more `--sbom` files, a
+  `--vex-dir`, a `--product-purl`, `--id`, optional `--author` and
+  `--timestamp`, writes an OpenVEX JSON to `--output` or stdout.
+- `Cargo.toml`: `[[bin]] auto-vex-presence` entry.
+- `Makefile`: `vex-auto-presence` target (defaults `GRYPE_JSON=grype.json`
+  and `SBOM_FILES=target/release/*.cdx.json docker-sbom-*.json`; both
+  overridable). Added to `.PHONY`.
+- `.github/workflows/build.yaml`: two new jobs gated on
+  `github.event_name != 'pull_request'`:
+  - `grype-triage` — runs Grype against each image variant without VEX
+    suppression, uploads per-variant JSON (pinned GRYPE_VERSION 0.87.0
+    matching the existing `grype` job).
+  - `auto-vex-presence` — builds the new bin, downloads both triage
+    scans + Docker SBOMs, runs the bin once per variant, merges the
+    per-variant outputs via `vexctl merge`, uploads
+    `vex-auto-presence` artifact.
+
+### Changed
+- `.github/workflows/build.yaml`:
+  - Docker SBOM generation (`Generate Docker SBOM for ${{ matrix.variant.name }}`):
+    gate loosened from `if: github.event_name == 'release'` to
+    `if: github.event_name != 'pull_request'` so push-to-main also
+    produces SBOMs for auto-vex-presence to consume.
+  - `build-vex` job: `needs` extended to include `auto-vex-presence`.
+    Added a feature-flagged download step (`if: vars.AUTO_VEX_PRESENCE == '1'`)
+    and conditional merge inclusion. When the repo variable is
+    `AUTO_VEX_PRESENCE=1`, `vex.auto-presence.json` is merged alongside
+    `.vex/*.json`; otherwise hand-authored only. Artifact is produced
+    regardless — only the merge is gated.
+- `src/lib.rs`: re-export `pub mod auto_vex_presence`.
+- `docs/src/security/vex.md`: CI flow section renumbered to 6 steps;
+  added step 2 for auto-presence. Rewrote "Why we did not auto-generate
+  statements" section as "What we automate, and what stays human" — the
+  policy now distinguishes `component_not_present` (mechanical,
+  automatable) from every other triage decision (human-authored).
+- `.vex/README.md`: added "Automated statements (roadmap Phase 2)"
+  section explaining the review-artifact vs flag-gated-merge split.
+
+### Why
+Phase 2 of the automated VEX generation roadmap
+(`~/dev/roadmaps/5spot-automated-vex-generation.md`). Most of the
+hand-authored statements under `.vex/` exist because Grype flags
+CVEs on libc / glibc / zlib code paths that the Rust binary never
+reaches — i.e. the vulnerable component is present in the image
+filesystem but never invoked. A subset of those (plus most
+base-image CVEs going forward) can be suppressed mechanically by
+observing that the flagged package's purl is not in the SBOM at
+all: the SBOM is authoritative for what's in the product, so
+"component_not_present" is the one OpenVEX justification with a
+purely verifiable definition. Automating that specific case shrinks
+the `.vex/` maintenance queue without compromising the trust model
+for any other justification.
+
+The implementation is strictly SBOM-driven — no reachability analysis,
+no source-code inspection. Reachability is Phase 3.
+
+### Rollout / feature-flag
+Per the roadmap rollout plan, the auto-presence artifact is
+produced and uploaded on every push + release, but it is **only
+merged into the signed VEX document when `vars.AUTO_VEX_PRESENCE=1`
+is set** at the repository or organization level. This gives
+maintainers at least one release of parallel-run validation: the
+artifact is visible for review, but consumers see only the
+hand-authored VEX until the flag is flipped. This matches the
+roadmap's explicit guidance ("Run in parallel with hand-authored VEX
+for one release; diff the auto-set against .vex/ and confirm no
+surprises before flipping it on").
+
+### Verification
+- `cargo fmt --all -- --check`: clean.
+- `cargo clippy --all-targets --all-features -- -D warnings`: clean.
+- `cargo test --lib`: 349 tests pass (329 pre-existing + 20 new for
+  `auto_vex_presence`).
+- Smoke test: ran the bin against a synthetic Grype JSON (3 matches),
+  synthetic SBOM (covering 1 of the 3 purls), and the current `.vex/`
+  directory (covering 1 of the 3 CVEs). The bin emitted exactly the
+  one statement for the remaining CVE whose purl was absent, and
+  `vexctl merge` of the auto-presence output + `.vex/*.json`
+  produced a 16-statement document with the auto statement correctly
+  included.
+
+### Impact
+- [ ] Breaking change
+- [x] Requires cluster rollout (no — CI only)
+- [ ] Config change only
+- [x] Documentation only
+
+*(Rollout note: when maintainers want to flip `AUTO_VEX_PRESENCE=1`,
+that's a repo-variable change in GitHub settings, no code deploy.)*
+
+---
+
+## [2026-04-22 19:45] - Replace Python VEX tooling with vexctl (roadmap Phase 1)
+
+**Author:** Erick Bourgeois
+
+### Removed
+- `tools/` — entire directory deleted. Removed `assemble_openvex.py`,
+  `validate_vex.py`, `validate-vex.sh`, `tests/assemble-openvex-tests.sh`,
+  `tests/validate-vex-tests.sh`, and all 18 fixture directories under
+  `tests/fixtures/`. ~400 LOC of bespoke Python + shell tests replaced
+  by upstream `vexctl` invocations.
+
+### Changed
+- `.vex/*.toml` → `.vex/*.json` (15 files): migrated every statement
+  from the bespoke TOML dialect to the native OpenVEX v0.2.0 JSON
+  shape. Each file is now a single-statement OpenVEX document that
+  `vexctl merge` can consume directly; no translation layer.
+- `Makefile`: added `VEXCTL_VERSION ?= 0.4.1`, `vexctl-install` target
+  (brew on macOS, pinned GitHub release tarball with checksum
+  verification on Linux; errors on other OSes), `vex-validate`
+  (parses every `.vex/*.json` via `vexctl merge` — successful parse
+  is the validation), and `vex-assemble` (prints the merged document
+  for local preview). `.PHONY` list updated.
+- `.github/workflows/build.yaml`:
+  - `validate-vex` job: dropped Python setup + custom validator calls;
+    now runs `make vexctl-install` then `make vex-validate`.
+  - `build-vex` job: dropped Python setup + `assemble_openvex.py`;
+    now runs `vexctl merge --id <per-event-id> --author <actor>
+    .vex/*.json` directly. Per-event `@id` logic (release / push /
+    PR) preserved verbatim. Cosign attestation, artifact upload,
+    and `attest-build-provenance` steps unchanged.
+  - PR `paths:` filter: removed `tools/**` (directory no longer
+    exists); `.vex/**` retained.
+- `.vex/README.md`: rewritten to document native OpenVEX JSON
+  authoring and `make vex-validate` / `make vex-assemble` instead of
+  the old TOML schema and shell validator.
+- `docs/src/security/vex.md`: CI flow section updated — step 1
+  ("validate") and step 2 ("assemble") now describe `vexctl merge`
+  behaviour; dropped the obsolete "cross-check with `vexctl validate`"
+  step (vexctl has no `validate` subcommand). Maintainer-authoring
+  section rewritten with the JSON shape in place of the TOML shape.
+- `.claude/SKILL.md`: release checklist item for VEX updated from the
+  old three-script check to `make vex-validate`.
+
+### Why
+Phase 1 of the automated VEX generation roadmap
+(`~/dev/roadmaps/5spot-automated-vex-generation.md`). The custom
+Python toolchain duplicated functionality that `vexctl` — the official
+OpenVEX CLI — provides upstream. Maintaining a bespoke TOML dialect,
+its validator, its assembler, and two fixture-based test suites
+added ~400 LOC of surface area with no offsetting benefit once we
+accept OpenVEX JSON as the authoring format. Replacing the whole
+stack with `vexctl merge` (which doubles as the validator via
+successful parse) removes the Python runtime from CI entirely,
+eliminates a class of drift between our validator and the upstream
+spec, and prepares the pipeline for Phases 2–3 (automated VEX
+generation from SBOM and call-graph reachability).
+
+The TOML-over-JSON ergonomics hit is real but small: 15 files in
+`.vex/`, each ~15 lines of JSON, with no inline comments. In
+exchange, future maintainers work with the same format upstream
+tooling speaks and any OpenVEX-aware tool can consume the source
+directory directly.
+
+### Verification
+- `make vex-validate` parses all 15 `.vex/*.json` successfully.
+- `vexctl merge --id <x> --author <y> .vex/*.json` produces a
+  15-statement document structurally identical to what the Python
+  assembler would have produced (confirmed via key-by-key diff of
+  `@context`, `@id`, `author`, `version`, and every statement's
+  `products`, `status`, `justification`, `impact_statement`,
+  `action_statement`, `timestamp`).
+
+### Impact
+- [ ] Breaking change
+- [ ] Requires cluster rollout
+- [ ] Config change only
+- [x] Documentation only
+
+*(Not really "documentation only" — code deletion is substantive —
+but no runtime, CRD, or API-surface change. Closest pre-existing
+box.)*
+
+---
+
 ## [2026-04-21 15:00] - Model emergency-reclaim in CALM — ADD retrofit
 
 **Author:** Erick Bourgeois

.claude/SKILL.md

@@ -326,8 +326,7 @@ done
 
 ### If preparing a release:
 - [ ] Every open Trivy finding has a corresponding statement in `.vex/` (triaged into one of: `not_affected`, `affected`, `fixed`, `under_investigation`). No silent "unknown" CVEs leave the door.
-- [ ] `./tools/validate-vex.sh` exits 0.
-- [ ] `./tools/tests/validate-vex-tests.sh` and `./tools/tests/assemble-openvex-tests.sh` pass.
+- [ ] `make vex-validate` exits 0 (every `.vex/*.json` parses cleanly via `vexctl merge`).
 - [ ] `.vex/` changes referenced in the release notes / changelog.
 
 **Verification:** Every checked box above passes. A task is NOT complete until the full checklist is green.