@damiangilgonzalez/harness 1.3.7

package/skills/security-scan/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: security-scan
+description: "Use when automated scanners drive a security sweep of a repo or app — SAST, dependency/lockfile CVEs, secrets in the tree or git history, IaC misconfig — and the raw output has to become one deduped, exploitability-ranked report CI can gate on. NOT threat-modeling, OWASP design reasoning, or hand-authoring the fix (that is `secure-coding`)."
+tags: [security, sast, sca, secrets, scanning, owasp]
+recommends: [secure-coding, github-actions]
+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: every finding traces to a scanner run with a
+`ruleId` and a source location, so the output is reproducible. Not eyeballing
+code, not authoring patches.
+
+**Read-only by default.** Scan, triage, report. Apply fixes (version bumps,
+rotation, `.gitignore` edits) only when the user asks — a security sweep that
+silently mutates the tree destroys the evidence and the trust.
+
+**Pin and verify your scanners.** Exact versions, verified checksums/SHAs, never
+`@latest` GitHub Actions. 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.
+
+## Scan classes and tool selection
+
+Four classes: **SAST** (injection, XSS, path traversal in *first-party* code),
+**SCA / deps** (known CVEs in dependency manifests + lockfiles), **Secrets**
+(credentials in the tree **or git history**), **Misconfig / IaC** (Dockerfile,
+k8s, Terraform, exposed config). Pick tools 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`, Semgrep rulesets |
+| 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 you normalize to it) — a common schema is what
+lets you merge four tools, dedupe, and feed one artifact into CI instead of four
+incompatible logs. **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 above)
+
+Trivy scans filesystems, images, and IaC and finds transitive CVEs `npm audit`
+misses.
+
+```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 `superpowers:verification-before-completion` for the broader
+  green gate this feeds.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+|---|---|
+| Pulling `aquasecurity/trivy-action@latest` because it is the official action | March 2026: a hijacked tag stole CI secrets. Pin a full SHA, verify provenance. |
+| Treating every scanner finding as a bug to fix | Most are noise. Rank by reachable + exposed + sensitive sink; report the few that matter. |
+| Calling the repo clean after scanning only the working tree | History holds the deleted keys. Scan git history; a removed-in-HEAD key is still leaked and live. |
+| Declaring deps fine because `npm audit` is clean | Native auditors miss transitive CVEs. Run osv-scanner/Trivy too; native is the fast pass, not the only pass. |
+| Committing a blanket `.semgrepignore` to quiet CI | A blanket ignore hides the next real bug. Suppress per-finding with a written justification + expiry. |
+| Deleting a verified key from the file and moving on | Deleting ≠ safe. Rotate the credential first, then scrub history. The committed value is already compromised. |
+| Taking the SARIF `level` as the severity | Tools disagree. Normalize to one scale before you rank or gate. |
+| Dumping all four tool outputs in the PR for the reviewer to sort | The reviewer won't. Merge, dedupe, rank, and emit one report. |
+| Letting the scan auto-fix the deps it finds | Read-only by default. Propose bumps; apply only when asked — never mutate during a sweep. |
+
+## Project grounding (docs + CLAUDE.md)
+
+In a project with a `docs/` layer (the [`harness`](../harness/SKILL.md)
+Karpathy wiki), record the scanner choices, pinned versions, gate thresholds, and
+any accepted-risk suppressions in `docs/wiki/stack/security-scan.md`, and index
+it in `docs/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short
+pointer to it). Read it first on every run so the next agent inherits the pinned
+tools and thresholds instead of re-deriving them. No `docs/`? Skip silently.
+Conventions are recorded, not gated — never block the scan on this.
+
+## See Also
+
+Reviewing a diff rather than scanning a repo: the `code-review` skill
+for correctness and quality, or `superpowers:requesting-code-review` for adversarial
+review against a spec.

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: code-review
+    why: General correctness/quality review of a diff is code-review's job, not a scanner-driven vuln sweep.
+  - prompt: "Run lint and tests and tell me if the green gate passes."
+    route_to: external:superpowers-verification-before-completion
+    why: The lint/type/test verification gate is superpowers' verification-before-completion's job; 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,97 @@
+# 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.

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

@@ -0,0 +1,92 @@
+# 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`.

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