Phase 10 — Security, Compliance & Supply Chain
Status: 100% Dev-Infra ceiling (2026-05-12). AWS OIDC + Cosign + SBOM
Trivy + CodeQL + SLSA Build L2 + license policy + npm-strip + key rotation runbook + audit-trail emission all shipped. SIEM destination stays out-of-scope per the project's Out-of-Scope table.
What this phase covers
Take the project from "we ship containers and hope they're not vulnerable" to "every artifact is signed, attested, scanned, license-checked, SAST- analysed, and every off-chain privileged action emits a structured audit event." Plus the runbooks the operator needs the day a key rotates or a CVE lands.
What we built
Defense-in-depth layer cake
Secret scanning
gitleaks
ci.yaml Secret Scan job
blocking on push
Source SAST
CodeQL
codeql.yaml, weekly cron + every PR
findings to Security tab
Container CVE scan
Trivy
publish-images.yaml
CRITICAL blocks; HIGH visibility-only
Solidity SAST
Slither
ci-contracts.yaml (production + template)
blocking with fail_on: high
License policy
scripts/check-licenses.mjs
ci.yaml License Check
blocking
Image signing
Cosign (keyless)
release.yaml + publish-images.yaml
required for prod pull
Build provenance
SLSA L2 (actions/attest-build-provenance@v2)
publish-images.yaml
verifiable via gh attestation verify
Deploy-side verify
Cosign + gh attestation verify
deploy-simple.yaml
per-service result in summary table
npm provenance
npm publish --provenance
release.yaml publish_npm
links every release to the exact CI run
Audit trail emission
pino child category: 'audit'
Makalu/api/src/lib/audit.ts
structured Loki-filterable lines
No single layer catches everything; together they cover the OWASP top-10
supply-chain attack classes documented in SLSA.
CodeQL first-scan triage (23 → 0)
CodeQL's first run flagged 23 alerts. Over two triage passes (commits ae2c0c7 + 5201549) they all closed:
10 fixed at source — including 2 CRITICAL
js/request-forgery(one with a real fix: post-resolution origin allow-list atMakalu/api/src/index.ts:86), 2 HIGHjs/polynomial-redosin the indexer (regex replaced with non-regex), and 6 NOTE-level unused-locals.13 dismissed as false positives with audit comments — mostly
js/log-injectionwhere CodeQL's local-flow analysis can't trace thesanitizeForLog()helper, andjs/xss-through-domonrouter.push()where there is nodangerouslySetInnerHTMLanywhere in the destination components (audit-confirmed by grep).
The triage workflow is documented in docs/governance/supply-chain.md under "Triage workflow for CodeQL findings": fix / dismiss-with-comment / track-as-work, weekly cadence aligned with the cron.
npm CVE strip (issue #14)
Production runners shipped with the full npm CLI baked in (11+ HIGH CVEs across node:20-alpine). The runner stages don't need npm — pnpm-installed deps run via node directly. Strip step in each Dockerfile:
Trivy delta: api 11→0 HIGH, indexer 11→0, explorer 14→3 (the residual 3 are explorer app deps — Next.js 14→15 + coinbase-wallet-sdk minor — tracked in issue #15).
License allow/deny policy
.license-policy.yaml defines 11 allowed + 14 denied license SPDX identifiers plus per-package exceptions. scripts/check-licenses.mjs spawns pnpm licenses list --json --prod and evaluates every prod package; the license-check CI job runs it on every PR.
Currently: 541 prod packages scanned, 1 granted exception (caniuse-lite CC-BY-4.0 — data file, not code).
Hand-parsed YAML (same pattern as scripts/process-test-results.mjs) so the gate has no transitive deps that would themselves need policy checking.
Audit trail emission
Makalu/api/src/lib/audit.ts exposes:
backed by a pino child logger with category: 'audit' baked into the child bindings. Typed AuditAction union (currently 3 actions: faucet_claim_success, faucet_claim_rejected, faucet_claim_upstream_failed) catches typos at every call site.
Wired into Makalu/api/src/routes.ts at the 4 faucet decision points. Operational logger.warn/error calls kept alongside — different concerns, different consumers.
Loki filter to extract the audit stream:
How to use what was built
Verify an image's signature + build provenance:
Triage a CodeQL alert:
Open Security → Code scanning → filter by
tool:CodeQL.Apply the three-way classifier from
supply-chain.md: fix / dismiss-with-comment / track-as-work.If dismissing, the comment is required reading for the next triage pass — explain why the analyzer is wrong.
Add a new audit action:
The typed union forces all three steps; you can't ship a new audit event without touching the doc (because the catalog table key is the action name).
Investigate a flagged audit event:
The requestId carries across because the audit logger is a pino child of the root logger — AsyncLocalStorage middleware stamps it.
Why it matters
Defense in depth catches the bugs a single tool misses. Trivy doesn't see SQL injection; CodeQL doesn't see CVE chains in transitive deps; Slither doesn't see either. Layering means one weak detector doesn't drop the floor.
Signed + attested images are non-negotiable for any prod-targeting deploy. Cosign proves provenance of the image content; SLSA L2 proves provenance of the build process. The deploy-side verify step turns both into pass/fail signals before the image runs.
License policy is the cheapest insurance. A copyleft package pulled in transitively can force open-source obligations on the whole SDK. The 5-minute CI job prevents the year-long lawyer engagement.
Audit emission ahead of SIEM means the day a SIEM lands, the forwarder is a one-query change (
category=auditfilter). No code rollout, no instrumentation backfill.
Files & commits
.github/workflows/codeql.yaml
SAST runner
.github/workflows/ci.yaml (license-check job)
Policy enforcement
.github/workflows/publish-images.yaml
Trivy + Cosign + SLSA attest
Makalu/api/src/lib/audit.ts
Audit logger + typed union
Makalu/api/src/routes.ts (faucet handlers)
4 audit call sites
.license-policy.yaml
Allow/deny + exceptions
scripts/check-licenses.mjs
Policy evaluator
docs/governance/supply-chain.md
Verification + triage UX
docs/governance/audit-trail.md
Audit catalog + Loki queries
docs/governance/key-rotation-runbook.md
Cosign/npm/AWS OIDC rotation
docs/governance/license-policy.md
Allow/deny rationale + exception process
Commit chain: 1ccc603 (Trivy), af4a18d (npm strip), ae2c0c7 + 5201549 (CodeQL triage), 8111e19 + 04ba66d (Slither blocking flip), 5f7499b (audit trail).
Deferred work
Architecturally out-of-scope (NOT closable by Dev Infra)
SIEM destination. Listed under Out-of-Scope ("Enterprise requirement, premature for testnet"). The audit channel is wired so the SIEM-when-it- lands export is a single Loki query change, not a code rollout.
Closable but deferred (low priority / low ROI)
Snyk / GitHub Advanced Security private vuln database. Trivy + CodeQL cover the same surface for public sources; the marginal value doesn't justify the cost yet.
Policy as code (OPA / Conftest). Today the policy is encoded in
scripts/check-licenses.mjsandslither.config.json. OPA would generalize but adds an OPA-runtime dep with its own CVE surface; defer until policy complexity demands it.S3 archival pipeline for audit logs. Cron-driven Loki→S3 export filtered on
category=auditwould satisfy 1-year compliance retention without a full SIEM. Defer until a compliance ask arrives.
Pending issue tracking
Issue #15: explorer Next.js 14→15 major bump to close residual HIGH alerts. Risky bump; deferred to a focused session.
Last updated