@ericrisco/rsc 0.1.5

package/skills/security-scan/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: security-scan
+description: "Use when running automated security scanners over a repo or app and turning the raw output into a triaged, ranked, gate-able report: scan for vulnerabilities before shipping, audit dependencies/lockfiles for known CVEs, find secrets committed to the tree or git history, run SAST, or wire scanners into CI. Triggers: 'scan this repo for vulnerabilities', 'check my package-lock for CVEs', 'did anyone commit AWS keys', 'scan git history for leaked keys', 'my lockfile has a transitive CVE', 'is aquasecurity/trivy-action@latest safe', 'set up Semgrep/gitleaks to fail CI', 'escanea el repo en busca de vulnerabilidades', 'audita las dependencias', 'analitza les dependències'. NOT threat-modeling, OWASP design reasoning, or authoring the fix (that is secure-coding)."
+tags: [security, sast, sca, secrets, scanning, owasp]
+recommends: [secure-coding, github-actions, verify]
+origin: risco
+---
+
+# Security scan — orchestrate scanners, triage the noise, emit a gate
+
+A **machine-first** vulnerability sweep. Point automated scanners at a codebase,
+collect SARIF/JSON, then do the work that has actual value: dedupe cross-tool
+overlap, rank by exploitability, and emit one gate artifact CI can act on. The
+finding comes from a **tool run**, not a hunch — if you are reasoning about a
+design or hand-writing a fix, that is [`secure-coding`](../secure-coding/SKILL.md),
+not this skill.
+
+Your job is orchestration + triage. Not eyeballing code, not authoring patches.
+
+## Operating posture
+
+- **Read-only by default.** Scan, triage, report. Apply fixes (version bumps,
+  rotation, `.gitignore` edits) only when the user asks. *Why:* a security sweep
+  that silently mutates the tree destroys the evidence and the trust.
+- **Machine-first.** Every finding must trace to a scanner run with a `ruleId`
+  and a source location. *Why:* "I think this looks injectable" is design
+  reasoning — route it to `secure-coding`. This skill ships reproducible output.
+- **Pin and verify your scanners.** Pin exact versions, verify checksums/SHAs,
+  never pull `@latest` GitHub Actions. *Why:* in **March 2026 Trivy was
+  supply-chain compromised** — malicious releases `v0.69.4/0.69.5/0.69.6` and a
+  hijacked `aquasecurity/trivy-action` exfiltrated CI secrets. Your scanner runs
+  with repo + CI-secret access; an unpinned scanner is itself the attack surface.
+- **SARIF everything.** Make every tool emit SARIF (or JSON you normalize to it).
+  *Why:* a common schema is what lets you merge four tools, dedupe, and feed one
+  artifact into CI instead of four incompatible logs.
+- **Triage before you report.** Raw scanner output is high-noise. Rank by
+  exploitability and dedupe overlap; never dump 400 raw findings on the user.
+
+## The four scan classes
+
+| Class | What it catches | Primary tool | Backup / fast pass |
+|---|---|---|---|
+| **SAST** | injection, XSS, path traversal in *first-party* code | Semgrep | — |
+| **SCA / deps** | known CVEs in dependency manifests + lockfiles | osv-scanner | `npm audit`, `pip-audit` |
+| **Secrets** | credentials in the tree **or git history** | gitleaks (speed) | TruffleHog (depth + live verification) |
+| **Misconfig / IaC** | Dockerfile, k8s, Terraform, exposed config | Trivy `config` | Semgrep rulesets |
+
+### Tool selection by ecosystem
+
+Pick by what is in the repo. This is the real branch point — match the tool to
+the manifest, do not run everything everywhere.
+
+| Repo contains | SAST | SCA | Secrets | Misconfig |
+|---|---|---|---|---|
+| Node (`package-lock.json`/`pnpm-lock.yaml`) | Semgrep | osv-scanner + `npm audit` (fast) | gitleaks → TruffleHog | Trivy |
+| Python (`poetry.lock`/`requirements.txt`) | Semgrep | osv-scanner + `pip-audit` (fast) | gitleaks → TruffleHog | Trivy |
+| Go (`go.mod`/`go.sum`) | Semgrep | osv-scanner (+ `govulncheck` for reachability) | gitleaks | Trivy |
+| Containers (`Dockerfile`, images) | — | Trivy `fs`/`image` | Trivy `--scanners secret` | Trivy `config` |
+| IaC (Terraform/k8s/Helm) | Semgrep (IaC rules) | — | gitleaks | Trivy `config` |
+| Monorepo (mixed) | Semgrep `auto` | osv-scanner (multi-ecosystem) | gitleaks → TruffleHog | Trivy |
+
+Full install (pinned), flag matrix, and suppression syntax: `references/tools.md`.
+
+## Run recipes
+
+All recipes emit SARIF or JSON so they merge into one report. **Pin the version
+shown** — the placeholders below mark where to lock an exact tag/digest.
+
+### SAST — Semgrep
+
+Free OSS edition (latest `1.164.0`, 2026-05-27): 30+ languages, ~2,000 community
+rules. SCA + Secrets rulesets are gated behind the hosted platform — use the
+dedicated tools below for those, not Semgrep.
+
+```bash
+# Pin via the CLI version, not @latest. OWASP ruleset, SARIF out.
+semgrep scan --config p/owasp-top-ten --sarif --output sast.sarif .
+# Broader local sweep (community rules), no telemetry:
+semgrep scan --config auto --sarif --output sast.sarif --metrics off .
+```
+
+### SCA — osv-scanner (primary), native auditors (fast pass)
+
+osv-scanner (OpenSSF/Google) checks lockfiles against OSV.dev across ecosystems
+and catches **transitive** CVEs the native auditors miss. Run native first for
+speed, osv-scanner for coverage — never native alone.
+
+```bash
+# Primary: lockfile-aware, multi-ecosystem, SARIF.
+osv-scanner scan source --format sarif --output sca.sarif .
+# Fast first pass (ecosystem-native, weaker on transitive):
+npm audit --omit=dev --audit-level=high --json > npm-audit.json   # Node
+pip-audit --format json --output pip-audit.json                   # Python
+```
+
+### Secrets — gitleaks (tree + history), TruffleHog (verified)
+
+gitleaks (~150+ patterns, sub-second on diffs) is the pre-commit/CI workhorse.
+TruffleHog (800+ types) adds **live credential verification** — it auth-tests a
+hit to tell a real leaked key from a sample. Scan **history, not just the tree**:
+a key deleted in HEAD is still in the pack files and still rotatable.
+
+```bash
+# gitleaks: redacted SARIF over the working tree AND full git history.
+gitleaks detect --redact --report-format sarif --report-path secrets.sarif
+# TruffleHog: only verified (live) secrets across history.
+trufflehog git file://. --only-verified --json > trufflehog.json
+```
+
+### Misconfig / IaC — Trivy (PINNED — see the caveat)
+
+Trivy scans filesystems, images, and IaC and finds transitive CVEs `npm audit`
+misses. After the March 2026 compromise, **never** run an unpinned Trivy.
+
+```bash
+# Pin the EXACT version (NOT v0.69.4/.5/.6 — those were the malicious releases).
+# Verify the checksum/cosign signature before first use. See references/tools.md.
+trivy fs --scanners vuln,secret,misconfig --format sarif --output trivy.sarif .
+```
+
+## Triage — turn noise into a ranked report
+
+The deliverable is not the four SARIF files. It is a deduped, ranked report.
+
+1. **Merge + dedupe.** Cross-tool overlap is real (osv-scanner and Trivy both
+   flag the same CVE; gitleaks and TruffleHog both flag the same key). Key on
+   `(class, normalized-id, path, line)` and keep the richest record — prefer the
+   one with verification (TruffleHog) or reachability (govulncheck).
+2. **Normalize severity.** SARIF `level` and tool-native severities disagree;
+   map them all to one `critical/high/medium/low` scale (`references/triage.md`).
+3. **Rank by exploitability, not by count.** A finding scores higher when it is
+   **reachable** (called, not just present) **+ exposed** (on an untrusted path)
+   **+ a sensitive sink** (auth, money, PII, RCE). A verified live secret or a
+   reachable RCE CVE outranks a theoretical lib finding behind a feature flag.
+4. **Suppress with a written justification, never a blanket ignore.** Each
+   suppression records *who, why, and an expiry* — not a silent `.semgrepignore`
+   that hides the next real bug too.
+
+```text
+BAD  — dump 412 raw findings from four tools, sorted alphabetically, no ranking.
+GOOD — 3 unsuppressed criticals first:
+       1. [secrets] VERIFIED live Stripe sk_live_… in config/.env (history) → ROTATE NOW
+       2. [sca] CVE-2024-… lodash 4.17.20 transitive, reachable in src/api/parse.ts → bump 4.17.21
+       3. [sast] SQL built from req.query in routes/search.js:48 → parameterize
+       + 7 mediums summarized, + 18 suppressed (each with justification + expiry).
+```
+
+Full ranking rubric, dedupe keying, and severity-normalization map:
+`references/triage.md`.
+
+## The gate artifact
+
+Emit one `security-scan-report.json` — the machine-checkable contract CI gates on.
+
+```json
+{
+  "schemaVersion": "1.0",
+  "scannedAt": "2026-06-02T10:00:00Z",
+  "target": ".",
+  "tools": [{ "name": "osv-scanner", "version": "2.0.2" }],
+  "summary": { "critical": 1, "high": 2, "medium": 7, "low": 14, "suppressed": 18 },
+  "findings": [
+    {
+      "class": "sca",
+      "ruleId": "CVE-2024-XXXXX",
+      "path": "package-lock.json",
+      "line": 0,
+      "severity": "critical",
+      "status": "open",
+      "tool": "osv-scanner",
+      "exploitability": "reachable",
+      "title": "Prototype pollution in lodash <4.17.21"
+    }
+  ]
+}
+```
+
+- `status` is one of `open | suppressed | fixed`; `severity` one of
+  `critical | high | medium | low`. Schema in full: `references/triage.md`.
+- **Gate rule:** any `open` finding at `critical` (and, on a strict gate, `high`)
+  → fail. `suppressed` never fails. `scripts/verify.sh` enforces exactly this and
+  exits `0` on a clean/empty report (no false failure).
+
+## CI wiring (brief)
+
+- Pin actions to a **full commit SHA**, not a tag, never `@latest` — the hijacked
+  `aquasecurity/trivy-action` was pulled by tag.
+
+```yaml
+# .github/workflows/security-scan.yml — pin the SHA, verify before bumping.
+- uses: aquasecurity/trivy-action@<full-40-char-sha>  # NEVER @latest / @master
+  with: { scan-type: fs, format: sarif, output: trivy.sarif }
+- run: ./scripts/verify.sh   # gate on security-scan-report.json
+```
+
+- Upload SARIF to code scanning; gate the merge on `verify.sh`, not on a human
+  reading logs. See [`github-actions`](../github-actions/SKILL.md) for the
+  pipeline shell and [`verify`](../verify/SKILL.md) for the broader green gate
+  this feeds.
+
+## Anti-patterns
+
+| Rationalization | Reality |
+|---|---|
+| "Pull `aquasecurity/trivy-action@latest`, it's official." | March 2026: a hijacked tag stole CI secrets. Pin a full SHA, verify provenance. |
+| "Every scanner finding is a bug to fix." | Most are noise. Rank by reachable + exposed + sensitive sink; report the few that matter. |
+| "Scanned the working tree, no secrets." | History holds the deleted keys. Scan git history; a removed-in-HEAD key is still leaked and live. |
+| "`npm audit` is clean, deps are fine." | Native auditors miss transitive CVEs. Run osv-scanner/Trivy too; native is the fast pass, not the only pass. |
+| "Commit a blanket `.semgrepignore` to quiet CI." | A blanket ignore hides the next real bug. Suppress per-finding with a written justification + expiry. |
+| "We found a verified key, I deleted it from the file." | Deleting ≠ safe. Rotate the credential first, then scrub history. The committed value is already compromised. |
+| "Trust the SARIF `level`, that's the severity." | Tools disagree. Normalize to one scale before you rank or gate. |
+| "Dump all four tool outputs in the PR, let the reviewer sort it." | The reviewer won't. Merge, dedupe, rank, and emit one report. |
+| "Run the scan; it'll auto-fix the deps." | Read-only by default. Propose bumps; apply only when asked — never mutate during a sweep. |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
+Karpathy wiki), record the scanner choices, pinned versions, gate thresholds, and
+any accepted-risk suppressions in `02-DOCS/wiki/stack/security-scan.md`, and link
+it from the root `CLAUDE.md` `## Knowledge map`. Read it first on every run so the
+next agent inherits the pinned tools and thresholds instead of re-deriving them.
+No `02-DOCS/`? Skip silently. Conventions are recorded, not gated — never block
+the scan on this.
+
+## See Also
+
+- [`secure-coding`](../secure-coding/SKILL.md) — the human-reasoning sibling:
+  threat-model a feature, hand-write the vulnerable→fixed diff. *If the answer
+  comes from a tool run it's this skill; if it comes from reasoning about the
+  design it's secure-coding.*
+- [`review`](../review/SKILL.md) — adversarial review of a diff against a spec.
+- [`code-review`](../code-review/SKILL.md) — general correctness/quality review.
+- [`verify`](../verify/SKILL.md) — the broader lint/type/test green gate this
+  feeds into.
+- **References** — `references/tools.md` (pinned installs, flag matrix,
+  suppression syntax); `references/triage.md` (ranking rubric, dedupe keying,
+  severity map, full report schema).
+</content>
+</invoke>

package/skills/security-scan/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — security-scan
+
+`cases.yaml` holds two kinds of checks, run by the skill eval harness — no live
+scanners are invoked. `should_trigger` / `should_not_trigger` are routing cases:
+each prompt asserts whether this skill should fire, and every negative names the
+real sibling it belongs to (`secure-coding`, `code-review`, `review`, `verify`).
+The `capability` case is a rubric: given the monorepo scenario, the agent's plan
+is graded against the `must_include` list (correct tool per ecosystem, history
+secret scan, SARIF merge + dedupe, exploitability ranking, the
+`security-scan-report.json` artifact, scanner pinning, rotate-then-scrub, and
+read-only default). Score the routing cases as pass/fail on the trigger decision
+and the capability case by how many rubric items the plan covers. The
+`scripts/verify.sh` gate is exercised separately by pointing it at a sample
+`security-scan-report.json`.

package/skills/security-scan/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: security-scan
+
+should_trigger:
+  - prompt: "Scan this repo for vulnerabilities before we ship."
+    why: Core multi-class sweep (SAST + SCA + secrets) — the central use case.
+  - prompt: "Check my package-lock.json for known CVEs."
+    why: SCA over a lockfile; osv-scanner primary with npm audit as the fast pass.
+  - prompt: "Did anyone commit AWS keys? Scan the git history."
+    why: Non-obvious — secrets in history, not just the working tree; a deleted key is still leaked.
+  - prompt: "escanea el repo en busca de vulnerabilidades y secretos"
+    why: Spanish trigger for the full vuln + secrets sweep.
+  - prompt: "Set up Semgrep and gitleaks to fail CI on critical findings."
+    why: CI gate artifact — emit security-scan-report.json and wire verify.sh into the pipeline.
+  - prompt: "Is it safe to use aquasecurity/trivy-action@latest in my pipeline?"
+    why: Non-obvious — the scanner is itself a supply-chain risk (March 2026 Trivy compromise); pin SHA, verify provenance.
+  - prompt: "analitza les dependències del projecte per CVEs"
+    why: Catalan trigger for dependency CVE auditing.
+
+should_not_trigger:
+  - prompt: "Threat-model this new payments endpoint."
+    route_to: secure-coding
+    why: Design reasoning (STRIDE on a feature), no tool run — the answer comes from a human reasoning about the design.
+  - prompt: "Write the fix for this SQL injection."
+    route_to: secure-coding
+    why: Authoring a vulnerable→fixed diff; this skill reports findings, it does not write fixes.
+  - prompt: "Review my PR diff for correctness and quality."
+    route_to: code-review
+    why: General correctness/quality review of a diff, not a scanner-driven vuln sweep.
+  - prompt: "Be my adversarial reviewer for this change against the spec."
+    route_to: review
+    why: SDD adversarial review gate against a spec, not automated scanning.
+  - prompt: "Run lint and tests and tell me if the green gate passes."
+    route_to: verify
+    why: The lint/type/test verify phase; security-scan can feed it but is not it.
+
+capability:
+  - scenario: >
+      A Node + Python monorepo with a committed .env, a transitive lodash CVE
+      reachable from src/api, and a hardcoded Stripe sk_live key in config. Run a
+      security scan and produce the gate artifact.
+    must_include:
+      - Selects the correct tool per ecosystem (Semgrep SAST; osv-scanner SCA with npm audit / pip-audit as fast pass; gitleaks + TruffleHog secrets; Trivy misconfig)
+      - Scans git history for secrets, not just the working tree
+      - Emits SARIF/JSON per tool and merges into one report
+      - Dedupes cross-tool overlap (same CVE / same secret flagged twice)
+      - Ranks by exploitability (reachable + exposed + sensitive sink), criticals first
+      - Produces security-scan-report.json conforming to the documented schema
+      - Pins scanner versions and flags the Trivy supply-chain caveat (no @latest action)
+      - Recommends rotating the verified Stripe key first, then scrubbing history
+      - Does NOT auto-fix or mutate the tree without asking (read-only by default)

package/skills/security-scan/references/tools.md

@@ -0,0 +1,98 @@
+# Tools — pinned installs, flags, suppression syntax
+
+Facts accessed 2026-06-02. Pin the exact versions shown; treat the scanner as a
+supply-chain dependency, not a throwaway CLI.
+
+## Semgrep (SAST)
+
+- Latest OSS `1.164.0` (2026-05-27). Community/OSS edition: 30+ languages, ~2,000
+  community rules. **SCA + Secrets rulesets are gated behind the hosted AppSec
+  platform** (login required) — do not rely on Semgrep for those; use osv-scanner
+  and gitleaks/TruffleHog instead.
+
+```bash
+pip install semgrep==1.164.0        # or pipx install semgrep==1.164.0
+semgrep scan --config p/owasp-top-ten --sarif --output sast.sarif --metrics off .
+semgrep scan --config auto          --sarif --output sast.sarif --metrics off .
+```
+
+- Severity: gate on `ERROR`; treat `WARNING`/`INFO` as informational.
+- Suppression: inline `// nosemgrep: rule-id` on the line, or a `.semgrepignore`
+  for **paths** (`vendor/`, `test/fixtures/`) — never a blanket rule mute.
+
+## osv-scanner (SCA — primary)
+
+- OpenSSF/Google. Checks lockfiles against OSV.dev across ecosystems; ships
+  guided remediation. v2 CLI: `osv-scanner scan source`.
+
+```bash
+# Install a pinned release binary from github.com/google/osv-scanner/releases.
+osv-scanner scan source --format sarif --output sca.sarif .
+osv-scanner scan source -L package-lock.json --format sarif --output sca.sarif
+```
+
+- Suppression: `osv-scanner.toml` with an `[[IgnoredVulns]]` block per CVE,
+  including `reason` and `ignoreUntil` (expiry).
+
+## Native auditors (SCA — fast pass)
+
+Weaker on transitive CVEs; a first pass, never the only pass.
+
+```bash
+npm audit --omit=dev --audit-level=high --json > npm-audit.json     # Node
+pip-audit --format json --output pip-audit.json                     # Python (PyPA + Trail of Bits; OSV + PyPI feed)
+govulncheck ./...                                                   # Go — reachability-aware
+```
+
+## gitleaks (Secrets — speed)
+
+- ~150+ default regex patterns, sub-second on diffs. Ideal pre-commit + CI diff.
+
+```bash
+# Pin a release from github.com/gitleaks/gitleaks/releases.
+gitleaks detect --redact --report-format sarif --report-path secrets.sarif   # tree + full history
+gitleaks protect --staged --redact                                           # pre-commit (diff only)
+```
+
+- Suppression: `.gitleaks.toml` `[allowlist]` (regexes/paths/commits) or an inline
+  `# gitleaks:allow` comment on the offending line.
+
+## TruffleHog (Secrets — depth + verification)
+
+- 800+ secret types. **Credential verification:** live-tests a detected secret via
+  auth, so a hit is a *confirmed* live leak, not a guess. Scans git history, S3,
+  Docker, etc.
+
+```bash
+trufflehog git file://. --only-verified --json > trufflehog.json
+```
+
+- Pattern most teams use: **gitleaks pre-commit** (speed) + **TruffleHog in CI**
+  (depth + verification).
+
+## Trivy (Misconfig / IaC / containers) — PINNED, VERIFIED
+
+- Aqua Security, scans containers/filesystems/IaC/language deps, generates SBOM,
+  catches transitive CVEs `npm audit` misses.
+- **Supply-chain caveat (March 2026):** malicious releases `v0.69.4`, `v0.69.5`,
+  `v0.69.6` and a hijacked `aquasecurity/trivy-action` GitHub Action stole CI
+  secrets. **Pin an exact known-good version, verify the cosign signature /
+  checksum before first use, and pin the Action to a full commit SHA — never a
+  tag, never `@latest`.**
+
+```bash
+# Install a pinned, signature-verified release (NOT 0.69.4/.5/.6).
+trivy fs --scanners vuln,secret,misconfig --format sarif --output trivy.sarif .
+trivy config --format sarif --output trivy-iac.sarif ./infra
+trivy image --format sarif --output trivy-img.sarif <pinned-image@sha256:...>
+```
+
+- Suppression: `.trivyignore` (one CVE/check id per line) or inline
+  `#trivy:ignore:<id>` in IaC files. Record a reason in review, not just the id.
+
+## SARIF notes
+
+- Every recipe emits SARIF 2.1.0 so findings merge into one report. Where a tool
+  only emits native JSON (`npm audit`, `pip-audit`, TruffleHog), normalize it to
+  the report schema in `triage.md` rather than gating on its raw shape.
+</content>

package/skills/security-scan/references/triage.md

@@ -0,0 +1,93 @@
+# Triage — ranking, dedupe, severity, report schema
+
+The value of this skill lives here: scanner output is high-noise, and the job is
+turning four overlapping logs into one ranked, gate-able report.
+
+## Exploitability ranking rubric
+
+Score each finding on three axes, then sort. Count of findings is irrelevant —
+one reachable RCE outranks fifty theoretical lib advisories.
+
+| Axis | High | Low |
+|---|---|---|
+| **Reachable** | the vulnerable code/dep is actually called (govulncheck-confirmed, in the import graph) | present but unused / behind a disabled flag |
+| **Exposed** | on an untrusted path (HTTP handler, CLI arg, file upload, deserialization) | internal-only, dev-only, test fixture |
+| **Sink sensitivity** | auth, money, PII, RCE, secret material | logging, cosmetic, info-leak of non-sensitive data |
+
+- **Critical:** reachable **+** exposed **+** sensitive sink. Or any **verified
+  live secret** (TruffleHog confirmed) — those are critical by definition.
+- **High:** two of three axes high, or a reachable CVE with a public exploit.
+- **Medium:** one axis high; present-but-not-clearly-reachable CVEs.
+- **Low / informational:** theoretical, unreachable, or test-only.
+
+Report criticals first with the concrete remediation (rotate / bump to fixed
+version / parameterize), then summarize the rest. Do not emit a flat list.
+
+## Cross-tool dedupe
+
+Tools overlap: osv-scanner and Trivy both flag the same CVE; gitleaks and
+TruffleHog both flag the same key.
+
+- **Dedupe key:** `(class, normalized-id, path, line)`.
+  - `normalized-id`: CVE/GHSA for SCA; rule id for SAST; secret fingerprint
+    (provider + redacted last-4 + location) for secrets.
+- **Keep the richest record** when two tools collide: prefer the one carrying
+  **verification** (TruffleHog `verified: true`) or **reachability**
+  (govulncheck), and merge the `tool` field into a list of contributors.
+
+## Severity normalization
+
+SARIF `level` (`error`/`warning`/`note`/`none`) and tool-native severities
+disagree. Map everything to one scale before ranking or gating:
+
+| Source signal | Normalized |
+|---|---|
+| SARIF `error` / CVSS ≥ 9.0 / verified secret | `critical` |
+| SARIF `error` / CVSS 7.0–8.9 / Semgrep `ERROR` | `high` |
+| SARIF `warning` / CVSS 4.0–6.9 / Semgrep `WARNING` | `medium` |
+| SARIF `note` / CVSS < 4.0 / `INFO` | `low` |
+
+Where a tool gives both CVSS and a label, take the **higher** of the two.
+
+## Suppression discipline
+
+A suppression is a per-finding record, not a silent ignore-file. Each one carries
+`who`, `why`, and `expiry` so it surfaces again instead of hiding the next bug.
+Use the tool-native suppression (osv-scanner.toml `ignoreUntil`, `.trivyignore`,
+gitleaks allowlist, `// nosemgrep`) and set `status: "suppressed"` in the report.
+
+## Report schema — `security-scan-report.json`
+
+This is the contract `scripts/verify.sh` gates on.
+
+```json
+{
+  "schemaVersion": "1.0",
+  "scannedAt": "<ISO-8601 UTC>",
+  "target": "<path or repo>",
+  "tools": [{ "name": "<tool>", "version": "<pinned>" }],
+  "summary": {
+    "critical": 0, "high": 0, "medium": 0, "low": 0, "suppressed": 0
+  },
+  "findings": [
+    {
+      "class": "sast | sca | secrets | misconfig",
+      "ruleId": "<CVE / GHSA / rule-id / secret-fingerprint>",
+      "path": "<file>",
+      "line": 0,
+      "severity": "critical | high | medium | low",
+      "status": "open | suppressed | fixed",
+      "tool": "<tool name>",
+      "exploitability": "reachable | exposed | theoretical",
+      "title": "<short human description>"
+    }
+  ]
+}
+```
+
+- `summary` counts must agree with `findings` (verify.sh tolerates an empty
+  `findings` array as a clean pass).
+- **Gate:** any `findings[]` with `status: "open"` and `severity: "critical"`
+  → fail. Strict mode also fails on `open` + `high`. `suppressed`/`fixed` never
+  fail. An empty/clean report exits `0`.
+</content>

package/skills/security-scan/scripts/verify.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — security-scan gate over security-scan-report.json
+#
+# USAGE
+#   ./verify.sh [path/to/security-scan-report.json]
+#   Defaults to ./security-scan-report.json in the current directory.
+#
+# WHAT IT DOES (read-only — never writes, never auto-fixes, never runs scanners)
+#   1. Locates the report. If it is ABSENT, exits 0 with a notice — the gate is
+#      vacuously clean (nothing scanned yet is not a failure).
+#   2. Parses it as JSON (requires jq).
+#   3. Validates the schema: schemaVersion, summary object, findings array, and
+#      that each finding carries class/ruleId/path/severity/status.
+#   4. Enforces the gate: any finding with status "open" at severity "critical"
+#      fails (exit 1). With STRICT=1, "open" + "high" also fails.
+#
+#   An empty/clean report (no open criticals, or an empty findings array)
+#   exits 0 — no false failure.
+#
+# ENV TOGGLES
+#   STRICT=1     Also fail on open HIGH findings (default: criticals only).
+#   NO_COLOR=1   Disable ANSI color.
+#
+# EXIT CODES
+#   0  Clean: report missing, empty, or no open critical (/high under STRICT).
+#   1  At least one open critical (or open high under STRICT).
+#   2  Usage / schema / tooling error (jq missing, malformed JSON, bad schema).
+# ============================================================================
+
+REPORT="${1:-./security-scan-report.json}"
+STRICT="${STRICT:-0}"
+
+if [ -n "${NO_COLOR:-}" ]; then
+  RED=""; YEL=""; GRN=""; RST=""
+else
+  RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+fi
+
+note() { printf '%s\n' "$*" >&2; }
+
+# --- 1. report absent => vacuously clean -----------------------------------
+if [ ! -e "$REPORT" ]; then
+  note "${YEL}notice:${RST} no report at '$REPORT' — nothing to gate. Clean."
+  exit 0
+fi
+
+# --- tooling ---------------------------------------------------------------
+if ! command -v jq >/dev/null 2>&1; then
+  note "${RED}error:${RST} jq is required to validate the report."
+  exit 2
+fi
+
+# --- 2. valid JSON ---------------------------------------------------------
+if ! jq -e . "$REPORT" >/dev/null 2>&1; then
+  note "${RED}error:${RST} '$REPORT' is not valid JSON."
+  exit 2
+fi
+
+# --- 3. schema -------------------------------------------------------------
+schema_ok=$(jq -e '
+  (has("schemaVersion"))
+  and (has("summary") and (.summary | type == "object"))
+  and (has("findings") and (.findings | type == "array"))
+  and (
+    .findings
+    | all(
+        (has("class")) and (has("ruleId")) and (has("path"))
+        and (has("severity")) and (has("status"))
+      )
+  )
+' "$REPORT" 2>/dev/null || echo "false")
+
+if [ "$schema_ok" != "true" ]; then
+  note "${RED}error:${RST} '$REPORT' does not conform to the schema"
+  note "       (need schemaVersion, summary{}, findings[] with"
+  note "        class/ruleId/path/severity/status on every finding)."
+  exit 2
+fi
+
+# --- 4. gate ---------------------------------------------------------------
+open_crit=$(jq '[.findings[] | select(.status == "open" and .severity == "critical")] | length' "$REPORT")
+open_high=$(jq '[.findings[] | select(.status == "open" and .severity == "high")] | length' "$REPORT")
+total=$(jq '.findings | length' "$REPORT")
+suppressed=$(jq '[.findings[] | select(.status == "suppressed")] | length' "$REPORT")
+
+note "Report: $REPORT  (findings: ${total}, suppressed: ${suppressed}, open-critical: ${open_crit}, open-high: ${open_high})"
+
+fail=0
+if [ "$open_crit" -gt 0 ]; then
+  note "${RED}FAIL:${RST} ${open_crit} open CRITICAL finding(s) — resolve or suppress with justification before merge."
+  jq -r '.findings[] | select(.status=="open" and .severity=="critical") | "  - [\(.class)] \(.ruleId)  \(.path)  \(.title // "")"' "$REPORT" >&2
+  fail=1
+fi
+if [ "$STRICT" = "1" ] && [ "$open_high" -gt 0 ]; then
+  note "${RED}FAIL (STRICT):${RST} ${open_high} open HIGH finding(s)."
+  jq -r '.findings[] | select(.status=="open" and .severity=="high") | "  - [\(.class)] \(.ruleId)  \(.path)  \(.title // "")"' "$REPORT" >&2
+  fail=1
+fi
+
+if [ "$fail" -eq 0 ]; then
+  note "${GRN}PASS:${RST} no open critical$([ "$STRICT" = "1" ] && echo "/high") findings."
+  exit 0
+fi
+exit 1