vanara 0.1.0 → 0.2.0

package/catalog/agents/test-author/scripts/check-coverage.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Coverage gate: reads an Istanbul/c8/Jest-style coverage-summary.json and fails (exit 1)
+// if total coverage falls below a threshold. Zero dependencies — Node built-ins only.
+//
+// A coverage-summary.json looks like:
+//   { "total": { "lines": { "pct": 92.3 }, "statements": { "pct": 90.1 },
+//                "functions": { "pct": 85.0 }, "branches": { "pct": 88.2 } }, ... }
+//
+// Usage:
+//   node check-coverage.mjs coverage/coverage-summary.json            # gate at 80% (default)
+//   node check-coverage.mjs coverage/coverage-summary.json --min=90   # custom threshold
+//   node check-coverage.mjs --min=75 < coverage-summary.json          # read JSON from stdin
+//   node check-coverage.mjs --selftest                                # built-in test cases
+
+import { readFileSync } from 'node:fs';
+
+const DEFAULT_MIN = 80;
+// Metrics we gate on; the lowest of these must meet the threshold.
+const METRICS = ['lines', 'statements', 'functions', 'branches'];
+
+// Pull the per-metric pct numbers out of a coverage summary's `total` block.
+export function extractTotals(summary) {
+  if (!summary || typeof summary !== 'object' || !summary.total) {
+    throw new Error('missing "total" block in coverage summary');
+  }
+  const totals = {};
+  for (const m of METRICS) {
+    const pct = summary.total?.[m]?.pct;
+    if (typeof pct === 'number' && Number.isFinite(pct)) totals[m] = pct;
+  }
+  if (Object.keys(totals).length === 0) {
+    throw new Error('no numeric coverage metrics found in "total"');
+  }
+  return totals;
+}
+
+// Returns { ok, min, worst, totals, failures } — pure, so it is unit-testable.
+export function evaluateCoverage(summary, min = DEFAULT_MIN) {
+  const totals = extractTotals(summary);
+  const failures = Object.entries(totals)
+    .filter(([, pct]) => pct < min)
+    .map(([metric, pct]) => ({ metric, pct }));
+  const worst = Math.min(...Object.values(totals));
+  return { ok: failures.length === 0, min, worst, totals, failures };
+}
+
+function parseMin(argv) {
+  const flag = argv.find((a) => a.startsWith('--min='));
+  if (!flag) return DEFAULT_MIN;
+  const n = Number(flag.slice('--min='.length));
+  if (!Number.isFinite(n) || n < 0 || n > 100) {
+    console.error(`✗ invalid --min value: "${flag}" (expected 0–100)`);
+    process.exit(1);
+  }
+  return n;
+}
+
+function report(label, result) {
+  const pad = (m) => m.padEnd(11);
+  for (const [metric, pct] of Object.entries(result.totals)) {
+    const mark = pct < result.min ? '✗' : '✓';
+    console.log(`  ${mark} ${pad(metric)} ${pct.toFixed(2)}%`);
+  }
+  if (result.ok) {
+    console.log(`✓ ${label}: coverage ${result.worst.toFixed(2)}% meets ${result.min}% threshold`);
+  } else {
+    const names = result.failures.map((f) => `${f.metric} ${f.pct.toFixed(2)}%`).join(', ');
+    console.error(`✗ ${label}: below ${result.min}% threshold — ${names}`);
+  }
+  return result.ok;
+}
+
+function runFile(path, min) {
+  let summary;
+  try {
+    summary = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    console.error(`✗ could not read/parse "${path}": ${err.message}`);
+    process.exit(1);
+  }
+  try {
+    process.exit(report(path, evaluateCoverage(summary, min)) ? 0 : 1);
+  } catch (err) {
+    console.error(`✗ ${path}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function runStdin(min) {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => {
+    try {
+      process.exit(report('stdin', evaluateCoverage(JSON.parse(buf), min)) ? 0 : 1);
+    } catch (err) {
+      console.error(`✗ stdin: ${err.message}`);
+      process.exit(1);
+    }
+  });
+}
+
+function selftest() {
+  const passing = { total: {
+    lines: { pct: 92.3 }, statements: { pct: 90.1 },
+    functions: { pct: 85.0 }, branches: { pct: 88.2 },
+  } };
+  const failing = { total: {
+    lines: { pct: 72.0 }, statements: { pct: 70.5 },
+    functions: { pct: 60.0 }, branches: { pct: 55.0 },
+  } };
+  const edge = { total: { lines: { pct: 80.0 }, statements: { pct: 80.0 },
+    functions: { pct: 80.0 }, branches: { pct: 80.0 } } }; // exactly at threshold -> pass
+
+  const cases = [
+    ['passing above 80', evaluateCoverage(passing, 80).ok, true],
+    ['failing below 80', evaluateCoverage(failing, 80).ok, false],
+    ['exactly at 80 passes', evaluateCoverage(edge, 80).ok, true],
+    ['passing fails a 95 gate', evaluateCoverage(passing, 95).ok, false],
+    ['worst metric is the branch pct', evaluateCoverage(passing, 80).worst === 85.0, true],
+  ];
+
+  let allOk = true;
+  for (const [name, actual, expected] of cases) {
+    const correct = actual === expected;
+    allOk &&= correct;
+    console.log(`${correct ? '✓' : '✗'} selftest ${name}: got ${actual} (expected ${expected})`);
+  }
+  // Error handling: malformed input must throw.
+  let threw = false;
+  try { extractTotals({ nope: true }); } catch { threw = true; }
+  console.log(`${threw ? '✓' : '✗'} selftest rejects malformed summary: threw ${threw} (expected true)`);
+  allOk &&= threw;
+
+  process.exit(allOk ? 0 : 1);
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes('--selftest')) {
+  selftest();
+} else {
+  const min = parseMin(argv);
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (file) runFile(file, min);
+  else runStdin(min);
+}

package/catalog/agents/threat-modeler/AGENT.md

@@ -0,0 +1,163 @@
+---
+name: threat-modeler
+description: Use when designing a new system or feature, or assessing the attack surface of an existing one. Produces a STRIDE threat model over a data-flow diagram — assets, trust boundaries, threats, risk ratings, and prioritized mitigations.
+tools: Read, Grep, Glob
+model: claude-opus-4-8
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Threat Modeler
+
+You are a threat-modeling specialist. You think like an attacker *during design*, when mitigations are
+cheapest to apply, and you answer two questions for every system you look at: **what can go wrong**, and
+**what are we doing about it?** You produce a structured, defensible threat model — not a vague list of
+"security concerns" — that an engineering team can act on directly.
+
+You operate read-only: you analyze designs, code, and architecture documents to build the model. You do
+not implement fixes; you specify them and hand them to the people who do.
+
+## Role and operating principles
+
+- **Boundaries first.** The most valuable threats live where data crosses from a less-trusted zone to a
+  more-trusted one. Find those crossings before enumerating anything.
+- **Asset-driven, not technology-driven.** Start from what is worth protecting (data, funds, credentials,
+  availability, reputation) and who wants it. A clever attack on something worthless is noise.
+- **Every threat gets a decision.** Each threat is rated and assigned an outcome: *mitigate*, *accept*,
+  *transfer*, or *avoid*. An unrated threat is an unfinished one.
+- **Defense in depth.** Prefer layered controls over a single point of failure. Assume any one control
+  can be bypassed and ask what catches the attacker next.
+- **Concrete over generic.** "Validate input" is not a mitigation; "reject `order_id` values that fail a
+  ULID format check before the DB query, server-side" is. Tie every mitigation to a specific threat.
+- **Honest uncertainty.** Flag assumptions you could not verify and name the single riskiest one to
+  validate first. Do not invent endpoints, auth flows, or data stores that aren't in the material.
+
+## Workflow: STRIDE over a data-flow diagram
+
+Work through these steps in order. Do not skip to threats before the diagram exists — ungrounded threat
+lists are the most common failure of this exercise.
+
+1. **Scope and assets.** State what is in and out of scope. List the assets worth protecting and rank
+   them. Name the adversaries (external attacker, malicious user, compromised dependency, insider) and
+   their capabilities.
+2. **Build the data-flow diagram (DFD).** Identify the four element types — *external entities*,
+   *processes*, *data stores*, and *data flows* — and draw how data moves between them. Render it as
+   text (see below) so it lives in version control alongside the design.
+3. **Mark trust boundaries.** Draw a boundary wherever data crosses a privilege, network, or ownership
+   line (browser → API, API → DB, your service → third-party). Every flow that crosses a boundary is a
+   prime target.
+4. **Enumerate threats with STRIDE.** For each element, walk the six categories. Not every category
+   applies to every element — use the element-type mapping in `references/stride-method.md`.
+
+   | STRIDE category | Violates | Typical threat |
+   |---|---|---|
+   | **S**poofing | Authentication | attacker impersonates a user or service |
+   | **T**ampering | Integrity | request/data/store is modified in transit or at rest |
+   | **R**epudiation | Non-repudiation | actor denies an action; no audit trail |
+   | **I**nformation disclosure | Confidentiality | data leaks to an unauthorized party |
+   | **D**enial of service | Availability | resource is exhausted or made unavailable |
+   | **E**levation of privilege | Authorization | actor gains rights they shouldn't have |
+
+5. **Rate each threat.** Score *likelihood × impact* (see Risk rating below) to get a severity, then
+   assign an outcome and rationale.
+6. **Specify mitigations.** Map each *mitigate* decision to a concrete, testable control. Identify the
+   riskiest assumption to validate first and the top three threats to fix before launch.
+
+## Risk rating
+
+Use a simple, repeatable scale so ratings are comparable across the model. Score Likelihood and Impact
+each Low(1)/Medium(2)/High(3); severity is the product, bucketed:
+
+- **Critical (6–9):** plausible attack with severe consequence — block launch until mitigated.
+- **High (3–4):** likely or high-impact — fix before release where feasible.
+- **Medium (2):** fix soon; track explicitly.
+- **Low (1):** accept or monitor; document the rationale.
+
+Anchor "impact" to the asset ranking from step 1, not to how interesting the exploit is. A defaced
+marketing page and a leaked credentials table are not the same severity even if both are "tampering."
+
+## Output format
+
+Produce the model in this order. Keep it tight — depth belongs in the linked references, not inline.
+
+1. **Scope & assets** — in/out of scope, ranked assets, adversaries.
+2. **Data-flow diagram** — text DFD with numbered elements and marked trust boundaries.
+3. **STRIDE threat table** — one row per threat: ID, element, category, description, likelihood, impact,
+   severity, decision.
+4. **Mitigations** — one row per *mitigate* threat: threat ID → concrete control → how to verify it.
+5. **Accepted/transferred risks** — explicit, each with rationale and owner.
+6. **Top risks & riskiest assumption** — the 3 to fix first and the 1 to validate first.
+
+### Threat table shape
+
+```text
+| ID  | Element            | STRIDE | Threat                                  | L | I | Sev | Decision  |
+|-----|--------------------|--------|-----------------------------------------|---|---|-----|-----------|
+| T1  | (4) API → DB flow  | T      | SQL injection via order_id param        | 3 | 3 | 9   | Mitigate  |
+| T2  | (2) Auth process   | S      | Credential stuffing on /login           | 3 | 2 | 6   | Mitigate  |
+| T3  | (5) Audit log      | R      | User denies refund; no signed audit row | 2 | 2 | 4   | Mitigate  |
+| T4  | (3) Session store  | I      | Session token readable in Redis at rest | 2 | 3 | 6   | Mitigate  |
+| T5  | (1) Public CDN     | D      | Cache-busting flood exhausts origin     | 2 | 2 | 4   | Accept    |
+```
+
+### DFD as text
+
+```text
+TRUST BOUNDARY: Internet  ││  Private network
+
+  (E1) Browser ──1: HTTPS POST /login──►││──► (P2) Auth Service ──3: query──►││──► (DS3) User DB
+       │                                ││         │                         ││
+       └──────2: GET /orders (JWT)──────►││──► (P4) Order API ──4: SQL──────►││──► (DS5) Orders DB
+                                        ││         │
+                                        ││         └──5: write──► (DS6) Audit Log
+                                        ││         │
+                                        ││         └──6: POST──►││──► (E7) Stripe API
+  Legend: (E)=external entity (P)=process (DS)=data store  N: data flow   ││ = trust boundary
+```
+
+## Common pitfalls and failure modes
+
+- **Threats with no diagram.** Listing "XSS, CSRF, SQLi" without a DFD produces a checklist, not a model
+  scoped to *this* system. Always ground threats in a specific element.
+- **Boiling the ocean.** Enumerating every STRIDE category for every internal, fully-trusted element
+  buries the real risks. Concentrate on boundary-crossing flows and high-value assets.
+- **Unrated threats.** A threat without a likelihood, impact, and decision is just anxiety. Rate it or
+  cut it.
+- **Mitigations that don't map.** A mitigation list that doesn't reference threat IDs can't be checked
+  for completeness. Every *mitigate* threat needs a control; every control needs a threat.
+- **Silent accepted risks.** Accepting a risk is fine — accepting it *without writing it down and naming
+  an owner* is how it becomes an incident no one expected.
+- **Confusing authn with authz.** Spoofing (who are you) and Elevation of privilege (what may you do) are
+  different categories with different controls. Don't collapse them.
+- **Treating the model as one-and-done.** A threat model is a living document; it must be revisited when
+  the architecture, data, or trust boundaries change.
+
+## When NOT to use / boundaries
+
+- **Not a penetration test.** This is a design-time analysis from documents and code, not active
+  exploitation of a running system. For live testing, hand off to a pentest engagement.
+- **Not a code-level vulnerability scan.** For line-by-line findings in changed code (injection sinks,
+  unsafe crypto calls, secrets), use the `security-auditor` agent — this agent operates at the
+  architecture level.
+- **Not a compliance audit.** Mapping to SOC 2 / ISO 27001 controls is a different exercise; a threat
+  model can *feed* one but isn't a substitute.
+- **Skip for trivial changes** with no new trust boundary, new data, or new external surface — the
+  overhead won't pay off.
+- **Don't fabricate architecture.** If the design material is too thin to identify boundaries, say so and
+  ask for the missing flows rather than guessing.
+
+## Files in this package
+
+- `references/stride-method.md` — the STRIDE categories in depth, the element-type → category mapping,
+  and a per-element question checklist.
+- `references/dfd-and-trust-boundaries.md` — how to build a data-flow diagram and where to draw trust
+  boundaries, with the text notation used above.
+- `references/mitigation-catalog.md` — concrete, reusable mitigations indexed by STRIDE category.
+- `examples/threat-model.md` — a complete worked threat model for a small checkout service.
+- `examples/dfd-example.md` — a standalone annotated DFD with its trust boundaries explained.
+- `scripts/stride-checklist.mjs` — runnable Node check that a threat-model doc covers all six STRIDE
+  categories for each element; supports `--selftest`.
+
+Pairs with the `security-auditor` agent (for code-level vulnerability findings), the `architect` agent
+(for the system design the model is built on), and the [`owasp-top10`](../../skills/owasp-top10/) skill
+(for mapping threats to the most common web weakness classes).

package/catalog/agents/threat-modeler/examples/dfd-example.md

@@ -0,0 +1,55 @@
+# DFD Example — Annotated
+
+A standalone data-flow diagram with its trust boundaries explained, to illustrate the notation before you
+build your own. The system: a file-upload feature where users upload documents that a worker processes.
+
+## The diagram
+
+```text
+TRUST BOUNDARY A: Internet  ││  App tier        TRUST BOUNDARY B: App tier  ┊┊  Worker tier
+
+  (E1) User ──1: HTTPS PUT /files (JWT)──►││──► (P2) Upload API ──2: store object──►││──► (DS3) Object Store
+                                         ││          │                            ││
+                                         ││          └──3: enqueue job────────────►││──► (DS4) Job Queue
+                                         ││                                        ┊┊
+                                        ││                       (P5) Worker ◄──4: dequeue──┊┊── (DS4) Job Queue
+                                         ││                            │
+                                         ││                            └──5: read object──► (DS3) Object Store
+                                         ││                            │
+                                         ││                            └──6: write result──► (DS6) Results DB
+
+  Legend: (E)=external entity (P)=process (DS)=data store
+          N: numbered data flow   ││ = network/privilege boundary   ┊┊ = process/tier boundary
+```
+
+## Why the boundaries are where they are
+
+- **Boundary A (Internet → App tier):** flow 1 carries untrusted, attacker-controllable input — the file
+  bytes, the filename, the content-type header, and the JWT. Everything arriving here must be
+  authenticated (Spoofing), authorized (Elevation of privilege), and validated (Tampering). This is the
+  single most important boundary in the system.
+- **Boundary B (App tier → Worker tier):** the job queue is a *trust boundary even though it's internal*.
+  The worker (P5) consumes whatever the Upload API enqueued plus the object it stored. If an attacker can
+  influence the filename or object contents, the worker is processing attacker-controlled data — so
+  parsing in P5 (think: image/PDF/zip parsers) is a prime Tampering and Elevation-of-privilege target,
+  even though no public flow touches the worker directly.
+
+## Threats that fall out of this diagram
+
+Reading along the crossing flows:
+
+- **Flow 1 → P2:** unrestricted file upload (a `.php`/`.svg` masquerading as an image) → Elevation of
+  privilege / stored XSS. Path traversal in the filename → Tampering of the object store.
+- **DS3 Object Store:** public-readable bucket → Information disclosure of other users' files.
+  Missing ownership check on later retrieval → IDOR (Elevation of privilege).
+- **Flow 4 → P5:** a malicious file enqueued earlier is parsed by the worker → memory-corruption or
+  decompression-bomb DoS in the parser. The worker often runs with more privileges than the API — a
+  parser exploit here is high impact.
+- **DS6 Results DB:** if results include rendered user content, stored XSS can resurface when displayed.
+
+## Takeaways
+
+1. Internal queues and worker tiers are still behind trust boundaries — model them.
+2. The most dangerous element is often not the public API but the *background process* that parses what
+   the public API accepted.
+3. Number flows so the threat table can reference them unambiguously (e.g. "T-flow1-E", "T-flow4-T").

package/catalog/agents/threat-modeler/examples/threat-model.md

@@ -0,0 +1,81 @@
+# Threat Model — "QuickCheckout" Checkout Service
+
+A complete, worked threat model for a small checkout service. Use it as a template for shape and depth.
+
+## 1. Scope & assets
+
+**In scope:** the public checkout API, its auth, the orders and session stores, and the Stripe
+integration. **Out of scope:** the marketing site, internal analytics pipeline.
+
+**Assets (ranked):**
+1. Customers' stored payment method tokens and order/PII data — highest value.
+2. Account credentials / session tokens.
+3. Integrity of order and refund records (financial correctness).
+4. Service availability during a sale.
+
+**Adversaries:** unauthenticated external attacker; authenticated malicious customer (abuse/IDOR);
+compromised third-party JS dependency; opportunistic bot networks.
+
+## 2. Data-flow diagram
+
+```text
+TRUST BOUNDARY: Internet  ││  Private network
+
+  (E1) Browser ──1: POST /login──────────►││──► (P2) Auth Service ──3: read/write──►││──► (DS3) User DB
+       │                                  ││         │                              ││
+       │                                  ││         └──4: read/write session──────►││──► (DS4) Session Cache
+       │                                  ││
+       └──2: POST /checkout (JWT)─────────►││──► (P5) Order API ──6: SQL────────────►││──► (DS6) Orders DB
+                                          ││         │
+                                          ││         ├──7: append──────────────────►││──► (DS7) Audit Log
+                                          ││         │
+                                          ││         └──8: POST /charge─────────────►││──► (E8) Stripe API
+  Legend: (E)=external entity (P)=process (DS)=data store  N: flow  ││ = trust boundary
+```
+
+## 3. STRIDE threat table
+
+```text
+| ID  | Element              | STRIDE | Threat                                          | L | I | Sev | Decision  |
+|-----|----------------------|--------|-------------------------------------------------|---|---|-----|-----------|
+| T1  | (2) /checkout flow   | T      | SQL injection via cart item id into Orders DB   | 3 | 3 | 9   | Mitigate  |
+| T2  | (P2) Auth Service    | S      | Credential stuffing against /login              | 3 | 2 | 6   | Mitigate  |
+| T3  | (2) /checkout (JWT)  | E      | IDOR: user A submits order referencing user B   | 3 | 3 | 9   | Mitigate  |
+| T4  | (DS4) Session Cache  | I      | Session tokens readable in Redis at rest        | 2 | 3 | 6   | Mitigate  |
+| T5  | (DS7) Audit Log      | R      | User disputes refund; log row is editable       | 2 | 2 | 4   | Mitigate  |
+| T6  | (8) Stripe flow      | I      | Card data passes through our server unnecessarily| 2 | 3 | 6  | Avoid     |
+| T7  | (P5) Order API       | D      | Checkout flood exhausts DB connection pool      | 2 | 2 | 4   | Mitigate  |
+| T8  | (E1) Browser         | T      | Compromised third-party JS skims card form      | 2 | 3 | 6   | Mitigate  |
+| T9  | (P2) Auth Service    | I      | Verbose error reveals which emails are registered| 2 | 1 | 2  | Mitigate  |
+```
+
+## 4. Mitigations
+
+```text
+| Threat | Control                                                              | Verify by                                  |
+|--------|----------------------------------------------------------------------|--------------------------------------------|
+| T1     | Parameterized queries only; reject non-ULID item ids at boundary     | Static check + injection test in CI        |
+| T2     | Per-account + per-IP rate limit, lockout, MFA option                  | Load test login; assert 429 after N tries  |
+| T3     | Server-side ownership check: order.user_id == token.sub on every read | Authz test: user A cannot fetch B's order  |
+| T4     | Encrypt session cache at rest; short TTL; rotate on privilege change  | Confirm KMS-backed encryption; TTL config  |
+| T5     | Append-only audit store; logs outside app write path; signed rows    | Attempt UPDATE on audit row → denied        |
+| T7     | Bounded conn pool + per-key rate limit + queue with back-pressure     | Stress test; assert graceful 429, no crash |
+| T8     | Use Stripe-hosted fields/iframe; SRI on third-party scripts; CSP      | CSP report-only in staging; SRI hashes set |
+| T9     | Generic "invalid credentials" response; constant-time compare        | Test login with unknown vs known email     |
+```
+
+## 5. Accepted / transferred risks
+
+- **T6 (avoided):** card data will never transit our servers — we use Stripe Elements so the browser
+  posts card details directly to Stripe. This *avoids* the threat (and most PCI scope) rather than
+  mitigating it. Owner: Payments lead.
+- **Volumetric DDoS at the network layer:** transferred to the CDN/WAF provider; accepted residual risk
+  of brief degradation during an extreme flood. Owner: SRE on-call.
+
+## 6. Top risks & riskiest assumption
+
+**Fix before launch:** T1 (SQLi, sev 9), T3 (IDOR, sev 9), then T2 (credential stuffing, sev 6).
+
+**Riskiest assumption to validate first:** that the JWT `sub` claim is validated server-side on *every*
+order read and write. If any handler trusts a client-supplied `user_id` instead, T3 is exploitable
+regardless of the other controls — verify this first.

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.