vanara 0.1.0 → 0.2.0

package/catalog/agents/vuln-scanner/references/triage-and-false-positives.md

@@ -0,0 +1,73 @@
+# Triage and False Positives
+
+Triage is the difference between a security agent and a `grep` wrapper. Raw scanner output is a starting
+point with a high noise floor; this reference is how you turn it into signal.
+
+## The triage pipeline
+
+```text
+raw findings
+  -> normalize    (one schema: id, package, severity, location, source-tool)
+  -> dedupe       (same CVE from SCA + container scan = one finding)
+  -> false-positive filter (suppress with a recorded reason)
+  -> reachability assessment (is the vulnerable path used/exposed?)
+  -> final severity (CVSS adjusted by reachability + impact)
+  -> rank + bucket (fix now / plan / accept-monitor)
+```
+
+The bundled `scripts/parse-scan-results.mjs` automates normalize + dedupe + severity sort. Human
+judgment owns the false-positive and reachability steps.
+
+## Deduplication
+
+The same underlying CVE often appears from multiple tools and multiple dependency paths. Collapse them:
+
+- Key on the advisory ID (CVE / GHSA) **plus** the affected package+version.
+- Keep the highest-confidence source and union the locations.
+- Count once in the summary. Reporting one CVE five times manufactures fake urgency and is a form of
+  alert fatigue.
+
+## Identifying false positives
+
+Common false positives and how to confirm them:
+
+| Pattern | Why it's flagged | How to confirm it's benign |
+|---|---|---|
+| Example/placeholder secret | Matches a key regex | Value is `AKIAEXAMPLE…`, in `*.example`, or in test fixtures |
+| Vendored test data | CVE in a bundled sample | Path is under `test/`, `fixtures/`, `__mocks__/` and not shipped |
+| Unreachable CVE | Vulnerable function never called | `grep` for the import/call; if absent, code path is dead |
+| Dev-only dependency | CVE in a build/test tool | Not in production bundle; lower severity, not zero |
+| Feature-gated advisory | Applies only with a flag on | Confirm the flag/default; note the qualifier |
+
+**Always record the suppression reason.** A silently dropped finding is indistinguishable from a missed
+one. Put suppressed items in an "Accepted / suppressed" section with their justification.
+
+## Reachability — the multiplier
+
+Reachability is what separates theoretical from exploitable risk:
+
+- **Exposed + reachable** (e.g. a deserialization CVE on a public POST handler): keep or raise severity.
+- **Present but unreachable** (vulnerable parser never invoked): downgrade, schedule, don't block.
+- **Dev/build-time only:** real but lower; an attacker needs supply-chain or CI access to exploit.
+
+State the reasoning explicitly so a reviewer can overrule:
+
+> CVE-2025-XXXX (CVSS 9.8) in `fast-xml@3.1.0`. The vulnerable `parseAttrs` path is only hit when
+> `allowAttributes:true`; this app calls the parser with defaults. **Downgraded critical -> medium**,
+> scheduled, not release-blocking.
+
+## Avoiding alert fatigue
+
+- Hard-rank. The top finding must be the genuinely most urgent, not the highest raw CVSS.
+- Bucket aggressively: *fix now* should be short (single digits ideally). Everything else goes to
+  *plan* or *accept/monitor*.
+- Push low/info findings into an appendix. Do not make a reader scroll past 200 lows to find the one
+  critical — that is how real issues get missed.
+- Be consistent run-to-run so developers can diff reports and see what's new.
+
+## When triage is genuinely uncertain
+
+If you cannot determine reachability from static analysis alone, say so and assign provisional severity
+on the conservative side, with a note on what would resolve the uncertainty (e.g. "needs DAST against
+staging" or "confirm whether `module X` is in the production bundle"). Honest uncertainty beats false
+confidence in either direction.

package/catalog/agents/vuln-scanner/scripts/parse-scan-results.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Normalizes a list of raw vulnerability findings: dedupes and sorts by
+// triaged severity. Demonstrates the triage step (raw output -> ranked list)
+// from this agent package. Zero dependencies; Node built-ins only.
+//
+// Usage:
+//   node parse-scan-results.mjs findings.json     # read a JSON array from a file
+//   cat findings.json | node parse-scan-results.mjs   # read from stdin
+//   node parse-scan-results.mjs --selftest        # run built-in tests (exit 0/1)
+//
+// Input: JSON array of findings, each with at least { id, severity }.
+// Optional fields: package, location, cvss, reachability, fix, bucket.
+// Output: { total, deduped, bySeverity, findings } sorted critical -> info.
+
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'info'];
+const SEVERITY_RANK = Object.fromEntries(SEVERITY_ORDER.map((s, i) => [s, i]));
+
+function normalizeSeverity(sev) {
+  const s = String(sev ?? '').toLowerCase().trim();
+  return SEVERITY_RANK[s] !== undefined ? s : 'info';
+}
+
+// Dedup key: advisory id + affected package/location. The same CVE reported by
+// multiple tools or via multiple paths collapses to one finding.
+function dedupKey(f) {
+  const id = String(f.id ?? 'unknown').toLowerCase();
+  const where = String(f.package ?? f.location ?? '').toLowerCase();
+  return `${id}::${where}`;
+}
+
+export function parseFindings(rawList) {
+  if (!Array.isArray(rawList)) {
+    throw new Error('input must be a JSON array of findings');
+  }
+
+  const seen = new Map();
+  for (const raw of rawList) {
+    const finding = { ...raw, severity: normalizeSeverity(raw.severity) };
+    const key = dedupKey(finding);
+    if (!seen.has(key)) {
+      seen.set(key, finding);
+    } else {
+      // Keep the higher severity when duplicates disagree.
+      const existing = seen.get(key);
+      if (SEVERITY_RANK[finding.severity] < SEVERITY_RANK[existing.severity]) {
+        seen.set(key, finding);
+      }
+    }
+  }
+
+  const findings = [...seen.values()].sort((a, b) => {
+    const d = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+    if (d !== 0) return d;
+    return String(a.id ?? '').localeCompare(String(b.id ?? ''));
+  });
+
+  const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
+  for (const f of findings) bySeverity[f.severity] += 1;
+
+  return { total: rawList.length, deduped: findings.length, bySeverity, findings };
+}
+
+function run(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    console.error('✗ invalid JSON input');
+    process.exit(1);
+  }
+  try {
+    const result = parseFindings(parsed);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function selftest() {
+  const raw = [
+    { id: 'CVE-1', package: 'lodash@4.17.15', severity: 'high' },
+    { id: 'CVE-1', package: 'lodash@4.17.15', severity: 'medium' }, // dup, lower sev
+    { id: 'CVE-2', package: 'axios@0.21.0', severity: 'CRITICAL' },  // case-insensitive
+    { id: 'CVE-3', package: 'jest@29', severity: 'low' },
+    { id: 'SECRET-1', location: 'config/x.env', severity: 'critical' },
+    { id: 'CVE-4', package: 'debug@4', severity: 'weird' },          // -> info
+  ];
+
+  const result = parseFindings(raw);
+  const checks = [];
+
+  // Dedup: 6 raw -> 5 unique (the two CVE-1 collapse).
+  checks.push(['dedupes duplicates', result.total === 6 && result.deduped === 5]);
+
+  // Duplicate keeps the higher severity (high, not medium).
+  const cve1 = result.findings.find((f) => f.id === 'CVE-1');
+  checks.push(['dup keeps higher severity', cve1 && cve1.severity === 'high']);
+
+  // Severity counts after normalization.
+  checks.push(['critical count is 2', result.bySeverity.critical === 2]);
+  checks.push(['high count is 1', result.bySeverity.high === 1]);
+  checks.push(['unknown severity -> info', result.bySeverity.info === 1]);
+
+  // Sort order: criticals first, info last.
+  const order = result.findings.map((f) => f.severity);
+  const sorted = [...order].sort(
+    (a, b) => SEVERITY_RANK[a] - SEVERITY_RANK[b]
+  );
+  checks.push(['sorted by severity', JSON.stringify(order) === JSON.stringify(sorted)]);
+  checks.push(['first finding is critical', order[0] === 'critical']);
+  checks.push(['last finding is info', order[order.length - 1] === 'info']);
+
+  let ok = true;
+  for (const [label, passed] of checks) {
+    console.log(`${passed ? '✓' : '✗'} ${label}`);
+    ok &&= passed;
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  const { readFileSync } = await import('node:fs');
+  run(readFileSync(arg, 'utf8'));
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => run(buf));
+}

package/catalog/packs/code-review-pack/PACK.md

@@ -0,0 +1,100 @@
+---
+name: code-review-pack
+description: Review pull requests faster and better — automated first-pass review, PR summaries reviewers can trust, healthy git workflow settings, conventional history, and query-performance checks, sequenced into one review pipeline.
+type: pack
+version: 1.0.0
+updated: 2026-07-10
+agents: [code-reviewer, pr-summarizer]
+skills: [git-collaboration-workflows, conventional-commits, sql-index-tuning]
+---
+# Code Review Pack
+
+The review toolkit for teams whose bottleneck is the pull-request queue: get every PR a
+fast, rigorous first pass, give human reviewers a summary they can trust, and keep the
+workflow settings and history hygiene that make review scale. The value of the pack is the
+**sequence** — which item runs at which moment of a PR's life — not the item list.
+
+## Who this is for
+
+Teams merging more PRs than their senior reviewers can deeply read; leads who want review
+latency down without review quality collapsing; anyone inheriting a repo where "review"
+means LGTM-stamping.
+
+## What's included
+
+- **Agents:** `code-reviewer` (rigorous first-pass review: correctness, security, tests,
+  maintainability), `pr-summarizer` (what changed, why, risk areas — the reviewer's map).
+- **Skills:** `git-collaboration-workflows` (branch protection, PR sizing, merge strategy,
+  monorepo questions), `conventional-commits` (machine-readable history that powers
+  changelogs and bisect), `sql-index-tuning` (the query-performance review lens most teams
+  lack — N+1s and missing indexes are the top silent regressions PRs ship).
+
+## The review pipeline (how the pieces sequence)
+
+```text
+PR opened
+  1. pr-summarizer     → posts the map: what changed, why, blast radius, files to read first
+  2. code-reviewer     → first-pass findings: blocking / question / nit, with file:line
+       └─ SQL touched? → sql-index-tuning lens: EXPLAIN the new queries, check indexes
+  3. human reviewer    → reads the summary + findings, spends attention ONLY on judgment
+                         calls the machine flagged and the design questions it can't make
+merge
+  4. conventional-commits → squash message feeds changelog + bisect-friendly history
+weekly
+  5. git-collaboration-workflows → hygiene audit: branch age, PR size trend, protection drift
+```
+
+The division of labor is the point: agents do coverage (every line, every time), humans do
+judgment (architecture, product fit, taste). Teams that flip this — humans doing coverage,
+no machine pass — get slow reviews AND missed bugs.
+
+## Setup
+
+1. Install the pack; wire `pr-summarizer` + `code-reviewer` to run on PR-open (CI job or
+   scheduled agent).
+2. Apply the branch-protection settings from `git-collaboration-workflows`
+   (`examples/branch-protection.md`) — required checks, stale-review dismissal, squash-only.
+3. Adopt the `blocking:/q:/nit:` comment convention from the PR review playbook; announce
+   the review SLO (first response < 4h).
+4. Enable commit-lint per `conventional-commits` so the history contract is enforced, not
+   hoped for.
+
+## Comment convention (adopt verbatim)
+
+```text
+blocking:  must be fixed before merge — correctness, security, data loss
+q:         genuine question; answer may resolve it
+nit:       author's call; NEVER blocks
+(unprefixed comments read as blocking — prefix everything)
+```
+
+## Pitfalls
+
+- **LGTM-stamping past machine findings** — the pipeline's failure mode; blocking findings
+  must actually block, or reverts won't move.
+- **Bot-nit fatigue** — untuned severity turns the first-pass reviewer into noise; demote
+  misfiring rules weekly during rollout (see `references/rollout-guide.md`).
+- **Summaries as gospel on giant PRs** — a wrong map on a 2,000-line PR is an argument for
+  the size norms, not against the mapper.
+- **Skipping the SQL lens** — missing-index regressions pass every test and fail at the
+  10× tenant; the `EXPLAIN` step is not optional when queries change.
+- **Anti-pattern: humans doing coverage** — re-reading every line the machine read wastes
+  the scarce resource (judgment) on the abundant one (attention).
+
+## When NOT to use this shape
+
+Solo projects (review theater), and rubber-stamp compliance environments where findings
+can't block merges anyway — fix the process authority first, then install tooling.
+Edge case worth naming: generated code and vendored files should be excluded from both
+summary and review scope up front, or they drown every real finding.
+
+## Verification
+
+After two weeks, three numbers should move: median time-to-first-review (down), PR size p50
+(down — the summary+size norms push authors to split), and post-merge defect
+reverts (down). If reverts didn't move, check whether `code-reviewer` findings are being
+LGTM'd past — the pipeline only works when blocking findings block. A full worked PR
+walkthrough lives in [examples/pr-flow-example.md](examples/pr-flow-example.md).
+
+Pairs with the `secure-delivery-pack` (security-focused review lenses) and
+`craftsmanship-pack` (refactoring and test depth beyond the review gate).

package/catalog/packs/code-review-pack/examples/pr-flow-example.md

@@ -0,0 +1,50 @@
+# Worked Example — one PR through the pipeline
+
+PR #512: "Add invoice CSV export" — 380 lines, touches API + a new query + one UI table.
+
+## 1. pr-summarizer posts (2 min after open)
+
+> **What**: New `GET /invoices/export.csv` endpoint (streaming), export button on the
+> invoices table, `invoices_export` permission.
+> **Why**: FEAT-201 — finance team needs monthly exports.
+> **Read first**: `export-controller.ts` (new query!), `permissions.ts` (auth change).
+> **Blast radius**: read-only endpoint; new DB query on `invoices` (potentially large);
+> no schema change. **Risk**: memory on large exports, query performance.
+
+## 2. code-reviewer posts (5 min after open)
+
+> `blocking:` export-controller.ts:41 — query selects `*` and loads all rows into memory
+> before streaming; a 500k-invoice tenant OOMs the pod. Stream with a cursor
+> (keyset pagination) or use the DB driver's row stream.
+>
+> `blocking:` export-query.sql — `WHERE tenant_id = ? AND created_at > ?` has no
+> supporting composite index (per sql-index-tuning: needs `(tenant_id, created_at)`;
+> current plan is a seq scan at 2M rows — EXPLAIN attached).
+>
+> `q:` permissions.ts:88 — `invoices_export` granted to `member` by default; FEAT-201
+> says finance-only. Intended?
+>
+> `nit:` csv column headers hardcoded English — project is i18n'd (`internationalization`).
+
+## 3. Human reviewer (18 min later, reads summary + findings first)
+
+Spends attention on the two judgment calls: confirms permission should be finance-only
+(product check), and decides streaming approach (driver row-stream over keyset — simpler
+here). Doesn't re-read the 300 lines the machine already covered line-by-line; spot-checks
+the test file.
+
+## 4. Author revises → checks green → squash-merge
+
+```text
+feat(invoices): add streaming CSV export (FEAT-201)
+
+Finance-only permission; keyset-cursor streaming; composite index
+(tenant_id, created_at) added expand-only.
+```
+
+## Outcome ledger
+
+- OOM prevented pre-merge (would have been a Sev-2 at month-end).
+- Missing index caught before it met the 2M-row tenant.
+- Human review time: ~20 min for a 380-line PR, spent entirely on judgment.
+- History entry supports changelog + bisect.

package/catalog/packs/code-review-pack/references/rollout-guide.md

@@ -0,0 +1,40 @@
+# Rollout Guide
+
+Review culture changes fail when imposed all at once. The two-week sequence that lands:
+
+## Week 1 — observation mode
+
+- Wire `pr-summarizer` only. Zero friction, immediate value: every PR gets a map. Nobody
+  argues with a summary.
+- Run `code-reviewer` in **comment-only** mode (findings posted, nothing blocks). The team
+  calibrates trust: are the findings real? (Tune severity thresholds now, while stakes are
+  low.)
+- Baseline the three metrics: time-to-first-review, PR size p50, revert rate. You need the
+  "before" or the "after" is a vibe.
+
+## Week 2 — the contract
+
+- Turn on branch protection per the skill's settings (checks required, stale-dismissal,
+  squash-only). Announce it as config, with the escape hatch documented (hotfix label path).
+- Adopt comment prefixes (`blocking:/q:/nit:`) and the 4-hour first-response SLO — put the
+  SLO on a dashboard where standup sees it.
+- commit-lint on (warning for 3 days, then required).
+
+## Weeks 3+ — enforcement earned
+
+- `code-reviewer` blocking findings now actually block (the team has seen two weeks of its
+  judgment; false-positive rate is known and tuned).
+- Weekly hygiene audit (`check-branch-hygiene.mjs`) posted to the team channel — trends,
+  not blame.
+
+## Objection handling (you will hear these)
+
+- **"The bot nitpicks."** Nits never block — that's what the prefix system encodes. Tune or
+  demote rules that misfire; the config is code-reviewable.
+- **"Summaries are wrong sometimes."** They're maps, not territory — a wrong summary on a
+  2,000-line PR is an argument for smaller PRs, which the size norms fix.
+- **"This slows us down."** The SLO + protection settings measurably speed up the queue;
+  show the week-1 baseline vs week-4. What slows teams is review latency and re-review
+  churn, both of which drop.
+- **"Admins need bypass."** The bypass IS the vulnerability; the hotfix path exists and is
+  faster than arguing at 2 a.m.

package/catalog/packs/security-pack/PACK.md

@@ -0,0 +1,128 @@
+---
+name: security-pack
+description: Build and ship secure software — threat modeling at design time, OWASP code audits, dependency/secret scanning, and secure auth and secrets handling, sequenced into one shift-left workflow.
+type: pack
+version: 2.0.0
+updated: 2026-07-06
+agents: [threat-modeler, security-auditor, vuln-scanner]
+skills: [owasp-top10, secure-auth, secrets-management]
+---
+# Security Pack
+
+Security is cheapest when it moves **left** — designed in at the whiteboard, enforced while the code
+is written, verified before merge, and monitored in the supply chain. This pack bundles three agents
+and three skills that cover that whole arc and, more importantly, teaches **which one to reach for at
+each stage of a feature's life**.
+
+The value of a pack is not the list of items — it is the sequencing. A threat model with no audit is
+a document nobody enforces; an audit with no threat model is a checklist with no context. This
+document ties them into one repeatable loop: **model → build → audit → scan → ship**.
+
+## Who this is for
+
+- Security engineers who own the security posture of a product or service.
+- Developers who own the security of the features they build — the ones expected to threat-model,
+  self-audit, and keep their dependencies clean before asking for review.
+- Tech leads introducing a shift-left practice to a team that currently bolts security on at the end.
+
+If you only need a one-off review of an existing diff, the `security-auditor` agent alone is enough.
+Reach for the full pack when you are carrying a feature **from design through to a clean merge** and
+want security enforced at every handoff instead of a single gate at the finish line.
+
+## What's included
+
+| Item | Kind | Job in the workflow |
+|---|---|---|
+| `threat-modeler` | agent | STRIDE-style threat modeling at design time — enumerate attack surface, trust boundaries, and abuse cases before code exists |
+| `security-auditor` | agent | OWASP-focused code review of the diff — injection, auth flaws, broken access control, unsafe crypto |
+| `vuln-scanner` | agent | Dependency CVE scanning and secret detection across the tree and git history |
+| `owasp-top10` | skill | Per-risk defenses for the OWASP Top 10 — the reference the auditor and you apply |
+| `secure-auth` | skill | Correct password hashing, session/token handling, and MFA construction |
+| `secrets-management` | skill | Keep secrets out of source, load them safely, and rotate without downtime |
+
+Agents *do* the work; skills are the *reference* they (and you) apply while doing it. Pair an agent
+with its matching skill — `security-auditor` + `owasp-top10`, or building auth with `secure-auth` —
+so the output is both produced and grounded in a standard.
+
+## The end-to-end workflow
+
+A secure feature moves through five stages. The pack maps one primary item to each:
+
+```text
+1. Model   → threat-modeler   (+ owasp-top10)        enumerate threats before code
+2. Build   → secure-auth / secrets-management        implement the risky parts correctly
+3. Audit   → security-auditor (+ owasp-top10)        review the diff, security-first
+4. Scan    → vuln-scanner                            CVEs in deps + secrets in the tree
+5. Ship    → gate on: no open CRITICAL/HIGH, clean scan
+```
+
+Model **first**, before any code. A threat model produced after the feature is built is a
+rationalization, not a design tool — its whole purpose is to change what you build. The threats it
+surfaces become the audit checklist in stage 3 and the abuse-case tests you write while building.
+
+### Worked example: adding "password reset via email link"
+
+```text
+threat-modeler   → surfaces: token guessability, token reuse/replay, host-header poisoning in the
+                   reset link, user enumeration on the "email sent" response, rate-limit bypass
+owasp-top10      → maps those to A01 (access control), A07 (auth failures), A04 (insecure design)
+secure-auth      → reset token = 256-bit random, single-use, 15-min TTL, hashed at rest; response is
+                   identical whether or not the email exists (no enumeration)
+secrets-management → the email-provider API key is loaded from the secret store, never in the repo
+security-auditor → confirms token is compared in constant time, is invalidated on use, and the
+                   "sent" response leaks nothing; flags the missing rate limit as HIGH
+vuln-scanner     → the email SDK pulls a transitive dep with a known SSRF CVE — flagged, bump required
+```
+
+Every item earned its place: the threat model set the agenda, the skills shaped the implementation,
+the auditor verified it, and the scanner caught a supply-chain issue no human review would have.
+
+## How to choose the right item
+
+- **Designing a feature that touches auth, money, or user data?** `threat-modeler` + `owasp-top10`
+  first — enumerate abuse cases before a line is written.
+- **Implementing login, sessions, or MFA?** `secure-auth` — do not hand-roll password hashing or
+  token generation.
+- **About to reference a credential, key, or token?** `secrets-management` — it never belongs in
+  source, config committed to git, or a client bundle.
+- **Diff ready for review?** `security-auditor` — security pass before correctness, every time.
+- **Before merge, always?** `vuln-scanner` — CVEs and leaked secrets are invisible to code review.
+
+See `references/choosing-the-right-tool.md` for the full decision table, `references/workflow.md` for
+the stage-by-stage playbook, and `references/threat-model-to-remediation.md` for the discipline
+playbook that connects a threat model to concrete fixes. Two complete runs are in `examples/`.
+
+## Common pitfalls (anti-patterns this pack prevents)
+
+- **Threat-modeling after the build.** A model written to justify existing code enumerates the
+  threats you already handled and misses the ones you didn't. The workflow puts it at stage 1 so it
+  can actually change the design.
+- **Auditing without a threat model.** A generic OWASP checklist misses domain abuse cases (e.g. a
+  refund flow that can go negative). The threat model *is* the audit's context.
+- **Treating secret scanning as one-time.** A secret committed once lives in git history forever even
+  after it's deleted from HEAD. `vuln-scanner` checks history, and the fix is rotation, not just
+  removal.
+- **Rolling your own crypto/auth.** Hand-rolled password hashing, JWT verification, or token
+  comparison is a reliable source of criticals. `secure-auth` points to vetted constructions.
+- **Fixing the secret, forgetting to rotate.** Deleting a leaked key from source does not un-leak it.
+  Any exposed secret must be rotated, not just removed.
+
+## When NOT to use this pack
+
+- **Compliance/audit-trail work** (GDPR, SOC 2 evidence) — that's `compliance-auditor` and the
+  privacy/audit-logging skills, not this pack's application-security focus.
+- **Infrastructure and network hardening** — firewall rules, TLS termination, and cloud IAM are
+  DevOps/network territory, not application-code security.
+- **A one-line, no-risk change** — a copy tweak or a CSS fix does not need a threat model; a single
+  `security-auditor` pass (or nothing) is proportionate.
+- **Smart-contract security** — use `smart-contract-auditor` and `smart-contract-security`; the
+  threat surface there is different.
+
+## Files in this package
+
+- `references/workflow.md` — the five-stage security workflow in detail, with entry/exit criteria.
+- `references/choosing-the-right-tool.md` — full decision table: symptom → item.
+- `references/threat-model-to-remediation.md` — the discipline playbook connecting STRIDE threats to
+  audited, tested remediations.
+- `examples/threat-model-then-audit.md` — a feature threat-modeled at design time, then audited.
+- `examples/owasp-vuln-triage-and-fix.md` — an OWASP-class vulnerability triaged and remediated.

package/catalog/packs/security-pack/examples/owasp-vuln-triage-and-fix.md

@@ -0,0 +1,66 @@
+# Walkthrough: triaging and fixing an OWASP-class vulnerability
+
+Not every task starts at design time. This shows the pack applied to a vulnerability found in
+existing code — where `security-auditor` leads and the workflow compresses.
+
+## The finding
+
+A routine `security-auditor` pass on a diff flags:
+
+```md
+### CRITICAL
+- `api/documents.js:73` — GET /documents/:id loads the record by id and returns it with no check
+  that the document belongs to the requesting user. Any authenticated user can read any document by
+  guessing/enumerating ids. (A01 Broken Access Control — IDOR)
+```
+
+Intermittent guessing isn't needed — the ids are sequential integers, so this is trivially
+enumerable. CRITICAL is correct.
+
+## Classify (`owasp-top10`)
+
+This is **A01 Broken Access Control**, the IDOR variant: the endpoint authenticates ("are you logged
+in?") but does not authorize ("is this *your* document?"). The reference is clear — authorization must
+be checked server-side against the resource owner on every request, deny-by-default.
+
+## Reproduce as a failing test first (`security-auditor` direction)
+
+Before touching the handler, lock the bug down as a regression test:
+
+```text
+✗ user B requesting user A's document id receives 404, not 200 + the document
+```
+
+It fails against current code — confirming the vulnerability and giving the fix a target. (404, not
+403, so the endpoint doesn't confirm the id exists — avoids the enumeration side channel too.)
+
+## Fix the access-control check
+
+Add the ownership guard *before* the record is returned:
+
+```text
+const doc = await Documents.findById(id);
+if (!doc || doc.ownerId !== session.userId) return res.status(404).end();
+return res.json({ data: doc, error: null });
+```
+
+The check runs for every request and denies by default. Test goes green. A grep for the same pattern
+across sibling routes (`/documents/:id/download`, `/documents/:id/versions`) confirms whether the same
+gap exists elsewhere — IDOR is rarely a single-endpoint problem.
+
+## Re-audit + scan (`security-auditor` + `vuln-scanner`)
+
+- `security-auditor` re-reviews: the guard is present on all three routes, the 404 leaks nothing, no
+  new finding introduced.
+- `vuln-scanner` runs on the branch: dependencies clean, no secret introduced by the change.
+
+## Ship
+
+CRITICAL closed, sibling routes patched, regression tests in place, scan clean. The fix ships.
+
+## The lesson
+
+The pack turned a single flagged line into a *class* fix: classify the vulnerability (A01/IDOR), lock
+it with a failing test, apply the deny-by-default mitigation, then sweep for the same pattern
+elsewhere. Fixing only line 73 would have left the download and versions routes exploitable — the
+OWASP framing is what prompts checking the whole class, not just the reported instance.

package/catalog/packs/security-pack/examples/threat-model-then-audit.md

@@ -0,0 +1,77 @@
+# Walkthrough: threat-modeling "password reset via email", then auditing it
+
+A complete run through the five stages for a classic high-risk feature, showing which pack item leads
+at each point.
+
+## Stage 1 — Model (`threat-modeler` + `owasp-top10`)
+
+Trust boundaries: browser → API → email provider → token store. Walking STRIDE surfaces:
+
+```text
+- Token guessability      → tokens must be cryptographically random (A07)
+- Token reuse / replay     → single-use, short TTL, invalidated on use (A07)
+- Host-header poisoning    → reset link host must not come from the request header (A04)
+- User enumeration         → "email sent" response identical for known/unknown emails (A01)
+- No rate limit            → attacker can brute-force or spam resets (A04/A07)
+```
+
+Each threat is tagged with its OWASP class and a planned mitigation. This list becomes the audit
+agenda.
+
+## Stage 2 — Build (`secure-auth` + `secrets-management`)
+
+Implement against the vetted construction:
+
+- Reset token = 256-bit CSPRNG value, stored **hashed** at rest, single-use, 15-minute TTL.
+- The "we sent you an email" response is byte-identical whether or not the account exists.
+- The reset link's host is built from server config, not the incoming `Host` header.
+- The email-provider API key is loaded from the secret store via `secrets-management` — it never
+  appears in source or committed config.
+
+Abuse-case tests are written alongside:
+
+```text
+✗ a used reset token cannot be redeemed a second time
+✗ /forgot-password returns the same body for known and unknown emails
+✗ /forgot-password returns 429 after 5 attempts in the window
+```
+
+Implement until green.
+
+## Stage 3 — Audit (`security-auditor` + `owasp-top10`)
+
+The auditor reviews the diff against the stage-1 list:
+
+```md
+### HIGH
+- `auth/reset.js:41` — token compared with `===`; use a constant-time compare to avoid a timing
+  oracle on the token value.
+- `auth/reset.js:12` — no rate limiter on the request-reset endpoint (threat listed in the model,
+  not yet implemented). Add per-IP + per-account throttling.
+
+### LOW
+- `auth/reset.js:58` — TTL is 60 min; model called for 15. Tighten.
+```
+
+The timing-compare and rate-limit findings are fixed and re-reviewed. No CRITICAL/HIGH remains.
+
+## Stage 4 — Scan (`vuln-scanner`)
+
+```text
+CVE: email-sdk@2.3.0 → transitive dep `node-fetch@2.6.1` has a known SSRF advisory.
+     Fix: bump to email-sdk@2.4.1 (pulls patched fetch).
+Secrets: none in tree; git history clean.
+```
+
+Dependency bumped; scan re-run clean.
+
+## Stage 5 — Ship
+
+Audit clean, scan clean, no committed secret. The feature ships with its abuse-case tests as
+permanent regression guards.
+
+## The lesson
+
+The threat model did the heavy lifting: it predicted the rate-limit gap and the enumeration risk
+*before* code existed, and it gave the auditor a precise agenda. Without it, stage 3 would have been a
+generic pass that could easily have missed the missing rate limiter.