security-scan

---
name: security-scan
description: Use when a user asks to scan a repository for dependency vulnerabilities, license compliance, insecure code patterns, CVEs, or OWASP Top 10 risks.
license: MIT
metadata:
  author: Ray Tien
  version: "1.4.0"
---

# Security Scan

Produce an evidence-backed security assessment without changing application code or dependencies.

## Boundaries

- Treat scanning as read-only. Do not install tools, update advisory databases, build images,
  run project scripts, or modify global client settings without explicit approval. OSV license
  lookup (like the existing OSV vulnerability fallback) queries deps.dev over the network;
  it does not install or execute project dependencies.
- Never report a clean scan when a tool failed, was missing, or could not cover the target.
- Never copy secret values into chat or reports. Follow
  [the reporting and redaction contract](references/REPORTING.md).
- Scan every detected project in a monorepo, not only the repository root.

## Interpret the Request

Default to dependency, license-compliance, and code scanning. Apply these modes before running
tools:

- `--deps-only`: include license records; skip Semgrep.
- `--code-only`: skip dependency and license scanners.
- `--owasp A01` through `A10`: retain only findings mapped to that 2025 category.
- `--severity critical,high`: filter after normalizing scanner output.
- `--export-bypass`: read the reporting reference and export reviewed false positives only.
- `--auto-remind`: explain that reminders are client-specific. Do not claim they are enabled or
  write client configuration until the user chooses a supported hook or automation.

Reject incompatible `--deps-only` and `--code-only` requests instead of guessing.

## Workflow

1. Record the repository path, Git commit, requested modes, scope, and exclusions.
2. Read [the scanner contract](references/SCANNERS.md). Build the dependency plan, repeating
   `--exclude` for each user-requested relative path:

   ```bash
   python3 <skill-root>/scripts/scan_plan.py <project-root> \
     [--exclude <relative-path>] --pretty
   ```

3. Review schema v2 `fallback`, `note`, and `evidence` fields, including root secrets and CI
   records. Run ready records into a new evidence directory:

   ```bash
   python3 <skill-root>/scripts/run_plan.py plan.json --out scan-evidence [--semgrep]
   ```

   Never chain package managers with `||`; a non-zero exit may mean findings, not tool failure.
4. Normalize the evidence before interpreting results:

   ```bash
   python3 <skill-root>/scripts/normalize_findings.py scan-evidence --out security-findings.json
   ```

   For repeat scans, pass `--baseline security-findings.json`. Use `--format sarif` for a GitHub
   code-scanning upload. Keep the original lockfiles available for license provenance filtering.
   Read every normalized scanner state and reason; normalization does not replace the completion
   gate for `failed`, `skipped`, or `inconclusive` coverage.
5. Review every code finding at its flagged lines. Assign a verdict and evidence as defined in
   [the reporting contract](references/REPORTING.md), write `verdicts.json`, then rerun with
   `--verdicts verdicts.json`. If this review is skipped, label those findings unreviewed.
6. Do not run planner records marked `inconclusive`; their command is null because project evidence
   is ambiguous. Preserve the planner's reason and report the affected scope as incomplete. Mark
   `needs-lockfile`, `needs-export`, and missing-tool entries as `inconclusive` or `skipped`. Offer
   installation or preparation instructions, but do not perform them without approval.
7. Unless code scanning was disabled, pass `--semgrep` to the evidence runner. It appends this
   root-level command as a code-scanning evidence record:

   ```bash
   semgrep scan --config p/owasp-top-ten --json --metrics=off .
   ```

   Parse the JSON even when the command exits non-zero. Treat Semgrep as pattern coverage, not
   proof that all OWASP risks were tested.
8. Read [the OWASP 2025 mapping](references/OWASP.md). Do not trust legacy 2017 or 2021 labels
   without translating them. Dependency findings map primarily to A03:2025.
9. Enrich actual CVE identifiers only when useful. Batch up to 100 IDs with the NVD `cveIds`
   parameter, honor rate limits, and preserve the scanner result if enrichment fails. Do not
   invent CVEs for GHSA, RUSTSEC, PYSEC, or other advisory identifiers.
10. Generate the result using [the reporting contract](references/REPORTING.md). Unless the user
   requested files, summarize in chat. Never overwrite an existing report without confirmation.

## Optional Jev Suggestions

Only when the user explicitly requests TypeSafe Jev suggestions and approves transmitting the
normalized finding context, offer this separate command:

```bash
TYPESAFE_API_KEY=... python3 <skill-root>/scripts/suggest_verdicts.py \
  security-findings.json --out jev-suggestions.json
```

It requires the optional `typesafe-sdk` package; do not install it without approval. The command
sends normalized metadata and the existing redacted snippet only, processes unreviewed Semgrep code
findings, and does not read additional source files. Treat `jev-suggestions.json` as triage input,
not `verdicts.json`: Jev's typed choice and confidence do not supply the technical evidence required
by the reporting contract. A person or reviewing agent must verify and write that evidence before a
verdict is merged.

## Completion Gate

Report every scanner as `clean`, `findings`, `failed`, `skipped`, or `inconclusive`. Include tool
versions and uncovered scope. A scan is complete only when all planned scanners have a recorded
state and every displayed snippet has passed redaction.