orchestrator/security-review

security-review

The Sea Haven security-review gate. One pure-code script (review.sh) is the decision-maker; everything else (hooks, the interactive skill, the headless runner, the nightly sweep) is a trigger that feeds it. See memory project-security-review-agent for the full design.

Pieces

• review.sh — merges deterministic-scanner findings + agent findings, dedups, applies suppressions (justification required), and makes the block decision (no agent decides). Exit 1 = BLOCK.
• hooks/pre-commit, hooks/pre-push + install-hooks.sh — fast --scanners-only gates. Install once globally for every repo, or per-repo (see below).
• skill/sh-security-review.md — the interactive agentic detector/verifier prompt (Path A, Max-covered). finding.schema.json — the structured finding contract both paths emit. install-hooks.sh --global links these into ~/.claude/ (this repo is the source of truth).
• run_headless.py — the Path B headless detector fan-out + proof-or-kill verifier (Claude Agent SDK, subscription OAuth). Self-contained: prompts are inline, so the VM needs no ~/.claude assets to run it.
• nightly_sweep.sh + systemd/ — the unattended two-tier sweep on the sh-secrev VM (R720).

Triggers (one script, many entry points)

• On-demand (primary): run /sh-security-review in a Claude Code session (Max-covered), have it write its schema JSON, then review.sh --agent-findings out.json <repo> to gate. Required before pushing payments/auth/IaC/input-handling changes (see the global CLAUDE.md security-review rule).
• Pre-commit / pre-push: the global git hooks run deterministic scanners automatically.
• Nightly: the VM sweep (Path B) is the unattended backstop.

Installing the hooks

# Global — gate EVERY repo on this machine, and link the skill + schema into ~/.claude:
security-review/install-hooks.sh --global

# Per-repo — for a repo that sets its own core.hooksPath (e.g. husky) and would shadow the global hook:
security-review/install-hooks.sh /path/to/repo

The global mode sets git config --global core.hooksPath ~/.config/git/hooks. Skip a repo with a .security-review-skip file at its root; bypass once with git push --no-verify. Caveat: a repo with its own local core.hooksPath overrides the global hook — install per-repo there. See memory reference_global_security_review_hook.

Suppressing a false positive. A written justification is required and is surfaced in the report. The hooks resolve a suppressions file in this order:

1. Machine-level (preferred), kept out of repo history: ${SH_SECURITY_SUPPRESSIONS_DIR:-~/.config/sea-haven/security-review}/<repo-basename>/suppressions.json (override the base dir with SH_SECURITY_SUPPRESSIONS_DIR). Keeps a suppression from becoming a permanent in-history "ignore."
2. Repo-local fallback: <repo>/.security-review/suppressions.json (used only if no machine-level file exists).

Same JSON either place: {"suppressions":[{"id":"<review.sh finding id>","justification":"…"}]}. Caveat: machine-level files are keyed by repo basename, so two repos sharing a name collide — fine for the current single-namespace layout under ~/Documents/repositories.

No CI — by design

There is no CI wiring for this gate. For a solo dev the git hooks + nightly VM sweep are the backstop, so the parked CI drafts (ci/*.yml, CI-BACKSTOP-NOTES.md) were removed; recover them from git history (the commit that deleted security-review/ci/) if the team ever goes multi-dev. The orchestrator repo's own ci.yaml (ruff + tests) is unrelated and stays.

Scanners

review.sh runs whatever is installed and logs the rest with install commands (no silent skips): semgrep (p/security-audit + p/secrets + p/javascript), gitleaks (git-mode — scans committed history, respects .gitignore), checkov, cfn-lint, pip-audit, npm audit. Each is normalized into the finding schema. Install the full set:

pipx install semgrep pip-audit checkov   # SAST / vulnerable Python deps / IaC misconfig
brew install gitleaks                      # hardcoded secrets
# cfn-lint via pip; Node.js provides npm audit

Nightly sweep (Path B) — two-tier, clean-clone auto-discovery

nightly_sweep.sh runs on the sh-secrev Ubuntu VM (R720) and needs no per-repo wiring. It:

1. Discovers every non-archived Sea-Haven-Industries repo via the GitHub REST API (curl + a read-only GH_TOKEN; no gh CLI dependency) and mirrors each as a shallow clean clone (git clone --depth=1, default branch from the API) into ~/repo-mirrors. Scanning server-side clones — not developer working trees — structurally keeps local gitignored .env secrets out of scope.
2. Tier 1 (every repo, every night, $0 Claude): review.sh --scanners-only over every mirror — complete deterministic baseline coverage.
3. Tier 2 (bounded agentic): run_headless.py over a deterministic round-robin rotation that fits TOTAL_BUDGET_USD, with a persistent cycle pointer so every repo gets a deep pass within MAX_CYCLE_NIGHTS. This bounds the draw on the shared Max limits (a clean night never deep-scans all repos). A COVERAGE ALARM fires if the rotation falls behind.

It is ALARM-only: a clean night posts nothing. See memory feedback_cloudwatch_alarms.

Skip / override

• A repo is skipped if it commits a .security-review-skip marker or is listed in the central skip file (~/.secrev-skip.txt, one repo name per line). Repos skipped via their own committed marker are logged in the report so a sensitive repo can't silently self-exclude.
• TARGETS="/path/a /path/b" overrides discovery entirely (scan explicit paths, no cloning).
• The canary corpus (~/security-review-testbed) is always scanned agentically first as the anti-complacency check — independent of the skip filter.

Anti-complacency + guards

• Canary check: the testbed MUST block AND surface ≥ CANARY_FLOOR (default 10) confirmed crit/high. Otherwise → COMPLACENCY ALARM. The corpus now includes Node + .NET fixtures (see the testbed key); re-tune the floor after the first VM canary run reports the expanded recall number.
• Budget ceiling: TOTAL_BUDGET_USD (default 120 — full deep-pass coverage of every repo per night) caps aggregate agentic spend; PER_TARGET_BUDGET_USD (default 12) caps each repo; MAX_AGENTIC_PER_NIGHT (default 0 = unlimited) optionally caps wall-clock. With the SDK-billing split deferred (memory reference-claude-subscription-billing), spend draws from the Max subscription limits, so the two-tier design keeps full coverage cheap and bounds the agentic draw.
• Two-model hook (optional, off): ENABLE_XMODEL_HOOK=1 re-checks each confirmed CRITICAL with the orchestrator cross-family reviewer (GPT-4.1) and flags disagreement; skips gracefully, never fails the sweep.
• Redaction: secret-shaped values are masked in the Slack ALARM string; on-disk reports are mode 600.

Secrets / env (~/secrev.env, mode 600)

• CLAUDE_CODE_OAUTH_TOKEN — required (run_headless.py pops ANTHROPIC_API_KEY).
• GH_TOKEN — read-only fine-grained PAT scoped to the org (Contents + Metadata: read-only, nothing else) for discovery + cloning. Never give this unattended box a write-capable token.
• SLACK_WEBHOOK_URL — alarms (plain incoming-webhook). ~/orchestrator/.env → OPENAI_API_KEY (xmodel hook only).
• Reports + per-target JSON land under ~/sweep-reports/<UTC-date>/.

Install the timer

Units are in systemd/; full runbook is DEPLOY-R720.md. On the VM:

sudo cp systemd/sea-haven-secrev.{service,timer} /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sea-haven-secrev.timer   # the timer drives it; do not enable the .service
sudo systemctl start sea-haven-secrev.service        # optional one-off smoke test

The timer fires nightly at ~02:00 local (Persistent=true catches missed runs after downtime).