Security Review

---
name: security-review
description: "Security review orchestrator for dependency lockfiles and source: inventory of lockfiles/manifests (npm, pip, cargo, go, gem, maven, gradle, composer), exit-code classifier for 13 security tools (semgrep, bandit, gitleaks, osv-scanner, pip-audit, trufflehog, checkov, trivy, grype, npm audit, cargo audit), JSON normalizer to a unified finding schema, and human-readable reports. Stdlib-only Python helper + workflow for OWASP-aligned security review."
license: MIT
metadata:
  author: best
  version: "1.0.0"
  compatibility: "Requires Python 3 stdlib only. External scanners (semgrep, osv-scanner, ...) optional and used via their own CLIs."
when_to_use: "Use when running a security review of a codebase: 'security review', 'dependency audit', 'scan lockfiles', 'normalize scanner reports', 'vulnerability review'. Example: \"review my repo's dependencies for vulns\" or 'run a security review and normalize the reports'."
---

# Security Review — dependency & static analysis orchestration

Load this skill when you need to run a **security review of a codebase**:
audit the dependency manifest/lockfile inventory, decide which scanner to run
per ecosystem, interpret scanner exit codes correctly (real findings vs.
infrastructure errors), and normalize reports from different tools into **one
unified schema** for a final report.

The helper script is **offline by design** — it inventories, classifies, and
normalizes. Actual scans are executed by the well-known external tools listed
below (install once locally or in CI).

---

## The helper script

`scripts/security_review.py` — pure Python 3 stdlib (no dependencies).

| Command | Purpose |
|---|---|
| `security_review.py inventory --dir . ` | List dependency locks with ecosystem + suggested tool |
| `security_review.py inventory --dir . --json` | Same, machine-readable |
| `security_review.py classify --tool semgrep --exit-code 1` | Explain what a tool exit code means |
| `security_review.py normalize --tool osv-scanner --input out.json` | Flatten a tool JSON report into unified findings |
| `security_review.py normalize --tool pip-audit --input pip.json --output report.json` | Save unified report |
| `security_review.py report --root .` | Report skeleton (markdown default, `--json` for JSON) |

### Lockfile inventory (per-ecosystem suggested tool)

| Lockfile / manifest | Ecosystem | Suggested tool |
|---|---|---|
| `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` | npm / pnpm / yarn | `npm audit` / `osv-scanner` |
| `requirements*.txt`, `pyproject.toml`, `Pipfile.lock`, `poetry.lock` | pip | `pip-audit` |
| `Cargo.lock` | cargo | `cargo audit` |
| `go.mod`, `go.sum` | go | `osv-scanner` |
| `Gemfile.lock` | gem | `osv-scanner` |
| `pom.xml`, `build.gradle(.kts)` | maven / gradle | `osv-scanner` / `dependency-check` |
| `composer.lock` | composer | `osv-scanner` |

`package.json` alone (no lockfile) is still reported, so gate or scan it with `npm audit`.

---

## Exit-code semantics (verified August 2026)

Get each tool's meaning on the fly with `classify --tool X --exit-code N`.

| Tool | `0` | findings | error / other |
|---|---|---|---|
| semgrep | clean | `1` (findings) | `2` fatal; `3/4/5/7/8/13/99` specific errors |
| bandit | clean | `1` (issues) | `2` error |
| gitleaks | clean | `1` (leaks or error) | `126` unknown flag |
| pip-audit | clean | `1` (vulns) | — |
| osv-scanner v2 | clean | `1` (vulns) | `127` error, `128` no packages, `129` API failed, `130` config |
| npm audit | clean | `1` (vulns) | — |
| cargo audit | clean | non-zero (vulns / errors) | — |
| grype | clean | `2` (vulns ≥ fail-on) | `1` error, `100` DB update |
| truffle | clean | `183` (findings, only with `--fail`) | `1` error |
| checkov | clean | `1` (failed checks) | `2` error |
| trivy | clean | `1` (vulns, with `--exit-code`) | — |
| dependency-check | clean | `1` (vulns ≥ threshold) | — |

**Rule of thumb:** `exit 0` == "no findings" only for tools listed as clean=0; other codes are infra errors and must not be treated as "vulnerable".

---

## Workflow

1. **Inventory** — `security_review.py inventory --dir <project> --json` → know exactly which lockfiles exist and which tool applies.
2. **Scan** — run the suggested tool per row above with its JSON format (see `references/canonical-patterns.md` for exact CLI + JSON shapes; e.g. semgrep JSON with `--json`, osv-scanner `--json`, pip-audit `--format json`, gitleaks `--report-format json`, bandit `-f json`).
3. **Classify exits** — in CI, map exit codes via `classify` so `1 = findings`, `2+ = infra error`.
4. **Normalize** — `normalize --tool <t> --input <scanner.json>` → unified findings (ruleId/rule/level/message/path/line/col).
5. **Report** — merge all normalized findings into one report (markdown or JSON), present severity rollup.

## When NOT to use

- **Not a scanner itself** — it does not detect vulnerabilities; it orchestrates/normalizes the real scanners. Run the real tools.
- **Not a secret detector** — use the `secret-scanner` skill for credentials/tokens.
- **Not a web scanner** — OWASP Top-10 dynamic testing is out of scope.

## Success criteria

- `inventory` lists every lockfile in the target directory with correct ecosystem + suggested tool.
- `classify --exit-code` matches the verified table above for your installed tools.
- `normalize` produces a valid unified report for the 5 built-in formats (osv-scanner, pip-audit, semgrep, gitleaks, bandit).
- CI gate: exit `1` on real findings, `EXIT_NEUTRAL` (or `2`) on infra errors, clean on 0.