Move to automating VEX

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

Author: ebourgeois

.claude/CHANGELOG.md

@@ -9,6 +9,90 @@ The format is based on the regulated environment requirements:
 
 ---
 
+## [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.

.github/workflows/build.yaml

@@ -15,7 +15,6 @@ on:
       - '.github/workflows/build.yaml'
       - '.github/actions/**'
       - '.vex/**'
-      - 'tools/**'
   push:
     branches:
       - main
@@ -139,10 +138,11 @@ jobs:
         run: cargo clippy --all-targets --all-features -- -D warnings
 
   # ─────────────────────────────────────────────────────────────────────────────
-  # VEX schema gate — PR only.
-  # Enforces schema, enum, and CVE-uniqueness on every file under .vex/ so that
-  # malformed VEX statements can never merge to main. The validator itself has
-  # its own fixture-based unit tests which also run here.
+  # VEX parse gate — PR only.
+  # Every .vex/<id>.json is a single-statement OpenVEX document (the native
+  # OpenVEX shape). vexctl merge parses each one as input; any malformed file
+  # fails the merge, giving us free schema + enum + structural validation
+  # from upstream tooling. No custom validator to maintain.
   # ─────────────────────────────────────────────────────────────────────────────
   validate-vex:
     name: 🧾 Validate VEX Statements
@@ -153,16 +153,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: '3.12'
-
-      - name: Run validator unit tests
-        run: ./tools/tests/validate-vex-tests.sh
+      - name: Install vexctl
+        run: make vexctl-install
 
-      - name: Validate .vex/ directory
-        run: ./tools/validate-vex.sh
+      - name: Parse every .vex/*.json via vexctl merge
+        run: make vex-validate
 
   # ─────────────────────────────────────────────────────────────────────────────
   # Extract version — all events; downstream build jobs depend on this.
@@ -492,15 +487,18 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────────────
   # VEX document — push to main + release.
   #
-  # Reads hand-authored per-CVE triage from .vex/*.toml, assembles a single
-  # OpenVEX document, and (on push/release only) Cosign-attests it to both
-  # image digests.  The `openvex` artifact is always uploaded so the `grype`
-  # container scan job can consume it via `--vex` and suppress already-
-  # triaged findings from GitHub Code Scanning.  On release, the GitHub
-  # build-provenance bundle is also emitted and attached to the release.
+  # Reads hand-authored per-CVE triage from .vex/*.json (each file is a
+  # single-statement native OpenVEX document), merges them into a single
+  # document via `vexctl merge`, and (on push/release only) Cosign-attests
+  # it to both image digests. The `openvex` artifact is always uploaded so
+  # the `grype` container scan job can consume it via `--vex` and suppress
+  # already-triaged findings from GitHub Code Scanning. On release, the
+  # GitHub build-provenance bundle is also emitted and attached to the
+  # release.
   #
-  # The validator runs first so malformed VEX can never leak through, even
-  # if a bad merge slipped past the PR gate.
+  # vexctl merge fails on any malformed input, so there's no separate
+  # validator step — a bad merge slipping past the PR gate would also fail
+  # the assembly here.
   # ─────────────────────────────────────────────────────────────────────────────
   build-vex:
     name: 🧾 Assemble OpenVEX
@@ -516,13 +514,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: '3.12'
-
-      - name: Validate .vex/ (defensive re-run before assembly)
-        run: ./tools/validate-vex.sh
+      - name: Install vexctl
+        run: make vexctl-install
 
       # Canonical @id varies by event so downstream consumers can link back
       # to the exact commit or release tag that produced the document.
@@ -541,11 +534,10 @@ jobs:
               vex_id="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}/vex"
               ;;
           esac
-          python3 tools/assemble_openvex.py \
-            --vex-dir .vex \
+          vexctl merge \
             --id "$vex_id" \
             --author "${{ github.event.release.author.login || github.actor }}" \
-            --output vex.openvex.json
+            .vex/*.json > vex.openvex.json
           echo "── vex.openvex.json ─────────────────────────────────────────"
           cat vex.openvex.json
 

.vex/CVE-2010-4756.json

@@ -0,0 +1,23 @@
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "@id": "https://github.com/finos/5-spot/.vex/CVE-2010-4756",
+  "author": "erick.bourgeois@gmail.com",
+  "statements": [
+    {
+      "impact_statement": "5-Spot performs no file-system glob expansion; the vulnerable glibc glob() implementation is never called from the controller.",
+      "justification": "vulnerable_code_not_in_execute_path",
+      "products": [
+        {
+          "@id": "pkg:oci/5-spot"
+        }
+      ],
+      "status": "not_affected",
+      "timestamp": "2026-04-19T00:00:00Z",
+      "vulnerability": {
+        "name": "CVE-2010-4756"
+      }
+    }
+  ],
+  "timestamp": "2026-04-19T00:00:00Z",
+  "version": 1
+}

.vex/CVE-2010-4756.toml

@@ -0,0 +1,23 @@
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "@id": "https://github.com/finos/5-spot/.vex/CVE-2018-20796",
+  "author": "erick.bourgeois@gmail.com",
+  "statements": [
+    {
+      "impact_statement": "5-Spot uses the Rust regex crate, a separate implementation from glibc's posix/regexec.c; the vulnerable C function is never invoked.",
+      "justification": "vulnerable_code_not_in_execute_path",
+      "products": [
+        {
+          "@id": "pkg:oci/5-spot"
+        }
+      ],
+      "status": "not_affected",
+      "timestamp": "2026-04-19T00:00:00Z",
+      "vulnerability": {
+        "name": "CVE-2018-20796"
+      }
+    }
+  ],
+  "timestamp": "2026-04-19T00:00:00Z",
+  "version": 1
+}

.vex/CVE-2018-20796.json

@@ -0,0 +1,23 @@
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "@id": "https://github.com/finos/5-spot/.vex/CVE-2019-1010022",
+  "author": "erick.bourgeois@gmail.com",
+  "statements": [
+    {
+      "impact_statement": "The controller does not execute adversary-supplied native code; the pre-conditions required to reach the glibc stack-guard bypass do not exist in this workload.",
+      "justification": "vulnerable_code_cannot_be_controlled_by_adversary",
+      "products": [
+        {
+          "@id": "pkg:oci/5-spot"
+        }
+      ],
+      "status": "not_affected",
+      "timestamp": "2026-04-19T00:00:00Z",
+      "vulnerability": {
+        "name": "CVE-2019-1010022"
+      }
+    }
+  ],
+  "timestamp": "2026-04-19T00:00:00Z",
+  "version": 1
+}

.vex/CVE-2018-20796.toml

@@ -0,0 +1,23 @@
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "@id": "https://github.com/finos/5-spot/.vex/CVE-2019-1010023",
+  "author": "erick.bourgeois@gmail.com",
+  "statements": [
+    {
+      "impact_statement": "The Distroless image ships no ldd or shell; the vulnerable workflow (running ldd on an adversary-supplied ELF) cannot occur at runtime.",
+      "justification": "vulnerable_code_not_in_execute_path",
+      "products": [
+        {
+          "@id": "pkg:oci/5-spot"
+        }
+      ],
+      "status": "not_affected",
+      "timestamp": "2026-04-19T00:00:00Z",
+      "vulnerability": {
+        "name": "CVE-2019-1010023"
+      }
+    }
+  ],
+  "timestamp": "2026-04-19T00:00:00Z",
+  "version": 1
+}