Appearance
0027: Security scanning on every change
Note 2026-11-06: the git host and CI moved to GitHub (
FEAW-Serv/getmy-books), ADR 0046. References below to the previous host are history; ADR 0046 says what replaces them.
Context
Issue #102. The pipeline checked lint, types, tests and the build, but nothing looked for committed secrets, vulnerable dependencies, insecure code patterns or container misconfiguration. GetMy Books holds Xero and bank tokens for real companies, so a leak or an injectable dependency is a real risk. The pipeline must stay under 6 minutes with no cache service, and must not go red for reasons that have nothing to do with the change (CLAUDE.md rule 7).
Decision
A security job in .github/workflows/ci.yml runs on every pull request and every push to main, in parallel with verify. It runs on the general ubuntu-latest runners in node:22-bookworm and needs no secrets, so it never uses the getmy-books-deploy runner (#71). A red scan on main alerts the Product Owner through alert-main-failed. It does not hold back migrate-nas or deploy-nas, which still depend on verify only.
Every step is a script under scripts/security/ and runs the same way on a developer's machine. Tools download into .tools/, which git ignores.
| Step | Tool | Blocks on |
|---|---|---|
| Secrets | gitleaks, full git history, default rules plus .gitleaks.toml | any finding |
| Dependencies | pnpm audit read by scripts/security/audit-check.ts | a high or critical advisory with no live exception, or an expired exception |
| Code | semgrep: p/typescript, p/nodejs, p/owasp-top-ten and security/semgrep/*.yml | any ERROR finding, or a project rule whose own fixture test fails |
| Configuration | trivy config on the Dockerfile | HIGH or CRITICAL |
| Base images | trivy image --image-src remote on each image the Dockerfile and compose files name | nothing yet: report only |
| SBOM | trivy fs --format cyclonedx from pnpm-lock.yaml, uploaded with actions/upload-artifact@v3 | nothing: a failed upload is ignored |
Each scan runs even if an earlier one failed, so one red run shows every finding.
ESLint also loads eslint-plugin-security (recommended rules). Lint allows no warnings, so its findings block through verify. Two rules are narrowed in eslint.config.js, with reasons: detect-object-injection is off (typed keys everywhere, 31 false positives), and detect-non-literal-fs-filename is off for tests/ and scripts/.
Project semgrep rules
Each rule in security/semgrep/ has an annotated fixture beside it, and semgrep --test runs first, so a rule that stops matching fails the job.
pure-modules-no-fetch,pure-modules-no-node-builtins: no network calls and nonode:modules insrc/rules/orsrc/vat/.pence-divided-by-float: pence divided or multiplied by a float literal.pence-divided-by-100: pence divided by 100 outsidesrc/shared/money.ts(penceToPounds,formatPounds,formatMoney).mcp-no-entity-id-input: noentityIdorentity_idin an MCP tool's input schema (rule 4).no-logging-credential-headers: theAuthorization,Cf-Access-Jwt-AssertionorCookieheader value never reaches a log call.
Pinned versions
| Tool | Version | How it is checked |
|---|---|---|
| gitleaks | 8.30.1 | sha256 pinned in scripts/security/gitleaks.sh (amd64 and arm64), must match the release's checksums file and the download |
| trivy | 0.74.0 | the same, in scripts/security/trivy.sh |
| semgrep | 1.178.0 | pip install semgrep==1.178.0 into a venv |
| eslint-plugin-security | 4.1.0 | exact version in package.json, locked in pnpm-lock.yaml |
A pinned hash means a re-uploaded release asset fails the job instead of running. Upgrades are deliberate: change the version and both hashes together.
Exceptions and ignores
- Dependencies:
security/audit-exceptions.json, a JSON array of{ "id", "package", "reason", "expires" }.idis the GHSA id or the npm advisory number,expiresisYYYY-MM-DD. An exception covers the advisory up to and including that day. After it, the job fails until someone upgrades or renews it with a fresh reason. An exception nothing needs any more is reported as a warning. - Secrets:
.gitleaks.tomlallowlists only the throwaway development database passwords. A new entry must be provably not a secret. - Code:
// nosemgrep: <rule-id> <reason>on the line, never without a reason. None exist today. - Configuration:
.trivyignore, one ID per line under a comment saying why. Empty today.
Findings on main when this was added (2026-09-30)
- semgrep
gcm-no-tag-length:decryptStringaccepted a truncated GCM authentication tag. Fixed withauthTagLength: 16insrc/platform/crypto.ts, with a test. pence / 100insrc/xero/bank-writes.ts(three places) and a copy of the pounds formatter insrc/rules/reconciliation-summary.ts. They now usepenceToPoundsandformatPoundsinsrc/shared/money.ts.- eslint-plugin-security:
scripts/xero-connect.tsopened the browser through a shell with the URL inside the command. It now usesexecFile. The thousands-separator regex became a loop (groupThousands). Five fixed-path file reads insrc/carry a disable comment with a reason. - The base image scan reports fixed HIGH and CRITICAL vulnerabilities in
node:22-bookworm-slim(the npm bundled in the image),postgres:17-alpine(gosu) andcloudflare/cloudflared:latest. These are report only (see below).
Consequences
- The job adds no time to the critical path while it is faster than
verify. Measured locally from a cold.tools/: gitleaks 2 s, audit 1 s, semgrep 12 s, trivy config 4 s, image scan 17 s, SBOM under 1 s. CI adds the checkout,pnpm installand theaptandpipinstalls. - Advisory databases and the semgrep registry packs change without a commit, so a new advisory or rule can turn a clean change red. That is the point of scanning, not flakiness: the fix is an upgrade, a code change or a dated exception, never a re-run.
trivy configdoes not read docker-compose files, soinfra/nas/docker-compose.ymlis not checked for misconfiguration. Its images are covered by the base image scan.
Later
- Image scan blocks after #75. Once CI builds the app image, scan that image and block on fixed HIGH or CRITICAL vulnerabilities, with base images pinned by digest.
cloudflare/cloudflared:latestshould be pinned then too. - Dependency updates (#77, Renovate) so audit findings arrive as PRs. See the amendment below.
- DAST against the deployed app (OWASP ZAP baseline). Not before the web surface grows beyond
/healthand/mcp. - Pin the semgrep registry packs to a snapshot if they ever cause churn.
Amendment, 2026-11-03: base images pinned by digest, and Renovate (#77)
- Pins.
postgres:17-alpineis pinned to one multi-arch index digest ininfra/nas/docker-compose.yml,docker-compose.dev.ymland thepostgresservices ofci.ymlandperformance.yml;cloudflare/cloudflared:latestbecame a versioned tag plus its digest. Every workflow jobcontainer:(node:22-bookworminci.yml,health.ymlandperformance.yml, deploy jobs included, which holdDOPPLER_TOKEN_PRD) is pinned to one index digest too, and Renovate'sgithub-actionsmanager keeps those pins current.tests/infra/compose-images.test.tsrefuses an unpinned or:latestimage or job container, and the compose check on the NAS refuses an unpinned image too (ADR 0023 §4a). The image scan stays report only until #75. - Renovate proposes updates as pull requests:
renovate.jsonpins digests (pinDigests), maintainspnpm-lock.yamlweekly, groups npm minor and patch updates into one pull request and image digests into another, and never proposes a new Postgres major (the data volume needs a dump and restore for that). - Where it runs.
.github/workflows/renovate.ymlruns the pinned Renovate image on the generalubuntu-latestrunners, nevergetmy-books-deploy(#71), against GitHub. It reads no Doppler secret; its only secret isRENOVATE_TOKEN, a repository secret holding a token of a bot user that can push branches and open pull requests on this repository and nothing else.tests/infra/ci-workflow.test.tsholds both rules. - Who merges. Its pull requests go through the same CI, and the Product Owner approves each one, like any other change. A change to
infra/nas/docker-compose.ymlstill needs the root-owned copy on the NAS reinstalled by hand (ADR 0023). - Until the token exists the workflow runs only by hand (
workflow_dispatch) and fails without the token; the weekly schedule is committed commented out, to be switched on once a manual run has opened its first pull request.