# Security Review

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

- **Type:** Skill
- **Install:** `agentstack add skill-bestdeejay-design-agent-skills-security-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bestdeejay-design](https://agentstack.voostack.com/s/bestdeejay-design)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** https://github.com/bestdeejay-design/agent-skills/tree/main/skills/security-review
- **Website:** https://bestdeejay-design.github.io/agent-skills/

## Install

```sh
agentstack add skill-bestdeejay-design-agent-skills-security-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** [bestdeejay-design/agent-skills](https://github.com/bestdeejay-design/agent-skills)
- **License:** MIT
- **Homepage:** https://bestdeejay-design.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bestdeejay-design-agent-skills-security-review
- Seller: https://agentstack.voostack.com/s/bestdeejay-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.