2026-06-29 11:41:41 -04:00
|
|
|
# security-review
|
|
|
|
|
|
2026-07-06 17:24:21 -04:00
|
|
|
[](https://github.com/Sea-Haven-Industries/security-review/actions/workflows/ci.yaml)
|
|
|
|
|
[](https://github.com/Sea-Haven-Industries/security-review/actions/workflows/dependency-review.yml)
|
|
|
|
|
|
|
|
|
|
|
2026-06-29 11:41:41 -04:00
|
|
|
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).
|
2026-07-14 19:24:01 -04:00
|
|
|
- `run_headless.py` — the headless detector fan-out + proof-or-kill verifier (Claude Agent SDK,
|
|
|
|
|
subscription OAuth). Self-contained: prompts are inline, so the host needs no `~/.claude` assets to run it.
|
|
|
|
|
- `cross_review.py` — the mandatory cross-family GPT-4.1 reviewer CLI (see its section below).
|
|
|
|
|
- `nightly_sweep.sh` — the retired VM-based two-tier sweep, retained for reference; the automated
|
|
|
|
|
sweep now runs as Claude Code web cloud routines (see below).
|
2026-06-29 11:41:41 -04:00
|
|
|
|
|
|
|
|
## 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.
|
2026-07-14 19:24:01 -04:00
|
|
|
- **Scheduled:** the Claude Code web cloud routines are the unattended backstop (see below).
|
2026-06-29 11:41:41 -04:00
|
|
|
|
|
|
|
|
### Installing the hooks
|
|
|
|
|
```
|
|
|
|
|
# Global — gate EVERY repo on this machine, and link the skill + schema into ~/.claude:
|
|
|
|
|
./install-hooks.sh --global
|
|
|
|
|
|
|
|
|
|
# Per-repo — for a repo that sets its own core.hooksPath (e.g. husky) and would shadow the global hook:
|
|
|
|
|
./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`.
|
|
|
|
|
|
2026-08-06 19:29:04 -04:00
|
|
|
If `review.sh` is missing or not executable at the configured path, the pre-push hook **fails closed**
|
|
|
|
|
(nonzero exit) instead of skipping the gate. Repair by setting `SH_REVIEW_SH` to the scanner path, or
|
|
|
|
|
reinstall with `./install-hooks.sh --global`.
|
|
|
|
|
|
2026-07-14 19:24:01 -04:00
|
|
|
- `--global` also creates the machine-level suppressions dir
|
|
|
|
|
(`${SH_SECURITY_SUPPRESSIONS_DIR:-~/.config/sea-haven/security-review}`): the per-repo file
|
|
|
|
|
`<dir>/<repo-basename>/suppressions.json` is preferred by the hooks over repo-local
|
|
|
|
|
`.security-review/suppressions.json`, and `review.sh` merges both when run without `--suppressions`.
|
|
|
|
|
|
feat(scanner): auto-resolve + merge suppressions when --suppressions absent (#4)
review.sh only applied suppressions when handed an explicit --suppressions
FILE, so only the pre-push hook resolved them. Every other entry point (the
Open SWE daily-report automation, nightly sweep, on-demand/CI, agent runs)
called review.sh without it and therefore suppressed nothing, re-surfacing
every already-adjudicated false positive as HIGH.
When --suppressions is not passed, resolve by repo basename and MERGE both
suppression locations (machine-level first, wins id collisions):
- machine-level: ${SH_SECURITY_SUPPRESSIONS_DIR:-~/.config/sea-haven/security-review}/<basename>/suppressions.json
- repo-local: <repo>/.security-review/suppressions.json
An explicit --suppressions still overrides, so the hook and existing callers
are unaffected. Degrades gracefully off-Mac (repo-local only); fail-safe on an
unparseable file (suppresses nothing → blocks).
SECURITY (/sh-security-review, 2026-07-13): fan-out + proof-or-kill confirmed
one HIGH — the git-tracked repo-local suppressions.json lets anyone who can
commit to a scanned repo suppress a real finding and PASS an automated run
(verified by an actual exploit run; same posture nightly_sweep already had).
ACCEPTED-RISK per Adam on the condition that the automated scanners only ever
target trusted repos (no unreviewed untrusted contributions). Documented in the
auto-resolve block, README trust-model note, and a hard warning in
sweep-targets.txt. Four other candidates downgraded to low/pre-existing.
Verified: machine-level and repo-local both auto-resolve and suppress; explicit
--suppressions override still blocks; simulated off-Mac host keeps repo-local
and correctly re-blocks machine-level-only FPs.
2026-07-13 14:33:27 -04:00
|
|
|
**Suppressing a false positive.** A written justification is required and is surfaced in the report.
|
|
|
|
|
When no `--suppressions FILE` is passed, `review.sh` auto-resolves and **merges** suppressions from
|
|
|
|
|
two locations (an explicit `--suppressions` still overrides both):
|
2026-06-29 11:41:41 -04:00
|
|
|
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."
|
feat(scanner): auto-resolve + merge suppressions when --suppressions absent (#4)
review.sh only applied suppressions when handed an explicit --suppressions
FILE, so only the pre-push hook resolved them. Every other entry point (the
Open SWE daily-report automation, nightly sweep, on-demand/CI, agent runs)
called review.sh without it and therefore suppressed nothing, re-surfacing
every already-adjudicated false positive as HIGH.
When --suppressions is not passed, resolve by repo basename and MERGE both
suppression locations (machine-level first, wins id collisions):
- machine-level: ${SH_SECURITY_SUPPRESSIONS_DIR:-~/.config/sea-haven/security-review}/<basename>/suppressions.json
- repo-local: <repo>/.security-review/suppressions.json
An explicit --suppressions still overrides, so the hook and existing callers
are unaffected. Degrades gracefully off-Mac (repo-local only); fail-safe on an
unparseable file (suppresses nothing → blocks).
SECURITY (/sh-security-review, 2026-07-13): fan-out + proof-or-kill confirmed
one HIGH — the git-tracked repo-local suppressions.json lets anyone who can
commit to a scanned repo suppress a real finding and PASS an automated run
(verified by an actual exploit run; same posture nightly_sweep already had).
ACCEPTED-RISK per Adam on the condition that the automated scanners only ever
target trusted repos (no unreviewed untrusted contributions). Documented in the
auto-resolve block, README trust-model note, and a hard warning in
sweep-targets.txt. Four other candidates downgraded to low/pre-existing.
Verified: machine-level and repo-local both auto-resolve and suppress; explicit
--suppressions override still blocks; simulated off-Mac host keeps repo-local
and correctly re-blocks machine-level-only FPs.
2026-07-13 14:33:27 -04:00
|
|
|
2. **Repo-local:** `<repo>/.security-review/suppressions.json` (tracked; travels with the repo).
|
|
|
|
|
|
|
|
|
|
Both files' `.suppressions[]` are concatenated (machine-level first, so it wins any id collision).
|
2026-07-14 19:24:01 -04:00
|
|
|
This means every entry point — the pre-push hook, the scheduled sweeps, on-demand/CI runs, and the
|
feat(scanner): auto-resolve + merge suppressions when --suppressions absent (#4)
review.sh only applied suppressions when handed an explicit --suppressions
FILE, so only the pre-push hook resolved them. Every other entry point (the
Open SWE daily-report automation, nightly sweep, on-demand/CI, agent runs)
called review.sh without it and therefore suppressed nothing, re-surfacing
every already-adjudicated false positive as HIGH.
When --suppressions is not passed, resolve by repo basename and MERGE both
suppression locations (machine-level first, wins id collisions):
- machine-level: ${SH_SECURITY_SUPPRESSIONS_DIR:-~/.config/sea-haven/security-review}/<basename>/suppressions.json
- repo-local: <repo>/.security-review/suppressions.json
An explicit --suppressions still overrides, so the hook and existing callers
are unaffected. Degrades gracefully off-Mac (repo-local only); fail-safe on an
unparseable file (suppresses nothing → blocks).
SECURITY (/sh-security-review, 2026-07-13): fan-out + proof-or-kill confirmed
one HIGH — the git-tracked repo-local suppressions.json lets anyone who can
commit to a scanned repo suppress a real finding and PASS an automated run
(verified by an actual exploit run; same posture nightly_sweep already had).
ACCEPTED-RISK per Adam on the condition that the automated scanners only ever
target trusted repos (no unreviewed untrusted contributions). Documented in the
auto-resolve block, README trust-model note, and a hard warning in
sweep-targets.txt. Four other candidates downgraded to low/pre-existing.
Verified: machine-level and repo-local both auto-resolve and suppress; explicit
--suppressions override still blocks; simulated off-Mac host keeps repo-local
and correctly re-blocks machine-level-only FPs.
2026-07-13 14:33:27 -04:00
|
|
|
Open SWE daily-report automation — resolves suppressions identically. **Portability note:** hosts that
|
2026-07-14 19:24:01 -04:00
|
|
|
cannot see the Mac's `~/.config` (the Open SWE automation, the cloud routines) get only the tracked
|
|
|
|
|
repo-local file, so a suppression that must be honored off-Mac has to live repo-local. Fail-safe: if a file is
|
feat(scanner): auto-resolve + merge suppressions when --suppressions absent (#4)
review.sh only applied suppressions when handed an explicit --suppressions
FILE, so only the pre-push hook resolved them. Every other entry point (the
Open SWE daily-report automation, nightly sweep, on-demand/CI, agent runs)
called review.sh without it and therefore suppressed nothing, re-surfacing
every already-adjudicated false positive as HIGH.
When --suppressions is not passed, resolve by repo basename and MERGE both
suppression locations (machine-level first, wins id collisions):
- machine-level: ${SH_SECURITY_SUPPRESSIONS_DIR:-~/.config/sea-haven/security-review}/<basename>/suppressions.json
- repo-local: <repo>/.security-review/suppressions.json
An explicit --suppressions still overrides, so the hook and existing callers
are unaffected. Degrades gracefully off-Mac (repo-local only); fail-safe on an
unparseable file (suppresses nothing → blocks).
SECURITY (/sh-security-review, 2026-07-13): fan-out + proof-or-kill confirmed
one HIGH — the git-tracked repo-local suppressions.json lets anyone who can
commit to a scanned repo suppress a real finding and PASS an automated run
(verified by an actual exploit run; same posture nightly_sweep already had).
ACCEPTED-RISK per Adam on the condition that the automated scanners only ever
target trusted repos (no unreviewed untrusted contributions). Documented in the
auto-resolve block, README trust-model note, and a hard warning in
sweep-targets.txt. Four other candidates downgraded to low/pre-existing.
Verified: machine-level and repo-local both auto-resolve and suppress; explicit
--suppressions override still blocks; simulated off-Mac host keeps repo-local
and correctly re-blocks machine-level-only FPs.
2026-07-13 14:33:27 -04:00
|
|
|
present but unparseable, nothing is suppressed (the gate blocks).
|
|
|
|
|
|
|
|
|
|
> **⚠️ Trust model — automated scanners must target TRUSTED repos only.** The repo-local
|
|
|
|
|
> `.security-review/suppressions.json` is git-tracked, so anyone who can land a commit in a scanned
|
|
|
|
|
> repo can suppress a real finding by committing it alongside the vuln (scanner IDs are deterministic).
|
|
|
|
|
> `/sh-security-review` confirmed this as a HIGH gate-bypass; it is **accepted** on the condition that
|
|
|
|
|
> the automated scanners (Open SWE daily report, nightly sweep) only ever scan repos that do **not**
|
|
|
|
|
> merge untrusted contributions without human review. See `sweep-targets.txt`. Relaxing that scoping
|
|
|
|
|
> requires a trust check first (signed / CODEOWNERS-verified repo-local suppressions).
|
2026-06-29 11:41:41 -04:00
|
|
|
|
|
|
|
|
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`.
|
|
|
|
|
|
|
|
|
|
## CI
|
|
|
|
|
The CI here (`.github/workflows/`) is standard org code-hygiene for **this repo's own source** (ruff
|
|
|
|
|
lint/format + a `pytest --collect-only` import check, via the `Sea-Haven-Industries/.github` reusable
|
|
|
|
|
workflows) — it is **not** a security gate over other repos. The gate itself is intentionally *not*
|
|
|
|
|
CI-wired: for a solo dev the git hooks plus the scheduled sweeps are the backstop. The parked CI-backstop
|
|
|
|
|
drafts (`ci/*.yml`, `CI-BACKSTOP-NOTES.md`) were removed earlier; recover them from history if the team
|
|
|
|
|
ever goes multi-dev.
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
```
|
|
|
|
|
|
2026-07-14 19:24:01 -04:00
|
|
|
## Scheduled execution — Claude Code web cloud routines
|
|
|
|
|
The automated sweep runs as **Claude Code web cloud routines**, both **ALARM-only** to Slack
|
|
|
|
|
`#repo-scanner` (a clean run posts nothing — see memory `feedback_cloudwatch_alarms`):
|
|
|
|
|
|
|
|
|
|
- **repo-scanner-nightly-sweep** — daily 08:00 ET: the agentic two-tier sweep (deterministic
|
|
|
|
|
scanners over every repo, plus the bounded agentic detector/verifier rotation).
|
|
|
|
|
- **repo-checkers-plane1** — daily 07:30 ET: the deterministic `checker_coordinator.sh` (the script
|
|
|
|
|
owns the findings + ALARM decision; the routine relays its output verbatim, never re-judging).
|
|
|
|
|
|
|
|
|
|
The VM-based Path B sweep is **retired** (the sweep VM was destroyed); its host artifacts (the
|
|
|
|
|
`systemd/` units and the `DEPLOY-R720.md` runbook) are deleted — recover them from git history if
|
|
|
|
|
ever needed. `nightly_sweep.sh` is retained in-repo as the reference implementation of the two-tier
|
|
|
|
|
design: GitHub REST API auto-discovery into shallow clean clones, Tier 1 `review.sh --scanners-only`
|
|
|
|
|
over every mirror, Tier 2 bounded agentic `run_headless.py` round-robin rotation, canary
|
|
|
|
|
anti-complacency floor, budget ceilings, and secret redaction. Its optional `ENABLE_XMODEL_HOOK=1`
|
|
|
|
|
critical tiebreak now calls this repo's `cross_review.py` (default off). Target scoping stays
|
|
|
|
|
trusted-repos-only — see `sweep-targets.txt`.
|
|
|
|
|
|
|
|
|
|
## cross_review.py — mandatory cross-family reviewer
|
|
|
|
|
The GPT-4.1 cross-family reviewer CLI, re-homed here from the archived orchestrator repo as a
|
|
|
|
|
router-less direct OpenAI SDK call. It is **mandatory** for IAM/policy and Lambda-handler-signature
|
|
|
|
|
changes (per the global instructions), and is the reasoning backend for the `sh-plan-review`,
|
|
|
|
|
`sh-security-audit`, and `sh-build-review` gates.
|
|
|
|
|
|
2026-06-29 11:41:41 -04:00
|
|
|
```
|
2026-07-14 19:24:01 -04:00
|
|
|
python3 ~/Documents/repositories/seahaven/security-review/cross_review.py "<task>"
|
2026-06-29 11:41:41 -04:00
|
|
|
```
|
2026-07-14 19:24:01 -04:00
|
|
|
|
|
|
|
|
Setup: `OPENAI_API_KEY` in the environment or in the repo-root `.env` (gitignored — never commit
|
|
|
|
|
it); `pip install -r requirements.txt` provides the `openai` SDK.
|
