security: document red team cadence
Jaime Fournier <jaimef@linbsd.org>
11f4827cdd6843f2a735ad3d5c094c02c00bd0ba
--- a/SECURITY.md +++ b/SECURITY.md @@ -9,6 +9,8 @@ Implemented security behavior is documented in [`docs/security-reference.md`](docs/security-reference.md). Production claims require the gates in [`docs/release-security.md`](docs/release-security.md) and the cross-repository tracker at `~/mine/jerboa-production-readiness.md`. +Repeatable AI-assisted adversarial review follows +[`docs/security-red-team.md`](docs/security-red-team.md). The prioritized security backlog and implementation handoff lives in [`docs/kimi3-security-recommmendations.md`](docs/kimi3-security-recommmendations.md). --- a/docs/index.md +++ b/docs/index.md @@ -71,6 +71,7 @@ work. ## Security - [security-reference.md](security-reference.md) - canonical reference for implemented security features, gates, and current limitations +- [security-red-team.md](security-red-team.md) - repeatable AI-assisted red-team review protocol - [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md) - prioritized security backlog and implementation handoff - [safety-guide.md](safety-guide.md) - practical secure-application guide for Jerboa programs - [release-security.md](release-security.md) - release gates and security evidence --- a/docs/kimi3-security-recommmendations.md +++ b/docs/kimi3-security-recommmendations.md @@ -900,6 +900,11 @@ P1 landing. Also drive the open sibling-repo findings (§4.4 item 6) to resolution in their own repos — do not patch them from here (repository boundary rule), but track them in the cross-repo readiness file. +- **Status:** complete for the repository-local standing protocol. + `docs/security-red-team.md` now defines cadence, inputs, review prompts, + required outputs, cross-repo handling, and closeout gates. `docs/index.md` + and `SECURITY.md` link it as stable security-process documentation. + ### K3-P2-05 — Scanner rule growth and pre-commit wiring **Serves:** G3. **Effort:** continuous; 2 days to wire. new file mode 100644 --- /dev/null +++ b/docs/security-red-team.md @@ -0,0 +1,73 @@ +# Security Red-Team Protocol + +Updated 2026-07-27. + +This protocol keeps Jerboa's security review repeatable. It is for maintainers +running adversarial reviews against the language, standard library, build +system, package tooling, LSP, MCP server, native runtime, and release pipeline. + +## Cadence + +Run an AI-assisted red-team review: + +- Quarterly. +- After every P1 security landing in + [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md). +- Before any production release candidate. +- After materially changing sandboxing, FFI, package verification, release + signing, secret handling, or safe-prelude behavior. + +## Inputs + +Start each review from a fresh model/session. Provide only repository-local +context unless the review is explicitly about release infrastructure: + +- `SECURITY.md` +- [docs/security-reference.md](security-reference.md) +- [docs/release-security.md](release-security.md) +- [docs/ai-threat.md](ai-threat.md) +- [docs/kimi3-security-recommmendations.md](kimi3-security-recommmendations.md) +- `.jerboa-system` +- The changed files since the last review or release candidate + +For cross-repository issues, record the finding and owner, but do not patch a +sibling checkout from this repository. + +## Review Prompts + +Ask the reviewer to produce exploit-shaped findings, not broad advice. Cover: + +- Untrusted code evaluation, safe-prelude escape routes, raw `eval`, `load`, + native FASL, macro expansion, and reader behavior. +- FFI and native Rust/C boundaries: nullability, width truncation, bounds, + collect-safety, callback lifetime, and signal/fork interactions. +- Filesystem, subprocess, network, package-install, and release-artifact paths. +- Secret handling in env, argv, logs, errors, audit records, and generated + evidence. +- Sandbox confinement on Linux, macOS, FreeBSD, and unsupported platforms. +- Documentation drift: implemented claims must match tests and release gates. + +## Required Outputs + +Every review must produce one of these outcomes: + +- No new findings, with the exact commit range reviewed and commands run. +- A finding in [docs/kimi3-security-recommmendations.md](kimi3-security-recommmendations.md) + with priority, affected surface, acceptance criteria, and verification plan. +- A normalized anti-pattern in `data/anti-patterns.sexp` when the finding is a + reusable model or engineering mistake. +- An exploit-shaped regression test under `tests/security/` or a scanner rule + in `data/security-rules.sexp` when the behavior can be detected mechanically. +- A cross-repo readiness note for issues owned outside this repository. + +## Verification + +Close a review only after the relevant gates run or the blocker is explicit: + +- Local language/security changes: `make audit`, `make test-security`, and the + focused test for the touched subsystem. +- Release-pipeline changes: `make release-evidence` or a documented blocker + plus the focused evidence target. +- Documentation-only reviews: `make check-docs`. + +Record any external blocker with the failing command and concrete error text.