source: .forge/security/README.md · generated — edit the markdown, not this file

Security — Dependency-Vulnerability Gate

This directory holds the reference template for the dependency-vulnerability build gate — the standing supply-chain security gate described in forge-harness-framework.md §4.10 (Build & CI foundation slice).

What the gate is

A scanner wired into CI that reports every resolved dependency carrying a vulnerability at or above a configurable severity threshold, on every build — it is not a per-feature judgment call. Under AD #38 it never fails a PR, a merge or a dev deploy; a UAT or production release stops on an open finding that has no exception (F38 FR-35). The per-feature application-security review (auth, data handling, endpoints) is a separate, human gate; see the quality checklist.

On this engagement the tool is Trivy (AD #9 as refined by AD #27), wired at FS-4. OWASP Dependency-Check — the tool AD #9 originally named and this README previously described — was swapped out when it proved unable to enumerate the pnpm frontends (0 npm coordinates from node_modules, 1 from its experimental lockfile parser); the full evaluation is .forge/specs/foundation/004-scanner-tool-analysis.md and the FS-4 spec Rev 2.

How it is wired (one shape, all three app repos)

  1. One tool, uniformly, in every repo — a scan wired into one repo but not its sibling is a gap, not a gate. Each repo’s Fast lane installs a pinned Trivy from its GitHub release, checked against a SHA-256 pinned in the workflow (not through aquasecurity/setup-trivy, whose install script depends on a second host — BUG-343), restores the vulnerability-DB cache (~/.cache/trivy; the DB is a public OCI artifact — no API key, no account), and runs trivy fs against the repo — which parses the committed lockfiles directly: the one gradle.lockfile (AD #31) plus the dev-tooling pnpm-lock.yaml on the backend, pnpm-lock.yaml on each frontend.
  2. Two invocations, one warm DB. A report invocation (all severities, --list-all-pkgs, JSON published as the trivy-report CI artifact) and a gate invocation: --severity HIGH,CRITICAL --exit-code $TRIVY_GATE_EXIT_CODE. HIGH,CRITICAL maps exactly onto AD #9’s CVSS ≥ 7.0 (HIGH 7.0–8.9, CRITICAL 9.0–10.0). The exit code is a workflow env var, never hardcoded, and it stays 0 (report-only): AD #38 (2026-10-02) cancelled FS-4 spec Rev 3’s plan to flip it to 1 once the dependency baseline was clean, because an enforcing PR gate would stop every merge and dev deploy the day an advisory is published against an untouched dependency. The blocking check is the release check in deploy-uat and deploy-prod (F38 FR-35), which stops on an open HIGH/CRITICAL finding unless the repo’s .trivyignore.yaml carries an exception for it. Coverage still gates at the Phase 1 → Phase 2 boundary (a settled denominator).
  3. --include-dev-deps is mandatory. Trivy suppresses dev-classified dependencies by default; a Vite app carries nearly everything as devDependencies, and build tooling executes in CI — it is supply chain too. Measured without the flag: 7 of 273 frontend packages visible, a HIGH finding invisible.
  4. Copy .forge/security/trivyignore-reference.yaml into each scanned app repo as .trivyignore.yaml and point the gate invocation’s --ignorefile at it. The copy in this directory is the reference, not the live file.
  5. Local reproduction (the scan is CI-only; the dev loop stays offline): brew install trivy (macOS) / winget install trivy (Windows), then run the gate invocation from the workflow verbatim. The DB caches under ~/.cache/trivy.

Suppressions governance

Every suppression entry must:

  • suppress by vulnerability id and dependency coordinate (purls, never a blanket id),
  • carry a justification in statement (why it’s not exploitable here, or who accepted the risk and when),
  • carry an expiry in expired_at — which Trivy enforces: the finding re-fires the gate once the date passes.

Trivy validates none of the fields’ presence itself, so id-plus-coordinate and justification are review-governed: an entry missing them is rejected in PR review. Prefer fixing by dependency upgrade over suppressing; a suppression is the exception, reserved for a genuinely non-exploitable dependency with no available fix.

Operational notes (captured so they aren’t re-learned)

  • Advisory source and its lag. Trivy’s language-ecosystem advisories come from the reviewed GHSA set (as do osv-scanner’s, Grype’s default, pnpm audit’s and Dependabot’s). NVD-fresh CVEs take days-to-weeks to gain a reviewed GHSA package mapping — measured 2026-08-31: 18 CVSS ≥ 7.0 Tomcat findings visible to NVD-based DC but to no GHSA-based tool six days after publication. Accepted (FS-4 finding F-003, AD #27), and kept accepted on 2026-11-03 once the release check existed: the nightly scans and the UAT and production release check catch a late advisory on the first night it reaches Trivy (AD #27’s row of .forge/design/architecture-decisions-why.md); the practical fix path for BOM-managed transitives is the routine framework bump either way.
  • Lockfile scanning cannot see inside jars. DC’s artifact-level analysis once flagged a shaded Guava embedded in a compile-time tool jar; no lockfile scanner can. Everything that ships is lockfile-visible, so the shipping surface is covered (FS-4 finding F-004).
  • Dependabot is the complementary alert layer, not the gate — it watches the default branch only, and GitHub’s dependency graph cannot read gradle.lockfile (measured: zero Maven packages in the backend graph), so its alerts cover the npm and github-actions ecosystems. It also cannot fix a transitive advisory in a pnpm lockfile. Measured 2026-09-15 on the js-yaml / fast-uri HIGH alerts in all three app repos (Dependabot security-update runs of 2026-09-10, read via gh run view --log-failed): corepack pnpm -v succeeds and the packageManager pin is honoured, but the updater’s VulnerabilityAuditor logs missing lockfile against pnpm-lock.yaml (it is npm-lockfile based), its only strategy is bumping the package to latest (pnpm update js-yaml@5.4.1 --lockfile-only — a major the dependents’ ranges refuse), and it records update_not_possible with the false claim that the current version is the latest installable. So an alert on a transitive pnpm dependency stays open until a person runs pnpm update --depth Infinity <pkg> (which resolves the fixed patch inside the existing ranges), falling back to pnpm.overrides with the reason at the line only when a range genuinely blocks; the alert closes on merge. This is a Dependabot limitation, not a dependabot.yml defect — no config change fixes it.
  • The DB cache uses the run_id-keyed / restore-keys freshness pattern (the exact key never pre-exists, so a fresh copy saves every run); Trivy self-refreshes a restored DB older than its 6h TTL. Cold download measured ~45s — under the lane cap even uncached; the cache mainly removes registry flakes.

Constraint

CI/CD pipeline changes typically require lead approval (see the project constitution’s NEVER DO list). Wiring or altering this gate is a CI change — get sign-off.

Generated from .forge/security/README.md by .claude/lib/render-docs-html.js. Markdown is canonical.