From cb524675cc54e4ddaf9594123932c569c99b043d Mon Sep 17 00:00:00 2001 From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com> Date: Sun, 12 Jul 2026 23:38:03 +0200 Subject: [PATCH] docs(security): document the scanning pipeline + maintainer checklist --- CLAUDE.md | 1 + docs/systems/security-scanning.md | 51 +++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 docs/systems/security-scanning.md diff --git a/CLAUDE.md b/CLAUDE.md index e9e72ba2..cce3a36d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -160,6 +160,7 @@ Before modifying any subsystem, read its spec from `docs/systems/`. After making | [message-list.md](docs/systems/message-list.md) | Auto-scroll model, position memory (session-only), embed renderer dimension contract, known limitations | Touching MessageList.tsx, scroll behavior, embed renderers, position restore | | [deployment.md](docs/systems/deployment.md) | Hosting pipeline: Docker/Caddy build, admin bootstrap, DB backup/restore, image pinning, env vars | Any deploy, backup/restore, or hosting change | | [activity-presence.md](docs/systems/activity-presence.md) | Presence states, rich activities, activity types/priorities, broadcast pipeline, visibility control, ActivityCard/Panel | Presence, rich activities, activity display, status management | +| [security-scanning.md](docs/systems/security-scanning.md) | CI security pipeline: Dependabot, CodeQL SAST, gitleaks, OSV-Scanner, Trivy (config/image/license), OpenSSF Scorecard, SHA-pinning, harden-runner, tiered enforcement policy, maintainer settings checklist | Any CI security work, adding/changing scanners, enabling enforcement, supply-chain hardening | --- diff --git a/docs/systems/security-scanning.md b/docs/systems/security-scanning.md new file mode 100644 index 00000000..9504e355 --- /dev/null +++ b/docs/systems/security-scanning.md @@ -0,0 +1,51 @@ +# Security Scanning & Supply-Chain Assurance + +Automated, continuous scanning wired into GitHub Actions. This document is the +reference for what runs, where results go, and the one-time settings a maintainer +must enable. **Current state: report-only** — scanners surface findings in the +Security tab but do not block merges yet. Enforcement (blocking) is turned on in a +later change once the remediation pass has cleared the backlog. + +## Workflows + +| File | Purpose | Trigger | Result | +|------|---------|---------|--------| +| `.github/dependabot.yml` | Dependency + action + base-image update PRs | weekly | PRs | +| `.github/workflows/codeql.yml` | CodeQL SAST (`javascript-typescript`, build-mode none) | PR + push main + weekly | Security tab | +| `.github/workflows/security.yml` | gitleaks (secrets, full history), OSV-Scanner (deps), Trivy config (IaC), Trivy license | PR + push main + weekly | Security tab | +| `.github/workflows/scorecard.yml` | OpenSSF Scorecard (repo posture) | push main + weekly | Security tab + public badge | + +## Tiered policy (target, enforced in a later change) + +- **Always block:** gitleaks secret hit; OSV/Trivy fixable HIGH/CRITICAL; Trivy + disallowed license. +- **Advisory (SARIF → Security tab):** CodeQL alerts; OSV/Trivy unfixable or + medium/low; Scorecard. + +Code-level gates (OSV, Trivy, gitleaks) block via workflow exit codes. CodeQL +merge-blocking, Dependabot alerts, and native secret-scanning are GitHub *settings* +— see the checklist below. + +## Supply-chain hardening + +- Every action is pinned to a full commit SHA (`# vX.Y.Z` comment) — resists + tag-move attacks and satisfies Scorecard's Pinned-Dependencies check. +- `step-security/harden-runner` (egress-policy `audit`) on Linux jobs. +- Least-privilege `permissions:` per workflow/job. +- SBOM + SLSA provenance are attached to the published container image (added with + the image-scan work). + +## Maintainer checklist (one-time GitHub settings — NOT code) + +- [ ] Repository must be **public** (required for the Scorecard badge/publish and + the CodeQL free tier). +- [ ] Settings → Code security: enable **Dependabot alerts** and **Dependabot + security updates**. +- [ ] Settings → Code security: enable **Secret scanning** + **Push protection**. +- [ ] Settings → Code security: enable **CodeQL / code-scanning merge protection** + so high-severity alerts block PRs (the code-level gates do the rest). +- [ ] Branch protection on `main`: require the CI + security status checks to pass. +- [ ] **Manual image bumps:** Dependabot does not track `docker-compose.yml` + `image:` pins — update `caddy` and `livekit/livekit-server` by hand when new + releases ship. (Renovate, which parses compose, is an optional future + alternative.)