vanara 0.1.0 → 0.2.0

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,146 @@
+---
+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.

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`).

package/catalog/agents/vuln-scanner/examples/scan-report.md

@@ -0,0 +1,49 @@
+# Example: Vulnerability Scan Report
+
+A worked example of the report shape this agent produces. Note the structure: a tight summary, a short
+*fix now* list, then everything else ranked below it. The raw scan had 47 findings; triage reduced the
+release-blocking set to 3.
+
+---
+
+## Summary
+
+- **Scope:** npm dependencies (lockfile), source secret scan, Dockerfile base image.
+- **Findings:** 1 critical, 2 high, 6 medium, 38 low/info (47 raw -> 9 actionable after triage).
+- **Most urgent:** rotate the AWS key committed in `config/legacy.env` — assume compromised.
+
+## Fix now (release-blocking)
+
+| Item | Severity | Fix | Breaking? | Reachability |
+|---|---|---|---|---|
+| AWS access key in `config/legacy.env` | critical | rotate in IAM, move to env var | n/a | Live credential, public history |
+| `lodash@4.17.15` (CVE-2020-8203) | high | -> `4.17.21` | no | Reachable via `util/merge.js` |
+| `axios@0.21.0` (SSRF, CVE-2021-3749) | high | -> `0.21.4` | no | Used in outbound webhook client |
+
+## Plan (schedule, not blocking)
+
+- **`next@12 -> 14` (3 medium CVEs):** breaking major. Clears 3 advisories but requires app-router
+  migration review. Estimate: 1 sprint. Group as one coordinated upgrade.
+- **`debug=true` in `config/prod.json`:** medium. Leaks stack traces to clients; set `false`.
+- **6 transitive medium CVEs in dev-only deps:** real but build-time only; bump opportunistically.
+
+## Exposed secrets
+
+| Secret | Location | Action |
+|---|---|---|
+| AWS access key `AKIA…` | `config/legacy.env:4` | **Rotate** in IAM (revoke old), replace with `AWS_ACCESS_KEY_ID` env var, add pre-commit secret hook |
+| Slack webhook URL | `scripts/notify.sh:12` | Rotate webhook in Slack, move to secret manager |
+
+Removal from the latest commit is **not** sufficient — both are still valid at the provider.
+
+## Config / container risks
+
+- **Base image `node:18.0-alpine`:** carries 4 OS-package CVEs. Bump to current `node:18-alpine` patch.
+- **Container runs as root:** add a non-root `USER` to the Dockerfile.
+
+## Accepted / suppressed (with reason)
+
+- **CVE-2025-XXXX in `fast-xml@3.1.0` (CVSS 9.8):** vulnerable `parseAttrs` path requires
+  `allowAttributes:true`; app uses defaults. Downgraded critical -> medium, scheduled.
+- **`AKIAEXAMPLE…` in `docs/setup.md`:** documentation placeholder, not a live key. Suppressed.
+- **CVE in `jest@…`:** dev/test-only dependency, not in production bundle. Backlog.

package/catalog/agents/vuln-scanner/references/remediation-and-severity.md

@@ -0,0 +1,68 @@
+# Remediation and Severity
+
+Once a finding is triaged, the deliverable is a *fix the reader can act on*. This reference defines the
+severity scale, the dependency-fix strategy, and the secret-rotation playbook.
+
+## Severity scale
+
+Use a single normalized scale across all scan families so the report is comparable:
+
+| Severity | Meaning | Default action |
+|---|---|---|
+| `critical` | Reachable RCE, auth bypass, or active secret leak | Block release; fix now |
+| `high` | Serious impact, exploitable with moderate effort | Fix before release |
+| `medium` | Real but constrained (limited reach or impact) | Schedule next sprint |
+| `low` | Minor / hardening | Backlog |
+| `info` | Awareness only | No action required |
+
+Final severity = scanner severity **adjusted by reachability and impact** (see
+[triage-and-false-positives](triage-and-false-positives.md)). Always show your adjustment reasoning.
+
+## Dependency remediation strategy
+
+For every vulnerable dependency, state the fix version and whether it's breaking:
+
+1. **Prefer the minimal bump that clears the CVE.** If `1.2.3 -> 1.2.4` fixes it, recommend that, not
+   the latest 3.x.
+2. **Label breaking vs. non-breaking** by semver distance and changelog. Crossing a major is breaking
+   until proven otherwise.
+3. **Transitive deps:** if you don't own the dependency directly, fix via the parent bump, or a
+   lockfile override / resolution (`overrides` in npm, `resolutions` in yarn/pnpm) — and flag overrides
+   as a temporary measure, not a permanent pin.
+4. **Group breaking upgrades separately** under *plan* with a migration-risk note. Never bundle a risky
+   major bump into a "quick fix" list.
+5. **No fix available?** Document the mitigation (disable the feature, add input validation, network
+   isolation) and mark for monitoring.
+
+```text
+Fix-now bucket  -> non-breaking bumps that clear critical/high, reachable
+Plan bucket     -> breaking upgrades, lower-severity, or coordinated changes
+Accept/monitor  -> no fix yet, or risk-accepted with justification
+```
+
+## Secret remediation — rotation, not removal
+
+A committed secret is compromised the moment it lands in a shared repo. The fix is always:
+
+1. **Rotate first.** Issue a new credential at the provider and revoke the old one. Until this is done,
+   the secret is live regardless of repo state.
+2. **Remove from code.** Replace with an env var or secret-manager reference.
+3. **Purge from history** if required (history rewrite or, more often, treat as exposed and rely on
+   rotation — rewriting shared history is disruptive and incomplete if the repo was cloned/forked).
+4. **Add prevention.** A pre-commit secret hook and a `.gitignore` entry so it doesn't recur.
+
+> "Deleted the key in the latest commit" is **not** remediation. The credential is still valid at the
+> provider and still present in every prior commit, clone, and CI cache.
+
+## Writing the remediation line
+
+Each finding's recommendation should be copy-pasteable and unambiguous:
+
+```text
+lodash 4.17.15 -> 4.17.21   | high | non-breaking | prototype-pollution CVE-2020-8203, reachable in util/merge.js
+AWS key in config/old.env   | critical | rotate    | revoke in IAM, replace with env var, add pre-commit hook
+debug=true in prod config    | medium | config     | set debug=false; leaks stack traces to clients
+```
+
+Tie remediation effort to severity so the reader can plan: a *fix now* of ten non-breaking bumps is an
+afternoon; one breaking major in *plan* may be a sprint. Make that tradeoff visible.

package/catalog/agents/vuln-scanner/references/scan-types-and-tools.md

@@ -0,0 +1,83 @@
+# Scan Types and Tools
+
+Vulnerability scanning is not one activity — it is a family of complementary techniques, each with a
+different blind spot. A credible scan combines several. Use this reference to pick the right family for
+the target and to understand what each one *cannot* see.
+
+## SCA — Software Composition Analysis (dependency scanning)
+
+Matches your resolved dependency versions against known-vulnerability databases (CVE/NVD, GitHub
+Advisory, OSV).
+
+- **Inputs:** lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `poetry.lock`, `Cargo.lock`, `go.sum`).
+  Always read the **lockfile**, not the manifest range — `^1.2.0` tells you nothing about what shipped.
+- **Strengths:** high-precision for *known* CVEs; cheap; covers transitive deps.
+- **Blind spots:** zero-days, logic bugs, anything not yet in an advisory DB. Version-only matching can
+  over-report (advisory may need a specific feature flag).
+- **Triage hook:** flag direct vs. transitive — a transitive CVE may be fixable only by bumping the
+  parent, or pinning via an override/resolution.
+
+```bash
+# Inventory before judging — never trust the manifest range alone
+node -e "const l=require('./package-lock.json');console.log(Object.keys(l.packages||{}).length,'resolved packages')"
+```
+
+## Secret scanning
+
+Finds credentials committed to the repo: API keys, tokens, private keys, connection strings,
+high-entropy blobs.
+
+- **Inputs:** working tree by default; git history when explicitly requested.
+- **Detection:** known-format regexes (e.g. `AKIA…` AWS keys, `ghp_…` GitHub tokens, `-----BEGIN ...
+  PRIVATE KEY-----`) plus entropy heuristics.
+- **Blind spots:** secrets in untracked files, encrypted blobs, or rotated-but-still-referenced values.
+- **Critical rule:** a found secret is assumed compromised. Removal ≠ remediation. See
+  [remediation-and-severity](remediation-and-severity.md) for the rotation playbook.
+
+```bash
+# Cheap first pass for common key formats (illustrative — a real scan uses a tool)
+grep -rERn 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|-----BEGIN [A-Z ]*PRIVATE KEY-----' . \
+  --include='*.*' || echo "no obvious key-format matches"
+```
+
+## SAST — Static Application Security Testing
+
+Analyzes source/AST for vulnerable patterns: injection sinks, unsafe deserialization, path traversal,
+hardcoded crypto, tainted-data flows.
+
+- **Strengths:** finds bugs in *your* code, not just dependencies; runs without deploying.
+- **Blind spots:** high false-positive rate; struggles with dynamic dispatch and framework magic;
+  cannot judge runtime config.
+- **Triage hook:** SAST output needs the heaviest false-positive filtering. Confirm the sink is
+  reachable with attacker-controlled input before alarming.
+
+## DAST — Dynamic Application Security Testing
+
+Probes a *running* application from the outside: injection, auth handling, misconfigured headers, TLS.
+
+- **Strengths:** finds runtime/config issues SAST can't see; low false positives for what it confirms.
+- **Blind spots:** only covers exercised endpoints; needs a deployed target; can be destructive.
+- **Boundary:** this agent does **not** perform live DAST/exploitation — that is a pen-test activity.
+  Note when DAST is warranted and hand off.
+
+## Container & IaC scanning
+
+When a `Dockerfile`, image, or infra-as-code (Terraform, Kubernetes manifests) is present:
+
+- **Base-image CVEs:** OS packages in the image carry their own advisories; a clean app on a stale base
+  image is still vulnerable.
+- **Image hygiene:** running as root, secrets baked into layers, unpinned `latest` tags.
+- **IaC misconfig:** public S3 buckets, `0.0.0.0/0` security groups, disabled encryption.
+
+## Choosing per target
+
+| Target present | Run | Primary risk caught |
+|---|---|---|
+| Lockfile | SCA | Known CVEs in deps |
+| Any source | Secret scan + SAST | Leaked creds, injection sinks |
+| Dockerfile / image | Container scan | Base-image CVEs, root, baked secrets |
+| Terraform / k8s | IaC scan | Public exposure, weak crypto config |
+| Deployed URL | DAST (hand off) | Runtime/config exploits |
+
+No single family is sufficient. Combine, then triage everything through
+[triage-and-false-positives](triage-and-false-positives.md).