From 600f5796f1dbc23c32e336771f8f59781daef034 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 27 Jul 2026 16:12:07 -0700 Subject: [PATCH] docs(security): document the automated security-scanning posture (#2182 #2142 #2272) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #2917 shipped the security-CI trio (OSV-Scanner, Semgrep CE SAST, release-binary attestations) but landed no contributor/user-facing docs. This adds the functional posture notes the issues asked for: - SECURITY.md: "Automated security scanning" section — what runs, when, and the gh attestation verify commands for release binaries (#2142 item 4). - CONTRIBUTING.md: PR-side note that Semgrep is advisory/non-blocking while the baseline is tuned (#2272 item 5), plus when OSV-Scanner and actionlint fire on a PR. No workflow changes: the audit found all three workflows already on master, green, SHA-pinned, least-privilege, with the reusable-workflow caller-permission superset already granted. Co-authored-by: maxpetrusenkoagent Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 8 ++++++++ SECURITY.md | 24 ++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ebc68cd93..85fe06761 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,6 +163,14 @@ host port with `GBRAIN_CI_PG_PORT=5435 bun run ci:local` if 5434 collides. Fail-closed selector: an unmapped `src/` change runs all 29 E2E files. Hand-tune narrower mappings via `scripts/e2e-test-map.ts`. +### PR-side security checks + +Besides the test gate, PRs may trigger three security workflows: Semgrep CE +SAST (every PR — **advisory/non-blocking** while the baseline is tuned, so a +Semgrep finding won't fail your PR), OSV-Scanner (only when `package.json` or +`bun.lock` change), and actionlint (only when `.github/workflows/**` change). +See `SECURITY.md` → "Automated security scanning" for details. + ## Building ```bash diff --git a/SECURITY.md b/SECURITY.md index 833809205..da709bfd8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,6 +8,30 @@ on GitHub. Do not open a public issue for security vulnerabilities. +## Automated security scanning + +CI runs three automated security checks alongside secret scanning (Gitleaks): + +- **Dependency vulnerabilities** — OSV-Scanner + (`.github/workflows/osv-scanner.yml`) runs weekly and on any PR that touches + `package.json` or `bun.lock`. +- **Static analysis (SAST)** — Semgrep CE (`.github/workflows/semgrep.yml`) + runs on every PR and weekly. It is currently **advisory (non-blocking)** + while the finding baseline is tuned; the graduation path to a blocking check + is documented in the workflow file. +- **Release binary provenance** — release builds + (`.github/workflows/release.yml`) attest each compiled binary with + [GitHub artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations). + Verify a downloaded release binary with: + + ```bash + gh attestation verify ./gbrain-darwin-arm64 -R garrytan/gbrain + gh attestation verify ./gbrain-linux-x64 -R garrytan/gbrain + ``` + +All security workflows use SHA-pinned actions and least-privilege permissions, +enforced structurally by actionlint on every workflow change. + ## Remote MCP Security ### ⚠️ Do NOT use open OAuth client registration for remote MCP