backspace/docs/superpowers/specs/2026-07-10-security-scanning-hardening-design.md

Security Scanning & Hardening Initiative — Design

Date: 2026-07-10 Status: Approved (design); pending implementation plan Author: Lead Developer (Backspace)

---

1. Motivation

A prospective self-hoster declined to run Backspace with the objection:

"Security testing: You've made a web app. I am not installing a new webapp that is expected to touch the internet without some level of security scanning."

The objection is valid. Investigation of the current state shows Backspace has solid security engineering but no security assurance infrastructure:

Already present (good):

• SECURITY.md with a private vulnerability-disclosure policy.
• Real defensive code: SSRF protection (packages/server/src/utils/ssrf.ts — DNS resolution, private-IP blocking, per-redirect-hop re-validation), HMAC-signed federation with replay-nonce prevention, sliding-window rate limiters, JWT + bcrypt, input validation.
• Good secrets hygiene: .deploy.local untracked; thorough .gitignore (.env*, *.pem, *.key, data/, *.db).
• CI (ci.yml) running typecheck + build + full test suite.

Absent (the gap):

• No SAST, no dependency/CVE scanning, no secret scanning, no container image scanning, no supply-chain hardening, no Dependabot.
• No visible, verifiable evidence a stranger can audit before trusting the app.
• No browser-facing hardening the objection actually cares about: no security response headers (@fastify/helmet absent; bare Caddyfile), CORS reflects any origin with credentials, unsigned desktop autoupdate, no Electron fuses/asar integrity, no license compliance gate for a dual-licensed (AGPL + commercial) project.

Root cause (per the No-Band-Aids principle): the fix is not a one-off scan. It is a permanent, automated, and visible scanning pipeline wired into CI/CD, plus remediation of the browser/desktop hardening gaps that continuous scanning would be embarrassing to leave open.

---

2. Goals & Non-Goals

Goals

1. Continuous, automated scanning on every change: SAST, dependency CVEs, secrets, container image, license compliance, supply-chain posture.
2. Tiered enforcement: high-confidence, fixable issues block merge; the rest are advisory in the GitHub Security tab. Never wall off merges on unfixable upstream CVEs.
3. Close the browser-facing and desktop-facing hardening gaps (headers, CORS, Electron integrity).
4. Publish verifiable evidence: badges, an OpenSSF Scorecard, SBOM/provenance, and documentation a stranger can read without repo access.
5. Land the whole thing without leaving CI spuriously red: scanners report-only → remediate → flip enforcement.

Non-Goals (explicitly out of scope for this initiative)

• npm provenance / package signing — every workspace is "private": true; nothing is published to npm. N/A.
• Purchasing desktop code-signing certificates — a procurement action (Apple Developer ~$99/yr, a Windows code-signing cert) that cannot be done in code. We implement the code-level Electron hardening and document the signing steps and certs to buy; we do not fake signing.
• Full fuzzing harness for federation input — valuable but multi-week; deferred. A handful of targeted negative/property tests on validateExternalUrl and S2S JSON parsing is in scope; a standing fuzz harness is not.
• TLS/cipher configuration — Caddy already auto-provisions HTTPS with modern defaults; we add security headers, not a TLS overhaul.

---

3. Tool Selection & Rationale

Where a "GitHub-native" option and a "committed-workflow" option overlap, we prefer committed workflow files — a self-hoster auditing the repo can read a .yml file; they cannot read repo settings. Settings-only toggles are documented as required manual steps, never claimed as code.

Scan class	Choice	Rationale
SAST	CodeQL (committed advanced workflow, default security suite to start)	Free for public repos, best TS/JS coverage, none build mode sidesteps monorepo/native-module build complexity. security-extended deferred to avoid a day-one triage tax.
Dependency CVEs	OSV-Scanner (blocking CI gate) + Dependabot (auto-upgrade PRs)	OSV-Scanner parses pnpm-lock.yaml v9 directly and can fail the build; Dependabot alerts are advisory-only. Two distinct roles, no overlap. Trivy is NOT used for dependency CVEs (avoids double-noise).
Secrets	gitleaks (committed, full history + PR diff) + documented native push-protection	gitleaks is the verifiable, blocking, history-aware gate; native push-protection is the complementary pre-commit net for the future.
Container image	Trivy (image scan, blocking)	SARIF output, ignore-unfixed: true for tiered policy, scans the exact GHCR image users pull.
IaC/config	Trivy config (Dockerfile, docker-compose)	Note: Trivy does not lint the Caddyfile; the reverse-proxy hardening is done by hand (§6.3).
License compliance	Trivy --scanners license with an allowlist	Dual-licensed AGPL + commercial → a copyleft-incompatible transitive dep is a legal defect. Reuses the Trivy we already run.
Supply chain	SHA-pinned actions + harden-runner (audit) + SBOM + SLSA provenance + OpenSSF Scorecard	Answers "can I trust the build?" and produces a public Scorecard badge.
Dynamic (DAST)	ZAP baseline against an ephemeral docker compose up (advisory)	Catches missing headers + CORS reflection continuously; the one dynamic check for a "webapp exposed to the internet."

---

4. Architecture — Component Layout

Each workflow file has one clear purpose (mirrors the codebase's module-boundary principle).

.github/
  dependabot.yml            NEW  — pnpm(npm) + github-actions + docker(Dockerfile only)
  workflows/
    codeql.yml              NEW  — CodeQL SAST (PR + push main + weekly)
    security.yml            NEW  — gitleaks + OSV-Scanner + Trivy config + Trivy license
    scorecard.yml           NEW  — OpenSSF Scorecard (push main + weekly) → Security tab + badge
    dast.yml                NEW  — ZAP baseline vs ephemeral compose stack (advisory)
    docker-publish.yml      EDIT — restructure for real image scanning + SBOM + provenance
    ci.yml                  EDIT — harden-runner (audit), tighten permissions
    release.yml             EDIT — harden-runner (audit), tighten permissions
    cla.yml                 EDIT
    deploy-pages.yml        EDIT

SHA-pinning applies to EVERY workflow — the four edited above, docker-publish.yml, and all four new ones (codeql/security/scorecard/dast). Pin every uses: to a full commit SHA with a trailing # vX.Y.Z comment. (OpenSSF Scorecard's Pinned-Dependencies check and tag-move attack resistance both require this repo-wide.)

Dockerfile                  EDIT — non-root USER, slim runtime, copy pruned node_modules
Caddyfile                   EDIT — security response headers
packages/server/src/index.ts      EDIT — @fastify/helmet + CSP; tighten CORS
packages/server/package.json      EDIT — add @fastify/helmet
packages/web/index.html           EDIT — CSP meta (defense in depth for static shell)
packages/desktop/src/main.ts      EDIT — will-navigate deny handler
packages/desktop/electron-builder.yml  EDIT — @electron/fuses / asar integrity
packages/desktop/package.json     EDIT — add @electron/fuses
README.md                   EDIT — badges + "Security & supply chain" section
SECURITY.md                 EDIT — "Security testing & assurance" section
docs/systems/security-scanning.md   NEW — full pipeline spec
docs/systems/desktop-security.md    NEW — Electron hardening + signing procurement
CLAUDE.md                   EDIT — add subsystem-table rows

---

5. Policy Engine (tiered enforcement)

Finding	Action
gitleaks secret hit	Block (always)
OSV-Scanner — fixable HIGH/CRITICAL	Block
Trivy image — fixable HIGH/CRITICAL (ignore-unfixed: true)	Block
Trivy license — disallowed license	Block
CodeQL — any alert	Advisory (SARIF → Security tab)
OSV/Trivy — unfixable, or medium/low	Advisory (SARIF → Security tab)
ZAP baseline (DAST)	Advisory (report artifact)
Scorecard	Advisory (score badge + Security tab)

Enforcement honesty — two mechanisms, kept separate:

• Code-enforced (auditable in the .yml): OSV-Scanner, Trivy, and gitleaks block via workflow exit codes.
• Settings-enforced (documented one-time toggles, NOT claimed as code): CodeQL merge-blocking (code-scanning merge protection), Dependabot alerts, native secret-scanning + push protection, and branch protection "require status checks." These live in docs/systems/security-scanning.md as a maintainer checklist.

---

6. Workstreams (bounded, independently reviewable)

Sequencing rule: WS1 scanners land report-only → WS5 remediation → flip WS1/WS2 enforcement to blocking. WS3/WS4 are otherwise independent and can land in parallel. Two cross-workstream dependencies to respect: (a) WS3 (CSP/CORS validation) and WS6's DAST job share the same two-instance + LiveKit ephemeral test rig — build it once, reuse it; (b) WS6's badges + maintainer checklist document state produced by WS1/WS2/WS5, so its final copy is written last (the workflow files can be scaffolded earlier).

WS1 — Scanning & supply-chain pipeline (report-only first)

• .github/dependabot.yml:
  • package-ecosystem: npm at / (Dependabot handles pnpm workspaces), weekly, grouped minor/patch.
  • ignore uiohook-napi — it is pinned by an exact-version patch (patches/uiohook-napi@1.5.5.patch); an unmatched bump breaks pnpm install --frozen-lockfile in CI and both Docker stages. Also treat onlyBuiltDependencies (better-sqlite3, esbuild, electron, sharp) bumps with care (grouped, expect native-rebuild churn).
  • package-ecosystem: github-actions at /.
  • package-ecosystem: docker at / — tracks the Dockerfile FROM only. No compose entry: docker-compose.yml sits at the same / directory (a second docker entry there would collide on ecosystem+directory), and Dependabot's docker ecosystem parses Dockerfiles, not image: refs in compose. The pinned caddy:2.11.1-alpine / livekit/livekit-server:v1.9.11 compose images are therefore updated manually — added as a line item to the maintainer checklist in docs/systems/security-scanning.md. (Renovate, which does parse compose, is noted there as an optional future alternative.)
• codeql.yml: languages javascript-typescript, default security queries, triggers PR + push main + weekly cron. SARIF uploaded.
• security.yml:
  • gitleaks — full history + PR diff, SARIF, block on hit.
  • OSV-Scanner — reads pnpm-lock.yaml; report-only initially, then block on fixable HIGH/CRITICAL after WS5.
  • Trivy config — Dockerfile + docker-compose misconfig, SARIF, advisory.
  • Trivy license — --scanners license against the dependency tree with an allowlist (permissive + AGPL-compatible); block on disallowed.
• scorecard.yml: ossf/scorecard-action, push main + weekly, publish results + badge.
• Harden all workflows (new and existing, incl. docker-publish.yml): pin every uses: to a full commit SHA (retain a # vX.Y.Z comment); add step-security/harden-runner in egress-policy: audit (not block — multi-arch buildx + QEMU + gha cache make many egress calls); tighten job-level permissions to least privilege.

WS2 — Container hardening & real image scanning

• Restructure docker-publish.yml (the current single multi-arch build-push cannot be scanned before publish):
  1. Build single-arch linux/amd64 with load: true.
  2. Trivy image scan (ignore-unfixed: true, block on fixable HIGH/CRITICAL), SARIF uploaded.
  3. On pass, the multi-arch (amd64,arm64) build-push with push: true, sbom: true, provenance: true. (Buildx cache makes the second build cheap.)
  • Trivy authenticates to GHCR with the same GITHUB_TOKEN used for login (the package may be private until manually flipped public).
• Dockerfile hardening:
  • Prune mechanics (precise): the builder runs a full pnpm install --frozen-lockfile (Dockerfile:25) whose node_modules is a symlinked .pnpm virtual store — a plain COPY --from=builder node_modules is not self-contained. Use pnpm --filter @backspace/server deploy --prod /app/deploy in the builder to produce a dereferenced/hoisted prod tree, then COPY --from=builder /app/deploy into the runtime stage. This replaces the runtime stage's own pnpm install --prod, letting python3 make g++ be dropped from runtime. Keep ffmpeg (real runtime dep) and keep tsx as a prod dependency (the CMD runs TS via tsx/esm). Verify better-sqlite3's prebuilt binary and tsx are present in the copied tree for both target arches.
  • Non-root + bind-mount chown (reconciled — the two are mutually exclusive if done naively): docker-compose.yml:31 bind-mounts host-owned ./data:/app/data. Chowning it requires root, so we do not hard-set a USER line (that would run the entrypoint as non-root and make the chown impossible). Instead: install gosu (or su-exec), add an ENTRYPOINT that (a) idempotently chowns /app/data to a fixed non-root UID, then (b) exec gosu <uid> "$@" to drop privileges — so the process runs non-root while the volume stays writable. The ENTRYPOINT must exec "$@" to preserve the existing WORKDIR /app/packages/server + CMD ["node","--import","tsx/esm","src/index.ts"] (Dockerfile:96-97). Ship a documented upgrade note; must not break existing self-hosters on docker pull + restart.

WS3 — Web/server hardening

Reality check (from review): this app renders arbitrary user-supplied content and is federated, so a restrictive img-src/media-src/connect-src is infeasible. A CSP here realistically constrains script-src / object-src / base-uri / frame-ancestors / form-action (the XSS/clickjacking-relevant directives) and stays permissive on content origins. Concretely:

• img-src / media-src must be broad (https: data: blob:): link-embed OG images (VideoEmbed.tsx, RichEmbed.tsx) come from any linked site, and GIF previews load directly from Klipy's CDN (routes/gif.ts returns file.url unproxied — the CDN host differs from api.klipy.com).
• connect-src must include the LiveKit wss:// origin, which is operator config (routes/livekit.ts returns config.livekit.url = LIVEKIT_URL verbatim) — so the CSP must be generated at runtime from config, not a static string. Federation (getApiForOrigin in exploreStore/socialStore/spaceStore) fetches/opens WS to peers discovered at runtime → connect-src must also allow https: wss: (peers aren't enumerable at build time).
• frame-src needs an explicit provider allowlist — YouTube, Vimeo, Spotify embed origins — or the embed iframes break (default frame-src 'self' blocks them).

Steps:

• Add @fastify/helmet. Build the CSP dynamically from config.livekit.url + the embed-provider list; ship it report-only first, validate against real flows (chat, cross-instance federation, embed render, upload, and a real voice join) with zero violations, then flip to enforcing.
• packages/web/index.html: CSP <meta> (defense-in-depth) — script/object/base directives only; do not duplicate the dynamic connect/img rules there.
• Caddyfile: Strict-Transport-Security, X-Content-Type-Options: nosniff, Referrer-Policy, and clickjacking protection via CSP frame-ancestors (prefer over X-Frame-Options). Ownership split (documented to avoid conflicts): Caddy owns HSTS + nosniff + Referrer-Policy; the app (helmet) owns the CSP. Don't set CSP in two places.
• CORS (packages/server/src/index.ts:46-48) — replace origin: true with a dynamic origin callback backed by the live federation-peer registry, NOT a static DOMAIN-derived list. Two breakages a static list would cause, both must be handled:
  • Federated browser uploads: browsers make cross-origin tus POST/HEAD/PATCH/ DELETE to peer /api/files/* (see the existing CORS-block comment at index.ts:50-64); peers are DB-backed and added after boot → the callback must consult the live registry, not a boot-time snapshot.
  • Desktop instance picker: packages/desktop/resources/instance-picker.html does a renderer fetch('<url>/api/instance/info') from a file:// document (Origin null). Keep /api/instance/info CORS-open (or move that probe to a main-process fetch) so the picker doesn't report instances as unreachable.
  • Federation note: S2S endpoints authenticate by HMAC and receive no browser Origin; verify they are unaffected by the two-instance federation integration suite.
• Rollout (phased, like the scanners): CSP report-only → observe → enforce; CORS gets a "log-and-allow" observation phase (log rejected origins without blocking) before switching to reject. Test-rig dependency: validating CSP + CORS here needs the two-instance + LiveKit harness (shared with the DAST env, §WS6/G2), which is heavier than a single-instance boot — call this out when scheduling.

WS4 — Desktop/Electron hardening

• Fuses without breaking the existing hook: electron-builder.yml:20 already declares afterPack: ./scripts/afterPack.js (it strips host-compiled uiohook-napi artifacts + cross-platform prebuilds), and electron-builder allows only one afterPack. So do not add a second hook. Prefer electron-builder's top-level electronFuses: config key (cleanest, no collision); if a fuse isn't expressible there, call @electron/fuses flipFuses() inside the existing scripts/afterPack.js. Fuses: disable RunAsNode + EnableNodeCliInspectArguments, enable OnlyLoadAppFromAsar. Asar-integrity caveat: it interacts with the existing asarUnpack: **/*.node (lines 17-18) and the afterPack that mutates app.asar.unpacked — integrity hashes must be computed after those mutations, and because builds are unsigned (release.yml:93) macOS integrity enforcement is limited; document this in desktop-security.md rather than over-claiming.
• will-navigate deny handler in main.ts: block foreign top-level navigations while allowing the initial https:// instance load and the file:// picker. Clarification (mechanism): the app is client-routed (history API → did-navigate-in-page), cross-instance switching uses main-process loadURL, and /join/* deep-links are handled by setWindowOpenHandler (main.ts:454) — none of these are will-navigate, so the deny handler is safe and setWindowOpenHandler stays untouched.
• docs/systems/desktop-security.md: document the current webPreferences posture (contextIsolation on, nodeIntegration off, sandbox on — main.ts:356-360), the fuses/asar posture and its unsigned-macOS limits, and — because release.yml:93 sets CSC_IDENTITY_AUTO_DISCOVERY: false (unsigned) — the exact signing + notarization steps and certificates to procure. Flag unsigned autoupdate as a known gap until signing is wired up.

WS5 — Remediation (after WS1 lands report-only)

• Run OSV-Scanner + Trivy + CodeQL; triage. Fix real HIGH/CRITICAL: direct upgrades, pnpm.overrides for transitive pins where no direct upgrade exists, code fixes for true-positive SAST findings. Dismiss false positives with written justification (.trivyignore / inline).
• SSRF hardening (fix, then test — not just test): the string-prefix isPrivateIp (utils/ssrf.ts:3-16) is genuinely bypassable — ::ffff:127.0.0.1 matches no branch and returns false (SSRF to loopback via an attacker AAAA record), and there is no 100.64.0.0/10 (CGNAT) or :: handling. Harden isPrivateIp: normalize IPv4-mapped IPv6, reject CGNAT and ::/unspecified, and normalize decimal/octal/hex hostname encodings — then add the negative/property tests for validateExternalUrl covering those vectors. The residual DNS-rebind TOCTOU is already documented (ssrf.ts:58-61) and stays out of scope (noted, not fixed).
• Then flip WS1/WS2 enforcement to blocking.

WS6 — Visible evidence, DAST & docs

• dast.yml (ZAP baseline): stands up an ephemeral instance and runs ZAP baseline (advisory). CI env override required — the production compose won't come up unmodified: Caddy uses {$DOMAIN} + ACME auto-HTTPS (hangs in CI without public DNS), backspace requires JWT_SECRET, livekit is profile-gated. Use a CI compose override that sets a test JWT_SECRET/DOMAIN and points ZAP directly at the backspace container :3000, bypassing Caddy (or Caddy internal/local TLS). This is the same two-instance-capable rig WS3 needs for CSP/CORS validation.
• README: CodeQL, OpenSSF Scorecard, and security-policy badges; a "Security & supply chain" section describing what runs on every change and where results are published.
• SECURITY.md: add a "Security testing & assurance" section enumerating the pipeline.
• docs/systems/security-scanning.md: full spec of every workflow, the tiered policy, and the maintainer settings checklist (§5) — including the repo-must-be- public precondition (Scorecard publish_results + badge and CodeQL free tier both require a public canonical repo) and the manual caddy/livekit compose-image update reminder (from WS1/F1).
• CLAUDE.md: add subsystem-table rows for security-scanning.md and desktop-security.md (required by the Documentation Rule — this is structural CI and architecture).
• Finalize WS6 last: badges + the maintainer checklist document state that only exists once WS1/WS2/WS5 land, so write the final copy after those are green (the workflow files can be scaffolded earlier).

---

7. Testing Strategy

• actionlint on every new/edited workflow.
• Real PR-branch run watching each check go green (or advisory) as intended.
• Canary proof of blocking: on a throwaway branch, introduce a fake secret and a known-vulnerable dependency; confirm gitleaks and OSV-Scanner actually fail the build; revert.
• WS2: docker build locally for amd64 + container boots + /api/health responds, before and after the Dockerfile changes; confirm the process runs non-root (via gosu step-down) yet still writes the host-owned ./data bind mount; confirm tsx + better-sqlite3 prebuilt are present in the pruned tree and the arm64 image still builds; confirm existing self-hosters survive pull + restart.
• WS3 (needs the two-instance + LiveKit rig): security headers present (curl/DevTools); zero CSP violations across chat, cross-instance federation, embed render (YouTube/Vimeo/Spotify + generic OG image), GIF, upload, and a real voice join; CORS callback permits the app origin and dynamically-registered peers (federated upload), keeps /api/instance/info open to the file:// picker (Origin null), and rejects an unknown origin; two-instance federation S2S suite still green.
• WS4: desktop app boots with fuses/asar-integrity applied and the existing afterPack native-module cleanup intact; will-navigate blocks a foreign top-level URL while the initial instance load, the file:// picker, and /join/* deep-links (via setWindowOpenHandler) still work.
• DAST: ZAP baseline runs against the CI compose override (bypassing Caddy) and produces a report artifact.
• Full suite (pnpm -r test) green throughout; existing federation/voice suites unaffected.

---

8. Risks & Mitigations

Risk	Mitigation
Enforcement day-one paints CI permanently red (May-2024 lockfile has fixable highs)	Report-only → remediate (WS5) → flip blocking.
Multi-arch image "scan" is theater / arm64 unscanned	WS2 restructure: single-arch load+scan → then multi-arch push.
Non-root USER breaks ./data bind-mount for existing self-hosters	Run entrypoint as root → chown → exec gosu <uid> step-down (no static USER); documented upgrade note; tested before/after.
Dependabot breaks CI via uiohook-napi patch / native rebuilds	ignore the patched dep; group onlyBuiltDependencies.
CSP too strict for a federated, arbitrary-content app	CSP built dynamically from config.livekit.url + peer registry; img/media/connect permissive; constrain only script/object/base/frame-ancestors; report-only → enforce.
CORS allowlist breaks federated uploads + desktop file:// picker	Dynamic origin callback backed by the live peer registry; keep /api/instance/info CORS-open; "log-and-allow" phase before rejecting.
Electron fuses overwrite the existing afterPack (native-module cleanup)	Use top-level electronFuses: key or call flipFuses() inside the existing scripts/afterPack.js; compute asar-integrity hashes after afterPack mutations.
pnpm symlinked .pnpm store makes a plain node_modules copy non-self-contained	Use pnpm --filter @backspace/server deploy --prod; verify tsx + better-sqlite3 prebuilt land per-arch; keep ffmpeg; boot test.
DAST/compose won't come up in CI (ACME/DOMAIN/JWT_SECRET)	CI compose override with test env; point ZAP at backspace:3000, bypass Caddy.
harden-runner block mode false-positives the Docker build	Start in audit; graduate to block only on lightweight jobs.
Scorecard badge / CodeQL free tier assume a public repo	Documented as an explicit precondition in the maintainer checklist.

---

9. Definition of Done

• All new workflows present, actionlint-clean, and green on a real PR.
• Blocking gates proven by canary (secret + vuln), then reverted.
• Security tab populated (CodeQL, Scorecard, advisory Trivy/OSV) with no open fixable HIGH/CRITICAL after WS5.
• helmet + CSP + Caddyfile headers live with no CSP violations in normal use; CORS allowlisted; federation suite green.
• Electron fuses + will-navigate live; desktop boots and deep-links work; existing afterPack native-module cleanup intact.
• isPrivateIp hardened (IPv4-mapped IPv6 / CGNAT / :: / alt-encodings) with passing negative tests.
• Container image scanned before publish; SBOM + provenance attached; Dockerfile runs non-root (gosu step-down) with a working data volume.
• README badges + Security section; SECURITY.md expanded; docs/systems/security-scanning.md + docs/systems/desktop-security.md written; CLAUDE.md subsystem table updated.
• Maintainer settings checklist documented (CodeQL merge protection, Dependabot alerts, push protection, branch protection).