Skip to content

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.

StepToolBlocks on
Secretsgitleaks, full git history, default rules plus .gitleaks.tomlany finding
Dependenciespnpm audit read by scripts/security/audit-check.tsa high or critical advisory with no live exception, or an expired exception
Codesemgrep: p/typescript, p/nodejs, p/owasp-top-ten and security/semgrep/*.ymlany ERROR finding, or a project rule whose own fixture test fails
Configurationtrivy config on the DockerfileHIGH or CRITICAL
Base imagestrivy image --image-src remote on each image the Dockerfile and compose files namenothing yet: report only
SBOMtrivy fs --format cyclonedx from pnpm-lock.yaml, uploaded with actions/upload-artifact@v3nothing: 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 no node: modules in src/rules/ or src/vat/.
  • pence-divided-by-float: pence divided or multiplied by a float literal.
  • pence-divided-by-100: pence divided by 100 outside src/shared/money.ts (penceToPounds, formatPounds, formatMoney).
  • mcp-no-entity-id-input: no entityId or entity_id in an MCP tool's input schema (rule 4).
  • no-logging-credential-headers: the Authorization, Cf-Access-Jwt-Assertion or Cookie header value never reaches a log call.

Pinned versions ​

ToolVersionHow it is checked
gitleaks8.30.1sha256 pinned in scripts/security/gitleaks.sh (amd64 and arm64), must match the release's checksums file and the download
trivy0.74.0the same, in scripts/security/trivy.sh
semgrep1.178.0pip install semgrep==1.178.0 into a venv
eslint-plugin-security4.1.0exact 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" }. id is the GHSA id or the npm advisory number, expires is YYYY-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.toml allowlists 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: decryptString accepted a truncated GCM authentication tag. Fixed with authTagLength: 16 in src/platform/crypto.ts, with a test.
  • pence / 100 in src/xero/bank-writes.ts (three places) and a copy of the pounds formatter in src/rules/reconciliation-summary.ts. They now use penceToPounds and formatPounds in src/shared/money.ts.
  • eslint-plugin-security: scripts/xero-connect.ts opened the browser through a shell with the URL inside the command. It now uses execFile. The thousands-separator regex became a loop (groupThousands). Five fixed-path file reads in src/ 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) and cloudflare/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 install and the apt and pip installs.
  • 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 config does not read docker-compose files, so infra/nas/docker-compose.yml is 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:latest should 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 /health and /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-alpine is pinned to one multi-arch index digest in infra/nas/docker-compose.yml, docker-compose.dev.yml and the postgres services of ci.yml and performance.yml; cloudflare/cloudflared:latest became a versioned tag plus its digest. Every workflow job container: (node:22-bookworm in ci.yml, health.yml and performance.yml, deploy jobs included, which hold DOPPLER_TOKEN_PRD) is pinned to one index digest too, and Renovate's github-actions manager keeps those pins current. tests/infra/compose-images.test.ts refuses an unpinned or :latest image 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.json pins digests (pinDigests), maintains pnpm-lock.yaml weekly, 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.yml runs the pinned Renovate image on the general ubuntu-latest runners, never getmy-books-deploy (#71), against GitHub. It reads no Doppler secret; its only secret is RENOVATE_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.ts holds 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.yml still 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.