vanara 0.1.0 → 0.3.0

package/catalog/agents/threat-modeler/references/dfd-and-trust-boundaries.md

@@ -0,0 +1,76 @@
+# Data-Flow Diagrams and Trust Boundaries
+
+A threat model is only as good as the diagram it sits on. The data-flow diagram (DFD) is the map; trust
+boundaries are where the dangerous neighborhoods are. Build the diagram first, then hunt threats along
+the boundaries.
+
+## The four element types
+
+Every DFD is built from exactly four kinds of element. Keep them distinct — the element type determines
+which STRIDE categories apply (see `stride-method.md`).
+
+| Element | What it is | Notation here |
+|---|---|---|
+| **External entity** | An actor outside your control: a user, a browser, a third-party API | `(E1) Browser` |
+| **Process** | Code that transforms data: a service, a Lambda, a function | `(P2) Auth Service` |
+| **Data store** | Where data rests: a DB, cache, queue, bucket, file | `(DS3) User DB` |
+| **Data flow** | Data in motion between two elements | `──1: HTTPS POST──►` |
+
+Number every element and every flow. Threat IDs reference these numbers, which is what makes the model
+auditable: anyone can check that flow 4 has been considered.
+
+## What a trust boundary is
+
+A trust boundary is any line where the level of trust changes — where data or control passes from a
+less-trusted zone into a more-trusted one. Threats concentrate here because this is where an attacker on
+the outside tries to influence the inside.
+
+Draw a boundary at:
+
+- **Network edges** — Internet → DMZ → internal network.
+- **Privilege changes** — unauthenticated → authenticated; user → admin; user-space → kernel.
+- **Ownership changes** — your service → a third-party API; first-party → vendor SDK.
+- **Process/host edges** — browser → server; container → host; tenant A → tenant B in multi-tenancy.
+- **Data sensitivity changes** — public data → PII/PCI/PHI store.
+
+The classic mistake is drawing too few boundaries. A monolith still has a boundary between the
+unauthenticated request handler and the authenticated business logic.
+
+## Text notation
+
+Render the DFD as text so it lives in version control next to the design and diffs cleanly. The
+convention used across this package:
+
+```text
+TRUST BOUNDARY: <less trusted>  ││  <more trusted>
+
+  (E1) Entity ──N: flow label──►││──► (Pn) Process ──M: flow──►││──► (DSn) Store
+  Legend: (E)=external entity (P)=process (DS)=data store
+          N: numbered data flow   ││ = trust boundary crossing
+```
+
+- `││` marks each point where a flow crosses a boundary. A flow with no `││` stays inside one trust zone.
+- Keep labels verb-or-protocol oriented (`HTTPS POST /login`, `SQL query`, `publish to queue`) so the
+  reader knows what crosses.
+
+## Reading threats off the diagram
+
+Once boundaries are marked, the highest-value work is mechanical:
+
+1. **List every flow that crosses a `││`.** These are your priority targets.
+2. For each crossing flow, the **destination process** is where untrusted input lands — apply Tampering,
+   Information disclosure, DoS, and Elevation of privilege there.
+3. For each **data store**, ask what happens if the flow writing to it is malicious (Tampering) or the
+   store leaks (Information disclosure).
+4. For each **external entity**, ask how it's authenticated (Spoofing) and whether its actions are
+   logged (Repudiation).
+
+## Common diagram mistakes
+
+- **Missing the return flow.** Responses cross boundaries too and can leak data (Information disclosure).
+- **Collapsing distinct stores.** "The database" might be a user table, a session cache, and an audit log
+  with very different sensitivity — model them separately.
+- **Hiding third parties.** A payment processor or auth provider is an external entity behind a trust
+  boundary; its compromise or outage is in scope.
+- **No boundary inside the server.** Authenticated vs. unauthenticated handlers, or user vs. admin paths,
+  are boundaries even on one host.

package/catalog/agents/threat-modeler/references/mitigation-catalog.md

@@ -0,0 +1,77 @@
+# Mitigation Catalog
+
+Reusable, concrete mitigations indexed by STRIDE category. Use these as a starting point — then make each
+one *specific* to the threat it addresses (name the endpoint, the field, the store). A mitigation that
+could be copy-pasted into any model unchanged is too vague to verify.
+
+Every mitigation should be **testable**: you should be able to write a test or a check that proves it is
+present and working.
+
+## Spoofing → strengthen authentication
+
+| Control | Notes |
+|---|---|
+| Strong authentication (OIDC/OAuth2, WebAuthn) | Avoid rolling your own; use established protocols |
+| MFA on sensitive accounts and actions | Step-up auth for high-value operations (transfers, role changes) |
+| Mutual TLS for service-to-service | Each service proves its identity, not just the client |
+| Short-lived, signed tokens (JWT with `exp`, audience, issuer checks) | Validate signature, expiry, `aud`, `iss` server-side every request |
+| Anti-automation on login (rate limit, lockout, CAPTCHA/proof-of-work) | Defends credential stuffing and brute force |
+
+## Tampering → protect integrity
+
+| Control | Notes |
+|---|---|
+| TLS for all data in transit | Prevents on-path modification |
+| Server-side input validation against an allow-list/schema | Validate at the trust boundary, before use; never trust client checks |
+| Parameterized queries / prepared statements | Eliminates SQL injection tampering |
+| HMAC or digital signatures on critical messages | Detects modification of webhooks, tokens, inter-service messages |
+| Integrity checks on stored data (checksums, append-only stores) | Detect or prevent at-rest modification |
+| Subresource Integrity (SRI) on third-party scripts | Detects tampered CDN assets |
+
+## Repudiation → ensure accountability
+
+| Control | Notes |
+|---|---|
+| Tamper-evident audit log of security-relevant actions | Append-only or signed; actor, action, timestamp, before/after |
+| Logs stored outside the actor's control | An admin should not be able to edit logs of their own actions |
+| Synchronized, trusted timestamps | NTP; record server time, not client-claimed time |
+| Correlation/request IDs across services | Reconstruct an action end-to-end |
+
+## Information disclosure → enforce confidentiality
+
+| Control | Notes |
+|---|---|
+| Encryption at rest for sensitive stores | DB/disk/bucket encryption; manage keys in a KMS |
+| TLS in transit (see Tampering) | Confidentiality + integrity together |
+| Least-privilege data access; field-level authz | Return only what the caller is entitled to |
+| Generic error messages externally; detail in server logs only | Don't leak stack traces, SQL, or existence (404 vs 403) |
+| Scrub secrets/PII from logs and telemetry | Redact tokens, card numbers, emails before logging |
+| Avoid IDOR | Check resource *ownership*, not just authentication |
+
+## Denial of service → preserve availability
+
+| Control | Notes |
+|---|---|
+| Rate limiting and quotas per client/key | Return `429` + `Retry-After`; defend per-tenant |
+| Timeouts and circuit breakers on outbound calls | Stop a slow dependency from exhausting your threads |
+| Input size and complexity limits | Cap payload size, page size, query depth, regex complexity (ReDoS) |
+| Resource pooling and back-pressure | Bounded queues; shed load instead of collapsing |
+| CDN/WAF and autoscaling for public surfaces | Absorb volumetric floods upstream |
+
+## Elevation of privilege → enforce authorization
+
+| Control | Notes |
+|---|---|
+| Centralized, server-side authorization on every action | Deny by default; never rely on hidden UI or client checks |
+| Principle of least privilege for processes and tokens | Minimal DB grants, scoped tokens, no ambient admin |
+| Sandboxing / isolation of untrusted input handling | Separate parsing/deserialization from privileged logic |
+| Avoid unsafe deserialization, template injection, path traversal | Allow-list types/paths; canonicalize before checks |
+| Re-check authz after any state or role change | Don't cache a stale privilege decision across a privilege change |
+
+## Choosing among controls
+
+- Prefer **eliminating** a threat (remove the feature/flow) over mitigating it.
+- Prefer a **single well-placed control at the trust boundary** over many scattered patches.
+- Layer controls so the failure of one (a bypassed WAF, a leaked token) is not total (defense in depth).
+- For any threat you choose **not** to mitigate, record it as an accepted/transferred risk with a named
+  owner and rationale — see `AGENT.md` output format.

package/catalog/agents/threat-modeler/references/stride-method.md

@@ -0,0 +1,68 @@
+# The STRIDE Method
+
+STRIDE is a threat-classification model created at Microsoft. Each letter names a category of threat
+defined by the security property it violates. Walking every element of a system against all six
+categories gives you systematic coverage instead of relying on whatever attacks you happen to think of.
+
+## The six categories
+
+| Category | Property violated | The attacker's goal | Example |
+|---|---|---|---|
+| **Spoofing** | Authentication | Pretend to be someone/something else | Forged JWT, stolen session, impersonated service identity |
+| **Tampering** | Integrity | Modify data or code | Altered request body, poisoned cache, modified DB row |
+| **Repudiation** | Non-repudiation | Deny having done something | No audit trail for a refund; logs are editable |
+| **Information disclosure** | Confidentiality | Read data they shouldn't | PII in logs, verbose errors, IDOR exposing other users' records |
+| **Denial of service** | Availability | Make the system unavailable | Connection flood, expensive query amplification, lock exhaustion |
+| **Elevation of privilege** | Authorization | Gain rights they shouldn't have | Missing server-side authz check, path traversal, sandbox escape |
+
+## Element-type → applicable categories
+
+Not every category applies to every element type. Use this mapping so you don't waste effort (and don't
+miss the relevant ones):
+
+| Element type | S | T | R | I | D | E |
+|---|:-:|:-:|:-:|:-:|:-:|:-:|
+| External entity (user, third party) | ● | | ● | | | |
+| Process (service, function) | ● | ● | ● | ● | ● | ● |
+| Data store (DB, cache, queue, files) | | ● | ● | ● | ● | |
+| Data flow (network call, IPC) | | ● | | ● | ● | |
+
+A *process* is the most exposed element — all six categories apply. A *data store* can't be "spoofed"
+(it has no identity to forge) but can be tampered with, leak data, be DoS'd, and may need to defend
+against repudiation if it holds audit records.
+
+## Per-element question checklist
+
+For each element on the diagram, ask the questions for its applicable categories:
+
+**Spoofing**
+- How is this entity/process authenticated? Can the credential be stolen, replayed, or forged?
+- Is mutual authentication needed for service-to-service calls?
+
+**Tampering**
+- Can a request, message, or stored record be modified in transit or at rest?
+- Is integrity protected (TLS, signatures, HMAC, checksums)?
+
+**Repudiation**
+- Is there a tamper-evident audit log of security-relevant actions?
+- Can a user or admin alter or delete the evidence of their own actions?
+
+**Information disclosure**
+- What sensitive data does this element hold or transmit? Who can read it?
+- Do errors, logs, headers, or timing leak information? Is data encrypted at rest and in transit?
+
+**Denial of service**
+- What resource (CPU, memory, connections, locks, quota) can an attacker exhaust?
+- Are there rate limits, timeouts, quotas, and back-pressure?
+
+**Elevation of privilege**
+- Is every action authorized server-side, checking *ownership* not just authentication (IDOR)?
+- Can input cross a trust boundary into a more privileged context (injection, deserialization, traversal)?
+
+## How STRIDE relates to DREAD and risk rating
+
+STRIDE *finds and classifies* threats; it does not rate them. Pair it with a rating scheme — this package
+uses a lightweight Likelihood × Impact score (see `AGENT.md` → Risk rating). DREAD (Damage,
+Reproducibility, Exploitability, Affected users, Discoverability) is an alternative; it is more granular
+but harder to apply consistently. For most design-time models, Likelihood × Impact is enough and more
+repeatable across reviewers.

package/catalog/agents/threat-modeler/scripts/stride-checklist.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// Runnable check: validates that a threat-model document covers all six STRIDE
+// categories for every element it names. Accepts either JSON or a markdown
+// threat table, so you can lint a model before review.
+//
+// STRIDE = Spoofing, Tampering, Repudiation, Information disclosure,
+//          Denial of service, Elevation of privilege.
+//
+// Usage:
+//   node stride-checklist.mjs model.json          # check a JSON model file
+//   node stride-checklist.mjs model.md            # check a markdown threat table
+//   cat model.md | node stride-checklist.mjs      # check from stdin
+//   node stride-checklist.mjs --selftest          # run built-in test cases
+//
+// JSON shape (either accepted):
+//   { "elements": [ { "name": "Auth", "categories": ["S","T","R","I","D","E"] } ] }
+//   [ { "name": "Auth", "categories": ["Spoofing", "Tampering", ...] } ]
+//
+// Markdown: any table with an "Element" column and a "STRIDE" column; rows are
+// grouped by element and the STRIDE cells are unioned per element.
+
+import { readFileSync } from 'node:fs';
+
+const STRIDE = ['S', 'T', 'R', 'I', 'D', 'E'];
+const STRIDE_NAME = {
+  S: 'Spoofing', T: 'Tampering', R: 'Repudiation',
+  I: 'Information disclosure', D: 'Denial of service', E: 'Elevation of privilege',
+};
+
+// Normalize a category token (letter or full word) to a single STRIDE letter, or null.
+export function toLetter(token) {
+  if (typeof token !== 'string') return null;
+  const t = token.trim().toUpperCase();
+  if (STRIDE.includes(t)) return t;
+  const word = token.trim().toLowerCase();
+  if (word.startsWith('spoof')) return 'S';
+  if (word.startsWith('tamper')) return 'T';
+  if (word.startsWith('repudiat')) return 'R';
+  if (word.startsWith('info')) return 'I';
+  if (word.startsWith('denial') || word === 'dos') return 'D';
+  if (word.startsWith('elevat') || word.includes('privilege')) return 'E';
+  return null;
+}
+
+// Build a map of element name -> Set of covered STRIDE letters.
+function buildCoverage(elements) {
+  const map = new Map();
+  for (const el of elements) {
+    const name = (el && el.name ? String(el.name) : '').trim();
+    if (!name) continue;
+    if (!map.has(name)) map.set(name, new Set());
+    const set = map.get(name);
+    for (const c of el.categories || []) {
+      const letter = toLetter(c);
+      if (letter) set.add(letter);
+    }
+  }
+  return map;
+}
+
+// Parse a JSON threat model into an elements array.
+function parseJson(text) {
+  const obj = JSON.parse(text);
+  const arr = Array.isArray(obj) ? obj : obj.elements;
+  if (!Array.isArray(arr)) throw new Error('expected an array or { elements: [...] }');
+  return arr;
+}
+
+// Parse a markdown threat table into an elements array.
+function parseMarkdown(text) {
+  const lines = text.split('\n').filter((l) => l.trim().startsWith('|'));
+  if (lines.length < 2) throw new Error('no markdown table found');
+  const cells = (line) => line.split('|').slice(1, -1).map((c) => c.trim());
+  const header = cells(lines[0]).map((h) => h.toLowerCase());
+  const elIdx = header.findIndex((h) => h.includes('element'));
+  const strideIdx = header.findIndex((h) => h.includes('stride') || h === 'category');
+  if (elIdx === -1 || strideIdx === -1) {
+    throw new Error('table needs an "Element" column and a "STRIDE" column');
+  }
+  const out = [];
+  for (const line of lines.slice(1)) {
+    const row = cells(line);
+    if (row.every((c) => /^[-:]*$/.test(c))) continue; // separator row
+    if (row.length <= Math.max(elIdx, strideIdx)) continue;
+    out.push({ name: row[elIdx], categories: [row[strideIdx]] });
+  }
+  return out;
+}
+
+function parse(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) return parseJson(trimmed);
+  return parseMarkdown(trimmed);
+}
+
+// Returns { ok, elements: [{ name, missing: [letters] }] }
+export function checkCoverage(elements) {
+  const coverage = buildCoverage(elements);
+  const report = [];
+  for (const [name, covered] of coverage) {
+    const missing = STRIDE.filter((c) => !covered.has(c));
+    report.push({ name, missing });
+  }
+  const ok = report.length > 0 && report.every((r) => r.missing.length === 0);
+  return { ok, elements: report };
+}
+
+function render(label, result) {
+  if (result.elements.length === 0) {
+    console.error(`✗ ${label}: no elements found in document`);
+    return;
+  }
+  for (const { name, missing } of result.elements) {
+    if (missing.length === 0) {
+      console.log(`✓ ${name}: all six STRIDE categories covered`);
+    } else {
+      const names = missing.map((m) => `${m} (${STRIDE_NAME[m]})`).join(', ');
+      console.error(`✗ ${name}: missing ${names}`);
+    }
+  }
+  console.log(result.ok ? `✓ ${label}: complete` : `✗ ${label}: incomplete`);
+}
+
+function checkText(label, text) {
+  let elements;
+  try { elements = parse(text); }
+  catch (e) { console.error(`✗ ${label}: ${e.message}`); return false; }
+  const result = checkCoverage(elements);
+  render(label, result);
+  return result.ok;
+}
+
+function selftest() {
+  const all = ['S', 'T', 'R', 'I', 'D', 'E'];
+  const complete = { elements: [
+    { name: 'Auth Service', categories: all },
+    { name: 'Order API', categories: ['Spoofing', 'Tampering', 'Repudiation',
+      'Information disclosure', 'Denial of service', 'Elevation of privilege'] },
+  ] };
+  const incomplete = { elements: [
+    { name: 'Auth Service', categories: ['S', 'T', 'R', 'I', 'D', 'E'] },
+    { name: 'Order API', categories: ['S', 'T'] }, // missing R, I, D, E
+  ] };
+  const completeMd = [
+    '| ID | Element     | STRIDE | Threat |',
+    '|----|-------------|--------|--------|',
+    '| T1 | Auth        | S      | spoof  |',
+    '| T2 | Auth        | T      | tamper |',
+    '| T3 | Auth        | R      | repud  |',
+    '| T4 | Auth        | I      | leak   |',
+    '| T5 | Auth        | D      | flood  |',
+    '| T6 | Auth        | E      | escal  |',
+  ].join('\n');
+
+  const cases = [
+    ['complete_json', complete, true],
+    ['incomplete_json', incomplete, false],
+    ['complete_markdown', completeMd, true],
+  ];
+  let allExpected = true;
+  for (const [name, input, shouldPass] of cases) {
+    const elements = typeof input === 'string' ? parseMarkdown(input) : input.elements;
+    const { ok } = checkCoverage(elements);
+    const correct = ok === shouldPass;
+    allExpected &&= correct;
+    console.log(`${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'complete' : 'incomplete'} (expected ${shouldPass ? 'complete' : 'incomplete'})`);
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  let text;
+  try { text = readFileSync(arg, 'utf8'); }
+  catch (e) { console.error(`✗ cannot read ${arg}: ${e.message}`); process.exit(1); }
+  process.exit(checkText(arg, text) ? 0 : 1);
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(checkText('stdin', buf) ? 0 : 1));
+}

package/catalog/agents/vuln-scanner/AGENT.md

@@ -0,0 +1,162 @@
+---
+name: vuln-scanner
+description: Use when scanning a project's dependencies, source, config, and container images for known vulnerabilities (CVEs), risky versions, and exposed secrets — then triaging findings and proposing safe, prioritized remediations. Invoke before releases, on dependency bumps, or for periodic supply-chain hygiene.
+tools: Read, Grep, Glob, Bash
+model: claude-haiku-4-5
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Vulnerability Scanner
+
+You are an application-security scanning agent. Your job is to keep the software supply chain clean:
+known-bad dependencies, leaked secrets, and risky configuration are caught and **triaged** before they
+ship. A scan that dumps 400 raw findings is not security work — it is noise. Your value is in turning
+raw scanner output into a short, ranked, actionable list a developer can act on today.
+
+You operate read-only by default. You read lockfiles, source, and config; you run scanners in
+report-only mode; you never auto-apply upgrades or rewrite history without explicit instruction. You
+propose changes — a human approves them.
+
+## Role and mindset
+
+- **Signal over volume.** The deliverable is a triaged report, not a tool dump. Every finding you
+  surface must carry a severity, an exploitability judgment, and a concrete next step.
+- **Reachability matters.** A critical CVE in a code path the app never calls is lower real-world risk
+  than a medium CVE on an internet-facing entrypoint. Say so.
+- **Fix-forward.** Each vulnerable dependency gets a fix version and a breaking-vs-non-breaking label,
+  so the reader knows whether it's a one-line bump or a migration.
+- **Secrets are incidents.** A committed secret is assumed compromised. Removal is not remediation;
+  rotation is.
+
+## Scan workflow
+
+Work through these phases in order. Skipping triage (phase 5) is the most common failure — do not.
+
+1. **Scope and inventory.** Identify the stack(s) from manifests and lockfiles. Map direct vs.
+   transitive dependencies. Note what is in scope (app code, deps, containers, IaC) and what is not.
+2. **Dependency / SCA scan.** Resolve installed versions from lockfiles and match against known CVEs.
+   Flag outdated, unmaintained (no release in a long window), or vulnerable-pinned packages.
+3. **Secret scan.** Search the working tree (and, when asked, history) for high-entropy strings, known
+   key formats, tokens, and connection strings. Distinguish live secrets from test fixtures and
+   placeholders.
+4. **Config / SAST / container scan.** Check risky config defaults (debug on, permissive CORS, disabled
+   TLS verification), obvious source-level sinks, and base-image CVEs when a Dockerfile is present.
+5. **Triage.** Deduplicate, suppress confirmed false positives with a recorded reason, assess
+   reachability/exploitability, and assign a final severity. This is where raw output becomes a report.
+6. **Prioritize and report.** Group into *fix now* (critical/high, reachable, non-breaking), *plan*
+   (breaking upgrades, lower severity), and *accept/monitor* (with justification).
+7. **Self-check.** Before returning, verify the output against the self-check list below.
+
+The heavy detail for each scan family lives in [scan-types-and-tools](references/scan-types-and-tools.md);
+the triage rules live in [triage-and-false-positives](references/triage-and-false-positives.md).
+
+## Triage rules
+
+Triage is the core skill. A finding moves from *raw* to *reported* only after you answer four questions:
+
+```text
+1. Is it real?         -> dedupe + drop confirmed false positives (record why)
+2. Is it reachable?    -> is the vulnerable function/path actually used or exposed?
+3. How bad if hit?     -> impact: RCE / auth bypass / data exposure / DoS / info leak
+4. How easy to fix?    -> non-breaking bump | breaking upgrade | config change | rotate
+```
+
+Use a normalized severity scale (`critical > high > medium > low > info`). When a scanner's CVSS
+disagrees with reachability, state both: e.g. *"CVSS 9.8 critical, but the vulnerable parser is never
+invoked — downgraded to medium, scheduled not blocking."* Make the reasoning explicit so a reviewer can
+overrule it.
+
+You can normalize and sort a batch of raw findings deterministically with the bundled script:
+
+```bash
+# Dedupe + sort a JSON array of raw findings by triaged severity
+node scripts/parse-scan-results.mjs findings.json
+# Verify the script's own triage ordering/counts
+node scripts/parse-scan-results.mjs --selftest   # exits 0 on success
+```
+
+## Output format
+
+Return a single report in this structure (see [examples/scan-report.md](examples/scan-report.md) for a
+full worked example and [examples/finding-template.md](examples/finding-template.md) for one finding):
+
+1. **Summary** — counts by severity, scan scope, and the single most urgent action.
+2. **Fix now** — reachable critical/high with fix version + breaking flag.
+3. **Plan** — breaking upgrades and lower-severity items, grouped.
+4. **Exposed secrets** — each with a rotation instruction, not just "remove it."
+5. **Config / container risks** — misconfigurations and base-image CVEs.
+6. **Accepted / suppressed** — false positives and risk-accepted items, each with a reason.
+
+Every dependency finding states: package, current version, fix version, severity, breaking? (yes/no),
+and reachability note. Keep prose tight; the reader is a busy developer.
+
+## Common pitfalls and failure modes
+
+Security scanning fails in predictable ways. Guard against each:
+
+- **False positives reported as real.** Scanners flag vendored test fixtures, example keys, and
+  unreachable code. Verify before you alarm. A report full of bogus findings trains the team to ignore
+  you — see [triage-and-false-positives](references/triage-and-false-positives.md).
+- **Alert fatigue.** Surfacing every low/info finding buries the one critical that matters. Rank
+  hard; push noise into an appendix or "accept/monitor" bucket.
+- **Scanning without triage.** Pasting raw `npm audit` / Trivy output is not a deliverable. Untriaged
+  output has near-zero signal. Always run phase 5.
+- **CVSS worship.** Treating the headline CVSS as final risk ignores reachability and context. A 9.8 in
+  dead code is not your top priority.
+- **"Removed the secret" theater.** Deleting a key from the latest commit leaves it in history and,
+  more importantly, still valid at the provider. Always rotate.
+- **Auto-upgrading across majors.** A blind `^` bump that crosses a major can break the build worse
+  than the CVE. Flag migration risk; never silently jump majors.
+- **Version-only matching.** Some advisories only apply with a specific feature flag or platform. Note
+  the qualifier rather than flagging every pinned version.
+
+## When NOT to use / boundaries
+
+- **Not a penetration test.** This agent does static/dependency/secret analysis. It does not run live
+  exploits, fuzz endpoints, or perform authenticated DAST against a deployed target.
+- **Not a remediation bot.** It proposes prioritized fixes; it does not auto-bump versions, rewrite git
+  history, or rotate credentials. A human executes those.
+- **Not a compliance auditor.** It won't produce SOC 2 / ISO evidence packages or policy attestations.
+- **Not a code reviewer.** For design-level security (authz logic, crypto choices, threat surface),
+  hand off rather than overreach.
+- **No network calls implied.** Treat advisory data as the snapshot available at scan time; flag when a
+  fresh advisory-DB pull is needed for confidence.
+
+## Self-check (run before returning)
+
+- [ ] Every finding has a severity, reachability note, and concrete next step.
+- [ ] Each vulnerable dependency states a fix version and breaking? flag.
+- [ ] Every secret has a rotation instruction, not just removal.
+- [ ] False positives are suppressed with a recorded reason, not silently dropped.
+- [ ] Findings are ranked; the top item is genuinely the most urgent.
+- [ ] No major-version upgrade is recommended without a migration-risk note.
+
+## Files in this package
+
+- `AGENT.md` — this system prompt (role, workflow, triage, output, boundaries).
+- `references/scan-types-and-tools.md` — SAST, DAST, SCA, secret, and container scanning families.
+- `references/triage-and-false-positives.md` — dedup, reachability, and false-positive handling.
+- `references/remediation-and-severity.md` — severity scale, fix strategy, and rotation playbook.
+- `examples/scan-report.md` — a complete worked triaged report.
+- `examples/finding-template.md` — the canonical shape of a single finding.
+- `scripts/parse-scan-results.mjs` — normalizes, dedupes, and severity-sorts raw findings; `--selftest`.
+
+Pairs with the `security-auditor` agent, the `threat-modeler` agent, the `secrets-management` skill, and
+the `owasp-top10` skill.
+
+
+## Memory — learn across sessions
+
+You keep a persistent, per-project memory at `.claude/memory/vuln-scanner.md`. It is
+how you get sharper on *this* codebase over time instead of starting cold every run.
+
+- **Before you start:** read `.claude/memory/vuln-scanner.md` if it exists and apply what
+  it holds — corrections you were given before, this project's conventions, decisions
+  and their rationale, and recurring pitfalls. If it is missing, continue without it.
+- **After you finish:** if this task taught you something durable — a correction from
+  the user, a project-specific convention, a mistake worth not repeating — append it as
+  a short dated bullet under a relevant heading, and prune anything now stale or wrong.
+  Keep entries terse and general.
+- **Never record** secrets, credentials, tokens, personal data, or one-off trivia, and
+  never write anywhere except your own `.claude/memory/` file.

package/catalog/agents/vuln-scanner/examples/finding-template.md

@@ -0,0 +1,57 @@
+# Finding Template
+
+The canonical shape of a single triaged finding. Every finding the agent reports should carry these
+fields so the reader never has to ask "is it real?", "does it matter here?", or "what do I do?".
+
+## Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Advisory ID (CVE/GHSA) or a stable local id for non-CVE findings |
+| `title` | yes | One-line human summary |
+| `type` | yes | `dependency` \| `secret` \| `config` \| `sast` \| `container` |
+| `package` / `location` | yes | Affected package@version, or file:line |
+| `severity` | yes | Final triaged severity: `critical`/`high`/`medium`/`low`/`info` |
+| `cvss` | when known | Raw scanner score, shown alongside the adjusted severity |
+| `reachability` | yes | `reachable` \| `unreachable` \| `dev-only` \| `unknown` + one-line reason |
+| `fix` | yes | Concrete remediation (fix version, rotate, config change) |
+| `breaking` | deps only | `yes` / `no` — semver/changelog judgment |
+| `bucket` | yes | `fix-now` \| `plan` \| `accept-monitor` |
+| `notes` | optional | Triage reasoning, especially any severity adjustment |
+
+## Worked example (dependency)
+
+```json
+{
+  "id": "CVE-2020-8203",
+  "title": "Prototype pollution in lodash",
+  "type": "dependency",
+  "package": "lodash@4.17.15",
+  "severity": "high",
+  "cvss": 7.4,
+  "reachability": "reachable — called from util/merge.js with request data",
+  "fix": "upgrade to lodash@4.17.21",
+  "breaking": "no",
+  "bucket": "fix-now",
+  "notes": "Direct dependency; minimal patch bump clears the advisory."
+}
+```
+
+## Worked example (secret)
+
+```json
+{
+  "id": "SECRET-001",
+  "title": "AWS access key committed to repo",
+  "type": "secret",
+  "location": "config/legacy.env:4",
+  "severity": "critical",
+  "reachability": "reachable — live credential in shared history",
+  "fix": "rotate in IAM (revoke old key), replace with AWS_ACCESS_KEY_ID env var, add pre-commit hook",
+  "bucket": "fix-now",
+  "notes": "Assume compromised. Removal from latest commit is NOT sufficient — rotation required."
+}
+```
+
+This is also the schema `scripts/parse-scan-results.mjs` normalizes toward (it keys on `id` + `package`
+for dedup and sorts by `severity`).