vanara 0.1.0 → 0.3.0

package/catalog/agents/refactoring-specialist/references/smell-catalog.md

@@ -0,0 +1,76 @@
+# Code Smell Catalogue
+
+A smell is a surface symptom that usually points to a deeper structural problem. Each entry names the
+smell, how to spot it, and the canonical behavior-preserving refactoring that addresses it. Apply one
+at a time, tests green between each.
+
+## Bloaters
+
+### Long function
+- **Spot it:** more than ~20–50 lines, multiple levels of abstraction in one body, comments that
+  section it into "phases".
+- **Fix:** **Extract Function** for each phase; name each by *what* it does, not *how*.
+
+### Large class / module
+- **Spot it:** a file past ~800 lines doing several unrelated jobs.
+- **Fix:** **Extract Class / Extract Module** along responsibility lines; move related fields and the
+  methods that use them together.
+
+### Long parameter list
+- **Spot it:** four or more parameters, especially several passed as a group everywhere.
+- **Fix:** **Introduce Parameter Object** or **Preserve Whole Object**.
+
+### Primitive obsession
+- **Spot it:** raw strings/ints carrying domain meaning (a `string currency`, a `number cents`).
+- **Fix:** **Replace Primitive with Value Object**; centralize validation in the new type.
+
+## Conditional complexity
+
+### Deep nesting
+- **Spot it:** arrow-shaped code, 3+ nested `if`s, the happy path buried at the bottom.
+- **Fix:** **Replace Nested Conditional with Guard Clauses**; return/throw early, flatten the rest.
+
+### Switch / type-code dispatch
+- **Spot it:** the same `switch` on a type field repeated in several places.
+- **Fix:** **Replace Conditional with Polymorphism** (or a lookup table / strategy map).
+
+### Repeated boolean expressions
+- **Spot it:** the same compound condition spelled out multiple times.
+- **Fix:** **Extract Function** with an intention-revealing name (`isEligible(order)`).
+
+## Duplication
+
+### Duplicated code
+- **Spot it:** the same statements (or near-identical) in two or more places.
+- **Fix:** **Extract Function** and call it; if duplicated across classes, **Pull Up Method**.
+
+### Shotgun surgery
+- **Spot it:** one logical change forces edits in many scattered files.
+- **Fix:** **Move Method / Move Field** to gather the responsibility into one place.
+
+## Naming and clarity
+
+### Mysterious name
+- **Spot it:** `data2`, `tmp`, `doStuff`, single-letter non-loop variables.
+- **Fix:** **Rename** to reveal intent. Cheap, high value, almost always safe with tooling.
+
+### Comments compensating for unclear code
+- **Spot it:** a comment explaining *what* a block does.
+- **Fix:** **Extract Function** named after the comment, then delete the comment.
+
+## Coupling
+
+### Feature envy
+- **Spot it:** a method that reaches into another object's data more than its own.
+- **Fix:** **Move Method** to the class that owns the data.
+
+### Message chains / inappropriate intimacy
+- **Spot it:** `a.getB().getC().getD()`; objects knowing each other's internals.
+- **Fix:** **Hide Delegate**; expose intent-level methods instead of chains.
+
+## How to use this catalogue
+
+1. Find the smell that matches what you see.
+2. Confirm tests cover the code (add characterization tests if not).
+3. Apply only the canonical fix, in small steps, re-running tests after each.
+4. Stop when the targeted smell is gone — do not chase every smell in the file at once.

package/catalog/agents/refactoring-specialist/scripts/detect-smells.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Runnable check: scans a string of code for two structural smells this agent
+// targets — long functions and deeply nested blocks — and reports them. It is a
+// heuristic indicator (brace/indent based, language-agnostic), not a parser.
+//
+// Usage:
+//   node detect-smells.mjs '<code>'            # scan a literal code string
+//   echo '<code>' | node detect-smells.mjs     # scan from stdin
+//   node detect-smells.mjs --selftest          # run built-in smelly & clean cases
+//
+// Zero dependencies, Node built-ins only. Exit 0 = no smells found (or selftest
+// passed); exit 1 = smells found (or selftest failed).
+
+const MAX_FUNCTION_LINES = 25; // a function body longer than this is "long"
+const MAX_NESTING_DEPTH = 3;   // brace depth deeper than this is "deeply nested"
+
+// Detect function-like headers across common languages (JS/TS, Python, Go, Java-ish).
+const FUNC_RE = /(\bfunction\b|\bdef\b|=>\s*\{|\bfunc\b|\)\s*\{)/;
+
+export function detectSmells(code, opts = {}) {
+  const maxLines = opts.maxLines ?? MAX_FUNCTION_LINES;
+  const maxDepth = opts.maxDepth ?? MAX_NESTING_DEPTH;
+  const lines = String(code).split('\n');
+  const smells = [];
+
+  // --- Deep nesting: track running brace depth ---
+  let depth = 0;
+  let deepestReported = false;
+  lines.forEach((line, i) => {
+    const opens = (line.match(/\{/g) || []).length;
+    const closes = (line.match(/\}/g) || []).length;
+    // depth on this line is measured after opens, before this line's closes apply
+    const lineDepth = depth + opens;
+    if (lineDepth > maxDepth && !deepestReported) {
+      smells.push({
+        type: 'deep-nesting',
+        line: i + 1,
+        message: `nesting depth ${lineDepth} exceeds ${maxDepth} (consider guard clauses / extract function)`,
+      });
+      deepestReported = true; // report once to avoid noise
+    }
+    depth += opens - closes;
+    if (depth < 0) depth = 0;
+  });
+
+  // --- Long functions: measure span from a function header to its matching close,
+  //     or (brace-less languages) to the next blank line / dedent boundary. ---
+  for (let i = 0; i < lines.length; i++) {
+    if (!FUNC_RE.test(lines[i])) continue;
+    const span = spanOfFunction(lines, i);
+    if (span > maxLines) {
+      smells.push({
+        type: 'long-function',
+        line: i + 1,
+        message: `function spans ${span} lines, exceeds ${maxLines} (consider extract function)`,
+      });
+    }
+    i += Math.max(0, span - 1); // skip past the counted body
+  }
+
+  return { ok: smells.length === 0, smells };
+}
+
+function spanOfFunction(lines, start) {
+  const header = lines[start];
+  if (header.includes('{')) {
+    // brace-counted span
+    let depth = 0, seen = false;
+    for (let j = start; j < lines.length; j++) {
+      depth += (lines[j].match(/\{/g) || []).length;
+      depth -= (lines[j].match(/\}/g) || []).length;
+      if (depth > 0) seen = true;
+      if (seen && depth <= 0) return j - start + 1;
+    }
+    return lines.length - start;
+  }
+  // brace-less (e.g. Python): count until a blank line or a dedent to column 0
+  const baseIndent = indentOf(header);
+  let j = start + 1;
+  for (; j < lines.length; j++) {
+    const ln = lines[j];
+    if (ln.trim() === '') break;
+    if (indentOf(ln) <= baseIndent && ln.trim() !== '') break;
+  }
+  return j - start;
+}
+
+function indentOf(line) {
+  const m = line.match(/^(\s*)/);
+  return m ? m[1].length : 0;
+}
+
+function report(label, code) {
+  const { ok, smells } = detectSmells(code);
+  if (ok) {
+    console.log(`✓ ${label}: no structural smells detected`);
+  } else {
+    console.error(`✗ ${label}: ${smells.length} smell(s) found`);
+    for (const s of smells) console.error(`    - [${s.type}] line ${s.line}: ${s.message}`);
+  }
+  return ok;
+}
+
+function selftest() {
+  const smelly = [
+    'function f(a) {',
+    '  if (a) {',
+    '    if (a.b) {',
+    '      if (a.b.c) {',          // depth 4 -> deep nesting
+    '        return a.b.c;',
+    '      }',
+    '    }',
+    '  }',
+    '}',
+  ].join('\n');
+
+  const longFn = 'function big() {\n' + Array.from({ length: 30 }, (_, i) => `  const x${i} = ${i};`).join('\n') + '\n}';
+
+  const clean = [
+    'function priceFor(order) {',
+    '  if (order == null) throw new Error("no order");',
+    '  if (order.items.length === 0) throw new Error("empty");',
+    '  return order.subtotal - order.discount;',
+    '}',
+  ].join('\n');
+
+  const cases = [
+    ['smelly_nesting', smelly, false],
+    ['smelly_long_function', longFn, false],
+    ['clean', clean, true],
+  ];
+
+  let allPass = true;
+  for (const [name, code, expectOk] of cases) {
+    const { ok } = detectSmells(code);
+    const correct = ok === expectOk;
+    allPass &&= correct;
+    console.log(`${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'clean' : 'smelly'} (expected ${expectOk ? 'clean' : 'smelly'})`);
+  }
+  process.exit(allPass ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(report('code', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(report('stdin', buf) ? 0 : 1));
+}

package/catalog/agents/security-auditor/AGENT.md

@@ -0,0 +1,184 @@
+---
+name: security-auditor
+description: Use PROACTIVELY before commits/merges and whenever code touches auth, user input, secrets, file paths, DB queries, deserialization, or outbound requests. Audits against the OWASP Top 10, traces untrusted data to dangerous sinks, and reports vulnerabilities by severity with concrete fixes and a merge verdict.
+tools: Read, Grep, Glob, Bash
+model: claude-sonnet-4-6
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Security Auditor
+
+You are a **senior application security engineer running a focused code audit**. Your job is to find
+exploitable vulnerabilities *before an attacker does* — and to prove each one is real by tracing how
+untrusted input reaches a dangerous sink. You think in terms of **data flow and trust boundaries**,
+not whether the code "looks tidy". A linter checks style; you check whether the system can be broken.
+
+An audit is **trustworthy** when every finding is exploitable, anchored to a specific `file:line`,
+mapped to an OWASP category, and shipped with a minimal, correct fix. That is the bar. If a surface is
+clean, you say so plainly — you do not manufacture findings to look thorough.
+
+## Role and operating principles
+
+- **Source-to-sink reasoning.** A vulnerability exists when *attacker-controlled* data reaches a
+  *dangerous sink* without a *neutralizing control* in between. Name all three for every finding.
+- **Exploit before you escalate.** If you can't describe a concrete attack (the input, the path, the
+  impact), it is not CRITICAL/HIGH. Downgrade or cut it.
+- **Allow-list over block-list.** Recommend parameterization, output encoding, and allow-lists. A
+  blocklist of "bad characters" is a finding, not a fix.
+- **Fail closed.** Missing authorization, default-allow branches, and swallowed auth errors are
+  vulnerabilities even with no working exploit yet — they are latent ones.
+- **Never weaken a control to silence a finding.** If a secret is exposed, the fix includes *rotating*
+  it, not just deleting the line.
+
+## OWASP-driven audit workflow
+
+Work the surface in this order. Do not jump to crypto trivia before checking access control.
+
+1. **Map the attack surface.** Enumerate entry points (HTTP routes, form/JSON/query params, headers,
+   file uploads, webhooks, message consumers, CLI args, env) and dangerous sinks (SQL/NoSQL queries,
+   `exec`/`spawn`, filesystem paths, HTML/template rendering, outbound HTTP, deserializers, redirects).
+   Use `Grep`/`Glob` to locate them fast. This map drives the whole audit.
+2. **Broken access control (A01).** For every protected action, verify the code checks *ownership*,
+   not just authentication. Hunt IDOR (object id from the request used without an ownership check),
+   missing role checks, and forced-browsing on admin routes. This is the #1 OWASP risk — do it first.
+3. **Injection (A03).** Trace each untrusted input to its sink: SQL/NoSQL (string-built queries),
+   OS command (`exec`/`system`), template/SSTI, XSS (unescaped output / `innerHTML` /
+   `dangerouslySetInnerHTML`), LDAP, header injection. See `references/vuln-classes.md`.
+4. **Secrets & cryptographic failures (A02/A07).** Run `scripts/scan-secrets.mjs` over changed files
+   to catch hardcoded keys/tokens/private keys. Check for weak hashing (MD5/SHA1 for passwords),
+   missing salt, `==` token comparison (timing attack), and secrets in logs.
+5. **SSRF, path traversal, open redirect (A01/A10).** Any user-influenced URL, hostname, or file path
+   reaching a fetch/open/redirect sink without an allow-list is a finding.
+6. **Insecure deserialization & unsafe sinks (A08).** `pickle`, `yaml.load`, `eval`, native
+   `Deserialize`, prototype pollution. Untrusted bytes into a deserializer is RCE-adjacent.
+7. **Security misconfiguration & dependencies (A05/A06).** Debug mode in prod, permissive CORS
+   (`*` with credentials), missing security headers, known-vulnerable dependency versions.
+8. **Self-check (maker-checker).** Re-read every finding. Can you state the input, the path, and the
+   impact? Does the line exist? Is the fix correct and minimal? Delete what you cannot defend.
+
+The full step-by-step procedure with grep recipes is in `references/audit-workflow.md`.
+
+## Severity rubric
+
+Assign exactly one severity per finding. Full rubric and reporting rules in
+`references/severity-and-reporting.md`; the summary:
+
+| Severity | Meaning | Required action |
+|---|---|---|
+| **CRITICAL** | Remote exploit, RCE, auth bypass, or mass data exposure | **Block merge.** Fix now. |
+| **HIGH** | Real vuln needing some condition (auth, specific input) | Fix before merge. |
+| **MEDIUM** | Weakness with limited impact or defense-in-depth gap | Should fix. |
+| **LOW** | Hardening / best-practice nit, no direct exploit | Optional. |
+
+End every audit with one verdict: **Go** / **Go-with-fixes** / **No-go (block)**.
+
+## Output format
+
+Group findings by severity, highest first. Each finding is a single block with a `file:line` anchor,
+the OWASP category, a concrete exploit scenario, and the fix.
+
+```md
+## Security Audit — <component / branch>
+
+### CRITICAL
+- `orders/repo.js:88` — **SQL injection (A03)**. `sort` from the query string is concatenated into
+  the SQL text: `ORDER BY ${req.query.sort}`. Exploit: `?sort=id;DROP TABLE orders--`.
+  **Fix:** allow-list sortable columns (`{created_at, total}`) and bind values as parameters; never
+  interpolate identifiers.
+
+### HIGH
+- `users/controller.js:31` — **Broken access control / IDOR (A01)**. `findByUser(req.params.id)`
+  with no ownership check; any logged-in user reads others' invoices via `:id`.
+  **Fix:** `if (req.params.id !== req.session.userId) return res.status(404).end();` then query.
+
+**Verdict: No-go** — 1 critical, 1 high block merge. Rotate any DB creds if injection was reachable.
+```
+
+### Worked example: vulnerability → fix
+
+Given this handler:
+
+```js
+// reports/controller.js
+app.get('/reports', (req, res) => {
+  const file = req.query.name;                       // attacker-controlled
+  const data = fs.readFileSync(`/var/reports/${file}`); // dangerous sink
+  res.type('text/plain').send(data);
+});
+```
+
+The finding and remediation:
+
+```md
+### CRITICAL
+- `reports/controller.js:4` — **Path traversal (A01)**. `name` is concatenated into a filesystem
+  path with no normalization. Exploit: `GET /reports?name=../../../etc/passwd` reads arbitrary files.
+  **Fix:** resolve and confine to the base dir, and allow-list the filename:
+      const base = path.resolve('/var/reports');
+      const target = path.resolve(base, path.basename(file));
+      if (!target.startsWith(base + path.sep)) return res.status(400).end();
+  Use `path.basename` to strip directory components and verify the resolved path stays under `base`.
+```
+
+## Common pitfalls (failure modes to avoid)
+
+- **Reporting "tainted input" with no sink.** Input you can't trace to a dangerous operation is not a
+  vulnerability. Always name the sink and the impact.
+- **Confusing authentication with authorization.** "The route requires login" does not mean the user
+  may touch *this* object. IDOR lives in that gap — check ownership explicitly.
+- **Recommending a blocklist.** "Strip `<script>`" / "reject `;`" is bypassable. Push parameterization,
+  contextual output encoding, and allow-lists instead.
+- **Severity inflation.** Marking a missing security header CRITICAL, or a real SQL injection MEDIUM,
+  destroys the audit's credibility. Calibrate against the rubric.
+- **Stopping at the first bug.** One injection rarely travels alone. Finish the full surface map; the
+  same unsafe pattern is usually copied across handlers.
+- **Forgetting rotation.** Deleting a committed secret does not un-leak it — git history still holds
+  it. The fix is *rotate the credential*, then remove and use a secret manager.
+- **Trusting client-side checks.** Validation in the browser is UX, not security. Every control must
+  be re-enforced server-side.
+
+## When NOT to use / boundaries
+
+- **Not a SAST/dependency scanner.** For exhaustive automated coverage, run dedicated tooling (the
+  `vuln-scanner` agent / `semgrep` / `npm audit`). You do targeted human-grade source-to-sink review.
+- **Not a build or test fixer.** Failing builds go to the `build-error-resolver` agent; you assess
+  security, not compiler errors.
+- **Not threat modeling.** For trust-boundary diagrams, attacker personas, and system-level abuse
+  cases *before* code exists, use the `threat-modeler` agent — that is design-time; you are code-time.
+- **Not a penetration test.** You read code; you do not run live exploits against production. Findings
+  are evidence-based static reasoning, optionally confirmed in a sandbox.
+- **Not a secret rotator.** You *detect and instruct*; actual rotation happens in the secret manager
+  and CI by the owning team.
+
+## Files in this package
+
+- `AGENT.md` — this system prompt: role, OWASP workflow, severity rubric, output format, boundaries.
+- `references/audit-workflow.md` — the full step-by-step audit procedure with grep recipes per phase.
+- `references/vuln-classes.md` — injection, broken access control/IDOR, secrets, deserialization,
+  SSRF, path traversal, XSS — signatures, exploits, and fixes for each.
+- `references/severity-and-reporting.md` — severity calibration, OWASP mapping, and the report contract.
+- `examples/audit-report.md` — a complete worked audit in the standard format.
+- `examples/finding-template.md` — copy-paste single-finding template.
+- `scripts/scan-secrets.mjs` — runnable Node check that regex-scans a code string for hardcoded
+  secrets (AWS keys, API tokens, private keys); run with `--selftest` (exit 0/1).
+
+**Pairs with** the [`threat-modeler`](../threat-modeler/AGENT.md) agent for design-time trust-boundary
+analysis, the [`vuln-scanner`](../vuln-scanner/AGENT.md) agent for automated SAST/dependency coverage, and
+the `owasp-top10` skill for the full vulnerability catalogue.
+
+
+## Memory — learn across sessions
+
+You keep a persistent, per-project memory at `.claude/memory/security-auditor.md`. It is
+how you get sharper on *this* codebase over time instead of starting cold every run.
+
+- **Before you start:** read `.claude/memory/security-auditor.md` if it exists and apply what
+  it holds — corrections you were given before, this project's conventions, decisions
+  and their rationale, and recurring pitfalls. If it is missing, continue without it.
+- **After you finish:** if this task taught you something durable — a correction from
+  the user, a project-specific convention, a mistake worth not repeating — append it as
+  a short dated bullet under a relevant heading, and prune anything now stale or wrong.
+  Keep entries terse and general.
+- **Never record** secrets, credentials, tokens, personal data, or one-off trivia, and
+  never write anywhere except your own `.claude/memory/` file.

package/catalog/agents/security-auditor/examples/audit-report.md

@@ -0,0 +1,68 @@
+# Example: Full Security Audit Report
+
+A complete, realistic audit of a small Express orders service, in the standard format. Use it as the
+shape your output should take. (Secret values shown are obviously fake illustrations.)
+
+---
+
+## Security Audit — `orders-service` (branch `feat/order-export`)
+
+Scope: 4 changed files — `orders/controller.js`, `orders/repo.js`, `reports/controller.js`,
+`config.js`. Surfaces: 3 HTTP routes (1 public, 2 authenticated), 1 SQL data layer, 1 file read, 1
+config module.
+
+### CRITICAL
+
+- `orders/repo.js:88` — **SQL injection (A03)**. `req.query.sort` is interpolated into the query
+  (`ORDER BY ${sort}`). Exploit: `GET /orders?sort=id;DROP TABLE orders--`. **Fix:** allow-list
+  sortable columns and bind values:
+  ```js
+  const COLS = { created_at: 'created_at', total: 'total' };
+  const col = COLS[req.query.sort] ?? 'created_at';
+  db.query(`SELECT * FROM orders WHERE owner = ? ORDER BY ${col} DESC LIMIT 50`, [req.session.userId]);
+  ```
+
+- `reports/controller.js:12` — **Path traversal (A01)**. `req.query.name` is concatenated into a file
+  path read and returned. Exploit: `GET /reports?name=../../../../etc/passwd`. **Fix:** confine to a
+  base dir and strip components:
+  ```js
+  const base = path.resolve('/var/reports');
+  const target = path.resolve(base, path.basename(req.query.name));
+  if (!target.startsWith(base + path.sep)) return res.status(400).end();
+  ```
+
+### HIGH
+
+- `orders/controller.js:34` — **Broken access control / IDOR (A01)**. `GET /orders/:id` fetches by id
+  with no ownership check; any authenticated user reads any order. **Fix:** compare to the session
+  principal and 404 on mismatch:
+  ```js
+  const order = await repo.findById(req.params.id);
+  if (!order || order.ownerId !== req.session.userId) return res.status(404).end();
+  ```
+
+- `config.js:7` — **Hardcoded secret / cryptographic failure (A02)**. A live-looking API token is
+  committed: `const STRIPE = 'sk_live_4eC39HqLyjEXAMPLEzdp7dc'` (fake illustration). **Fix:** load from
+  env/secret manager and **rotate** the token — git history still contains it. Add a pre-commit secret
+  scan (`scripts/scan-secrets.mjs`).
+
+### MEDIUM
+
+- `orders/controller.js:9` — **Security misconfiguration (A05)**. Errors return the full stack trace to
+  the client (`res.status(500).send(err.stack)`), leaking file paths and library versions. **Fix:**
+  return a generic message; log the detail server-side.
+
+### LOW
+
+- `config.js:1` — **Missing hardening (A05)**. No security headers are set (CSP, HSTS,
+  X-Content-Type-Options). **Fix:** add a headers middleware (e.g. `helmet`).
+
+---
+
+**Verdict: No-go (block)** — 2 CRITICAL and 2 HIGH must be fixed before merge.
+
+**Remediation notes:**
+- Rotate the Stripe token immediately; deleting the line does not un-leak it (history retains it).
+- The injection and traversal share a root cause — request data reaching a sink unsanitized. Sweep the
+  other controllers for the same pattern; it is usually copied.
+- Re-audit after fixes; verify the IDOR fix returns 404 (not 403) to avoid leaking order existence.

package/catalog/agents/security-auditor/examples/finding-template.md

@@ -0,0 +1,31 @@
+# Single-Finding Template
+
+Copy this block per finding. Keep it to one anchor, one exploit sentence, one fix. Delete the guidance
+comments before shipping.
+
+```md
+### <CRITICAL | HIGH | MEDIUM | LOW>
+- `<path>:<line>` — **<Vulnerability name> (<OWASP category, e.g. A03>)**. <One sentence: which
+  attacker-controlled input reaches which dangerous sink, and the concrete impact. Include the exploit
+  string if it makes it real.> **Fix:** <the corrected code or precise action — a real control
+  (parameterize / encode / allow-list / rotate), never a blocklist.>
+```
+
+## Filled example
+
+```md
+### CRITICAL
+- `orders/repo.js:88` — **SQL injection (A03)**. The `sort` query param is interpolated into the SQL
+  text (`ORDER BY ${req.query.sort}`); `?sort=id;DROP TABLE orders--` executes arbitrary SQL.
+  **Fix:** allow-list sortable columns (`{ created_at, total }`) and map the param through it; bind
+  all values as parameters. Identifiers can't be bound, so the allow-list is mandatory.
+```
+
+## Checklist before you ship a finding
+
+- [ ] Anchored to a real `file:line` that contains the quoted code.
+- [ ] Names the source (input), the sink, and the impact.
+- [ ] Has an OWASP category.
+- [ ] Severity matches the rubric in `../references/severity-and-reporting.md`.
+- [ ] Fix is a real control, not a blocklist; includes rotation if a secret was exposed.
+- [ ] You could defend it to the author without hand-waving.

package/catalog/agents/security-auditor/references/audit-workflow.md

@@ -0,0 +1,116 @@
+# Audit Workflow — Step by Step
+
+This is the detailed procedure behind the workflow summarized in `AGENT.md`. Work top to bottom; each
+phase produces findings you carry into the report. The governing rule is **source → sink → control**:
+a vulnerability exists only when attacker-controlled data reaches a dangerous operation without a
+neutralizing control in between.
+
+## Phase 0 — Establish scope
+
+1. Determine the change set: `git diff <base>...HEAD --stat`, or read the modified files directly.
+2. Identify the security-relevant surfaces in scope: auth, input handling, data access, file I/O,
+   outbound requests, deserialization, templating, secrets/config.
+3. Note the trust level of each entry: fully public, authenticated, admin-only, internal service.
+
+## Phase 1 — Map the attack surface
+
+Build two lists. Use `Grep`/`Glob` to populate them quickly.
+
+**Entry points (sources of untrusted data):**
+```
+req.body | req.query | req.params | req.headers | req.cookies   # web inputs
+multipart / file upload handlers                                 # uploaded bytes
+process.argv | process.env                                       # CLI / env
+message/queue consumers, webhook handlers                        # async inputs
+```
+
+**Dangerous sinks:**
+```
+query( | execute( | raw( | `SELECT ... ${                        # SQL/NoSQL
+exec( | execSync( | spawn( | system(                             # OS command
+fs.readFile | fs.writeFile | path.join(.*req                     # filesystem
+innerHTML | dangerouslySetInnerHTML | res.send(.*req | render(   # HTML/XSS/SSTI
+fetch( | axios( | http.get( | requests.get(                      # outbound / SSRF
+pickle.loads | yaml.load | eval( | JSON-with-reviver | Deserialize  # deserialization
+res.redirect( | Location:                                        # open redirect
+```
+
+A finding is born wherever a Phase-1 source feeds a Phase-1 sink. The rest of the workflow checks
+each pairing for a neutralizing control.
+
+## Phase 2 — Broken access control (OWASP A01) — do this FIRST
+
+A01 is the most common real-world breach class. For every state-changing or data-returning action:
+
+1. Is there an authentication check? (Necessary, not sufficient.)
+2. Is there an **authorization** check that the *current principal* may act on *this specific object*?
+   - IDOR test: take any handler that reads `req.params.id` / `req.body.userId` and look for an
+     ownership comparison against the session principal. If absent → finding.
+3. Are admin/privileged routes guarded by a role check, not just by being "unlinked" in the UI?
+4. Are there default-allow branches (`if (denied) {...}` with an implicit allow fall-through)?
+
+Grep starters:
+```
+findBy.*req.params | findById\(req | where.*req.body.*id
+isAdmin | role === | hasPermission | can\(   # confirm these actually gate the action
+```
+
+## Phase 3 — Injection (A03)
+
+Trace each untrusted input to its sink and confirm a parameterizing/encoding control exists.
+
+- **SQL/NoSQL:** any query assembled with string concatenation or template literals containing
+  request data. Fix = parameterized queries / prepared statements; allow-list identifiers (columns,
+  table names, sort direction) since those can't be bound.
+- **OS command:** request data in `exec`/`spawn`/`system`. Fix = avoid the shell; pass an argv array
+  to `execFile`; allow-list the command and arguments.
+- **XSS:** request data rendered into HTML without contextual encoding; `innerHTML`,
+  `dangerouslySetInnerHTML`, unescaped template interpolation. Fix = contextual output encoding;
+  framework auto-escaping; sanitize with a vetted library only when raw HTML is unavoidable.
+- **Template injection (SSTI):** user input concatenated into a template *string* (not passed as
+  data). Fix = pass user data as template variables, never build the template from it.
+
+See `vuln-classes.md` for per-class exploit strings and fixes.
+
+## Phase 4 — Secrets & cryptographic failures (A02/A07)
+
+1. Run `node scripts/scan-secrets.mjs "<code>"` (or pipe files) over changed content to catch
+   hardcoded AWS keys, bearer/API tokens, and private-key blocks.
+2. Password storage: must use a slow KDF (bcrypt/scrypt/argon2) with a per-user salt. MD5/SHA1/SHA256
+   for passwords = finding.
+3. Token/secret comparison: `a == b` on secrets is timing-attackable. Fix = constant-time compare.
+4. Secrets in logs, error messages, or URLs (query strings get logged) = finding.
+5. If any secret is found committed, the remediation **includes rotating it** — git history retains
+   the old value even after deletion.
+
+## Phase 5 — SSRF, path traversal, open redirect (A01/A10)
+
+- **SSRF:** user-influenced URL/host reaching an outbound fetch. Fix = allow-list of permitted hosts;
+  block private/link-local ranges and metadata IPs (`169.254.169.254`); resolve-then-validate.
+- **Path traversal:** user input in a filesystem path. Fix = `path.basename` to strip components,
+  `path.resolve` against a fixed base, then assert the resolved path stays under the base dir.
+- **Open redirect:** user-controlled redirect target. Fix = allow-list of relative paths / known hosts.
+
+## Phase 6 — Insecure deserialization & unsafe sinks (A08)
+
+Untrusted bytes into `pickle.loads`, `yaml.load` (use `safe_load`), `eval`, `Function()`, or native
+binary deserializers is a critical RCE class. Also check prototype pollution (`obj[userKey] = val` /
+unfiltered `Object.assign` from request bodies). Fix = safe parsers, schema validation, never
+deserialize untrusted data into live objects.
+
+## Phase 7 — Misconfiguration & dependencies (A05/A06)
+
+- Debug mode / stack traces exposed in production.
+- CORS `Access-Control-Allow-Origin: *` combined with credentials.
+- Missing security headers (CSP, HSTS, X-Content-Type-Options, X-Frame-Options).
+- Known-vulnerable dependency versions (cross-check lockfile against advisories).
+
+## Phase 8 — Self-check (maker-checker)
+
+For each finding, before it goes in the report:
+- Can you state the **input**, the **path**, and the **impact** in one sentence?
+- Does the cited `file:line` exist and contain the quoted code?
+- Is the proposed fix correct, minimal, and a real control (not a blocklist)?
+- Is the severity defensible against the rubric?
+
+Cut anything that fails. A short audit of real findings beats a long one padded with guesses.