# security-review

[![CI](https://github.com/Sea-Haven-Industries/security-review/actions/workflows/ci.yaml/badge.svg)](https://github.com/Sea-Haven-Industries/security-review/actions/workflows/ci.yaml)
[![Dependency Review](https://github.com/Sea-Haven-Industries/security-review/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/Sea-Haven-Industries/security-review/actions/workflows/dependency-review.yml)
![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)

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 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).

## 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.
- **Scheduled:** the Claude Code web cloud routines are the unattended backstop (see below).

### 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`.

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`.

- `--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`.

**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):
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:** `<repo>/.security-review/suppressions.json` (tracked; travels with the repo).

Both files' `.suppressions[]` are concatenated (machine-level first, so it wins any id collision).
This means every entry point — the pre-push hook, the scheduled sweeps, on-demand/CI runs, and the
Open SWE daily-report automation — resolves suppressions identically. **Portability note:** hosts that
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
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).

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
```

## 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.

```
python3 ~/Documents/repositories/seahaven/security-review/cross_review.py "<task>"
```

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.