Security Scan

---
name: security-scan
description: |
  Stack-agnostic security audit: map the attack surface, trace untrusted input to dangerous calls, surface
  dependency and configuration flaws. Severity-ranked report with fixes.
  Use when auth, input handling, secrets or dependencies change, and before a release.
---

# Security Scan

<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
Trigger phrases: "security scan", "run a security scan", "OWASP check", "scan for vulnerabilities", "find security vulnerabilities", "security audit", "api key", "secret key", "leaked credential", "credentials leaked", "hardcoded secret", "hardcoded password", "sql injection", "can an attacker"

The core of a security vulnerability fits in a single sentence: **an untrusted input reaches a
dangerous operation without being adequately checked.** This skill chases exactly that sentence — it first
looks for where the input comes from, then where it flows, and what gate should sit in between.
It is stack-agnostic: whatever the language/framework, the same logic applies; when current tooling and
patterns are needed, it runs a web search.

> **Crewforth adaptation (local, .claude/):** `crew-security-expert` applies this; findings are carried to
> **crew-review-agent** in severity order, whatever the stack. Automatic
> fixes only with explicit approval (§4.4); `.claude` does not go to the repo (§4.3). §4 Prohibitions apply.

## What it does, what it doesn't
- **Does:** surfaces common vulnerability classes, known vulnerable dependencies, and risky configuration; ties each finding to a concrete fix.
- **Doesn't:** does not replace a professional pentest / SAST / DAST. The report **guides**, it does not give full assurance — state this at the end of the report.
- **Boundary:** analysis is local; code/data is not sent to an external service, and the project directory is not left.

## A question is not a scan
Loading this skill does not mean running all of it. "Is this query injectable?", "should this key be in the
repo?", "how do I hash these passwords?" are **questions**: answer them from the relevant part of this skill and
stop — no discovery pass, no fan-out of verifiers, no coverage ledger, no report file. The full workflow below runs
when the user asks for a scan, an audit or a security review of a codebase or a change, or asks for the report
itself. When a request could be either, ask one question before starting the full workflow; do not guess upward.

## Mental model — source → gate → sink
Reduce every check to three questions:
1. **Source** — where does the input enter? (route, API endpoint, form, CLI argument, file upload, WebSocket, queue message, external API response)
2. **Sink** — which dangerous operation does this input reach? (SQL execution, shell, file path, HTML render, deserialization, template)
3. **Gate** — is there validation / parameterization / escaping / authorization in between? If not, that's the finding.

The scan applies this model on four fronts: **dependency · code · configuration · authorization**. The result is ranked by severity, and the fix is presented for the user to choose.

## Scope
Prefer **`docs/THREAT_MODEL.md`** if present (from the `threat-model` skill): its entry points and attack classes
are the focus areas, and its impact/likelihood bias which findings count as high severity — the biggest lever on
false positives. No threat model → map the surface yourself first (Front 0 · Discovery).

## Checklist
- [ ] Stack and package ecosystem(s) detected, attack surface mapped
- [ ] Dependency audit run for each ecosystem
- [ ] Source→sink paths traced across the four vulnerability classes
- [ ] Configuration and secret leakage scanned
- [ ] Authorization matrix produced, unprotected sensitive endpoints searched for
- [ ] Code builds on a model (prompts, retrieval, memory, tools, sub-agents, MCP) → Front 5 run (`references/ai-agents.md`)
- [ ] Each candidate adversarially **verified** (N-verifier disprove pass); FALSE_POSITIVE / CANNOT_VERIFY separated out
- [ ] Severity **derived from preconditions × access** (not the scanner's category); verification ≠ severity
- [ ] Findings reported in severity order, no secret disclosed; ruled-out findings recorded too
- [ ] Fix options presented to the user

---

## Fronts

Five review fronts — Discovery · Dependencies · Code (source→sink) · Configuration · Authorization: **`references/fronts.md`** (read the fronts you're scanning). A sixth, for code built on a model — prompts, retrieval, memory, tools, sub-agents, MCP — lives in **`references/ai-agents.md`**: read it only when that code is present.

When you fan out a sub-agent per front, how you prompt it decides recall — describe vulnerability **shapes** not a
checklist, scope each agent, and state that vulnerabilities exist: **`references/prompting.md`**.

---

## Verify before you report

Discovery is deliberately noisy (recall-biased); a **separate adversarial pass** disproves each candidate before it
reaches the report — the biggest lever on false positives. Run **N independent verifiers** per finding (each starts
from the code, not the summary; each hunts for why it's *wrong*), classify **TRUE_POSITIVE / FALSE_POSITIVE /
CANNOT_VERIFY**, then derive **severity from preconditions × access** (independently — "real" is not "critical").
The verifier procedure, the false-positive exclusion rules, the parseable verdict block, and the severity matrix
live in **`references/verify.md`**. Ruled-out findings are recorded, not silently dropped.

## Report

The severity scale, finding format, summary line, and the fix-presentation format live in **`references/reporting.md`**.

## Invariant rules
1. **Guides, does not assure** — it does not replace a professional audit; say so in the report.
2. **State coverage, not just findings** — every report ends with a `complete / partial / unknown` ledger over the
   threat model's surfaces, each non-complete row carrying its reason. Without it, "no findings" and "never
   looked" read identically to whoever acts on the report (`references/reporting.md`).
3. **Mask secrets** — only the first 4 + last 4 characters (`sk-p…i789`); never write the full secret.
4. **No automatic fix without approval** — even if "Fix everything" is chosen, first show what will change.
5. **Do not install tools without asking.**
6. **Preserve behavior** — a fix must not change functionality beyond closing the vulnerability.
7. **Stay local** — do not send code/data to an external service, do not cross the project boundary.
8. **Do not run the code under review to prove a finding** — no build, test, install or fixture run of it unless it
   is isolated: no network, an empty environment, writes confined to a scratch directory, and hard limits on time
   and resources. An install runs the target's own scripts; a test run executes whatever the target chose. If that
   isolation is not available, the finding stays **CANNOT_VERIFY** with the exact local check that would settle
   it. Reading source never needs any of this; executing it always does.