# security-review

The Sea Haven security-review gate. One pure-code script (`review.sh`), many triggers.
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` + `install-hooks.sh` — fast scanners-only hook for a target repo.
- The agentic detector/verifier pass is the interactive `/sh-security-review` slash command
  (`~/.claude/commands/sh-security-review.md`), schema at `~/.claude/security-review/finding.schema.json`.

## 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.
- **Pre-commit:** `install-hooks.sh <repo>` — fast deterministic scanners abort the commit early.
- **CI (Phase 3):** the same `review.sh` runs headless as the unbypassable backstop.

## Scanners
`review.sh` runs whatever is installed and logs the rest with install commands (no silent skips).
Currently wired: `cfn-lint`. To give the deterministic layer teeth, install:
```
pipx install semgrep        # SAST: injection / authz / xss
brew install gitleaks       # hardcoded secrets
pipx install pip-audit      # vulnerable Python deps
pipx install checkov        # IaC / IAM misconfig
```
Each needs a small normalizer added to `review.sh` (map its JSON to the finding schema) when installed.

## Status
review.sh gate validated against the local testbed: 16 findings, correct dedup of distinct
same-CWE findings, suppression-without-justification rejected and surfaced, BLOCK on confirmed crit/high.