security-review

Files (1)

• SKILL.md

SKILL.md (first lines)

> Spec 052 introduced this skill as jig's **team baseline** for security
> review, under [ADR-0013](../../docs/decisions/adr-0013-security-floor-policy.md)'s
> "jig provides the floor; bring your own depth" principle. Like
> `/jig:pr-review` (spec 012), `/jig:arch-review` (spec 014), and
> `/jig:contracts` (spec 022), it ships as SKILL.md only — no `.py`
> helper. It is fundamentally a judgment skill; the determinism it needs
> (detect a scanner on `PATH`, run it, read a diff) Claude runs inline.
> If any other skill is installed whose description identifies it as
> handling security review, SAST, or vulnerability analysis, the Claude
> Code skill router prefers that one over jig's baseline — the deferral
> is **category-based, not name-specific**, so a richer skill named
> anything (`security-review`, `adobe-security-reviewer`, `sast-scan`,
> `vuln-audit`, etc.) wins. Jig's slim version remains the auto-trigger
> when no such skill is installed.

## What this skill does

Produces a **breadth-over-depth heuristic security pass** over a diff, a
branch's changes, or a pasted snippet, in a four-bucket markdown envelope:

1. **Summary** — a one-paragraph read of what changed and the overall
   security posture (clean / needs fixes before merge / needs a deeper
   look).
2. **Blockers** — concrete must-fix security issues. Each cites a
   `file:line` and a one-sentence rationale.
3. **Nits** — lower-urgency hardening suggestions. Same shape as blockers.
4. **Strengths** — security-positive choices worth repeating (parameterized
   queries, secrets read from env, input validated at the boundary).

It works in two modes that compose:

- **Orchestrate-if-present.** When a real scanner (`semgrep`, `bandit`,
  `gosec`, `npm audit` / `osv-scanner`) is on `PATH`, it runs the ones
  present and folds their output into the review. It **installs nothing.**
- **Defer-if-richer.** When a richer security/SAST/vuln skill is installed,
  the router prefers it; jig's baseline yields.

When neither a scanner nor a richer skill is present, the heuristic
baseline below is the floor — even a tooling-less user gets a real,
structured pass. This is **not a SAST engine** and **not a guarantee** —
see [Honest framing](#honest-framing).

## When to use vs. when to defer

There are several things people confuse with this skill. Pick the right one:

- **Any other installed security / SAST / vulnerability-analysis skill.**
  The deferral is **category-based, not name-based**: a skill named
  anything whose description claims security review, SAST, or
  vulnerability analysis is preferred. The routes the Claude Code router
  may resolve to include **the user's own** skill (commonly
  `~/.claude/skills/security-review/`), **Adobe's `adobe-security-*`
  family** (depth jig deliberately does not ship), or a **built-in
  `security-review`**. If one is present, **defer to it** — explicitly
  invoke it if you want to be sure. The deferral is a router hint, not a
  filesystem probe (see [Gotchas](#gotchas)).
- **`/jig:pr-review`** — sibling jig skill for **general PR craft review**
  (scope / blockers / nits / strengths across correctness, readability,
  test coverage). This skill is the **security lens** specifically. Reach
  for `/jig:pr-review` for overall code-review craft; reach for this skill
  when the question is "is this *secure*?" The two compose: pr-review for
  craft, security-review for the security pass.
- **`/jig:independent-review`** — sibling jig skill for **spec-compliance
  review** of a finished slice (does the implementation satisfy `spec.md`'s
  acceptance criteria?). That is a spec-shape review against a written
  spec. This skill is a diff-shape security review. Reach for
  `/jig:independent-review` when a slice is in REVIEWED-or-similar state
  with a spec.md to evaluate against.
- **The `jig-secret-scan` PreToolUse hook** (spec 052-02) — the secret
  *prevention* floor. It blocks an obvious secret from being written to
  disk at agent-edit time. **This skill is *review*, not *prevention*.**
  The hook stops a secret going in; this skill reads a change-set after
  the fact and flags security issues (including secrets that slipped past
  the hook, e.g. in a file the agent didn't write). They are different
  primitives at different times — keep both.

Rule of thumb: **"is this secure?" → this skill (or the richer installed
one). "does this match the spec?" → `/jig:independent-review`. "is this
good code?" → `/jig:pr-review`. "stop me committing a secret" → the
`jig-secret-scan` hook.**

## Orchestrate installed scanners (never bundle)

This skill **runs the tools you already have; it installs nothing and
bundles nothing.** Before the heuristic pass, detect what is on `PATH` and
run the ones present, folding their findings into the four-bucket envelope.

**Scanner-present path.** For each scanner detected on `PATH`, run it
scoped to the change-set and merge its output:

| Scanner | Surface | Detect | Typical invocation |
|---|---|---|---|
| `semgrep` | Multi-language SAST | `command -v semgrep` | `semgrep --config auto <paths>` |
| `bandit` | Python SAST | `command -v bandit` | `bandit -r <python paths>` |
| `gosec` | Go SAST | `command -v gosec` | `gosec ./...` |
| `npm audit` | JS/TS dependency CVEs | `command -v npm` + `package-lock.json` | `npm audit --json` |
| `osv-scanner` | Cross-ecosystem dependency CVEs | `command -v osv-scanner` | `osv-scanner --lockfile=<file>` |

Treat scanner output as **input to your judgment**, not the verdict:
de-duplicate against the heuristic findings, drop noise that is clearly
out of the change's scope, and promote genuine high-severity hits to
Blockers with the scanner named in the rationale.

**Scanner-absent path (graceful degradation).** When **none** of these is
on `PATH`, say so once in the Summary ("no security scanner detected on
PATH; this is a heuristic-only pass") and fall back to the
[heuristic baseline categories](#heuristic-baseline-categories) — the
review still ships, just without scanner corroboration. Degrading
gracefully to heuristic-only is the designed floor, not a failure mode:
a tooling-less user still gets a structured security pass.

**Never** `pip install`, `npm install -g`, `go install`, or otherwise
fetch a scanner. If a scanner would help and isn't present, note it as a
Nit ("consider wiring `semgrep` in CI") — do not install it.

## Heuristic baseline categories

With no scanner and no richer skill, this is the floor: a structured pass
over the change-set across eight named categories. For each, the bullets

From ramboz/jig, MIT.

More from ramboz/jig