Skip to content
CommonLayer
Documentation menu
On this page

ADR-0010: Cosign, Trivy and Grype as CLIs behind traits; OSV over HTTP

Status: Accepted (plan decision D10). Implemented in crates/commonlayer-artifacts/src/adapters/cosign.rs and crates/commonlayer-security/src/adapters/.

Context

Signature verification and vulnerability scanning have reference implementations (cosign, Trivy, Grype). Re-implementing them would be error-prone; depending on a single scanner would hide findings that only the other one reports.

Decision

  • Drive cosign, Trivy and Grype as subprocesses behind traits (SignatureVerifier, Scanner). Subprocesses run without a shell, with an explicit argument vector, a cleared environment, a fresh temporary working directory, a timeout and bounded output; output is parsed strictly and treated as untrusted.
  • Query OSV over HTTPS (batch API) to re-match the components of stored SBOMs every 6 hours, without pulling images again.
  • An adapter whose binary is not configured reports not_configured. The pipeline never skips verification: without cosign a submission stops with artifacts.verifier_not_configured.

Consequences

  • Tool versions matter and are pinned by scripts/dev/install-tools.sh (cosign 3.1.4, Trivy 0.76.2, Grype 0.121.3 at the time of writing).
  • Because the environment is cleared, scanner cache directories, proxies and insecure registries must be configured explicitly (security.scanner_cache_dir, scanner_offline, scanner_proxy, scanner_insecure_registries).
  • Cosign key-pair verification was exercised for real (WP-11); keyless verification (Fulcio, Rekor, GitHub OIDC identities) was not run locally and is validated only in CI once the release workflows run.
  • Real Trivy and Grype runs were exercised through the runner (WP-12); OSV, EPSS, KEV and NVD adapters were tested against recorded responses only.

Amendment, 2026-11-10

  • The publish drill (WP-70g, scripts/dev/e2e-publish.sh) ran the whole pipeline with real cosign 3.1.4, Trivy 0.76.2, Grype 0.121.3 and syft 1.57.1 against a local CNCF Distribution, with a key pair and without a transparency-log entry. Keyless verification (Fulcio, Rekor, GitHub OIDC identities) has still not run anywhere.
  • The OSV queries of the platform were not checked against the real service; the feeds still have only recorded-response tests.