@lhi/tdd-audit 1.16.0 → 1.18.0

package/docs/vulnerability-patterns.md

@@ -1,6 +1,104 @@
 # Vulnerability Patterns Reference
 
-All 57 patterns detected by `@lhi/tdd-audit` across 6 scanner modules. Source patterns are checked against `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.py`, `.go`, `.dart`, `.yml`, and `.yaml` files line-by-line. Prompt/skill patterns are checked separately against `.md` files in agent configuration directories. Supply-chain patterns check `package.json`. NEXT_PUBLIC secret patterns also check `.env*` files.
+All 79 patterns detected by `@lhi/tdd-audit` across 6 scanner modules. Source patterns are checked against `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.py`, `.go`, `.dart`, `.yml`, and `.yaml` files line-by-line. **All `.md` files in the repo are also scanned** for AI/LLM vulnerabilities, prompt injection, skill anti-patterns, hidden unicode, and hardcoded keys (see Phase 0d). Supply-chain patterns check `package.json`. NEXT_PUBLIC secret patterns also check `.env*` files.
+
+---
+
+## Custom Patterns & Extensibility
+
+`tdd-audit` is designed to be wrapped and rebranded by organizations that want to maintain their own pattern databases, plug in org-specific MCP services, or distribute a pre-configured version to their teams.
+
+All extensibility is controlled by a single `.tdd-audit.json` file at the repo root. The CLI tool and the Claude Code skill both read this file at startup. CLI flags override file config; file config overrides built-in defaults.
+
+### `.tdd-audit.json` extensibility fields
+
+```jsonc
+{
+  // ── Identity & branding ────────────────────────────────────────────────────
+  // Appears in reports, SECURITY.md, commit messages, and the README badge.
+  "org":     "Daily Caller",
+  "project": "beltway-events",
+
+  // Badge & SARIF link — replaces the default @lhi/tdd-audit npm page.
+  // Set this to your internal tool URL, your org's security portal, or your
+  // fork of tdd-audit. Controls badge href, SARIF informationUri, and the
+  // "Run /tdd-audit to remediate" footer in scan output.
+  "tdd_site": "https://security.dailycaller.com",
+
+  // Badge label text — replaces "tdd-audit" in the shields.io badge.
+  // Useful when distributing a white-labeled or rebranded version.
+  "badge_label": "dc-audit",
+
+  // ── Pattern repositories ────────────────────────────────────────────────────
+  // Each repo is cloned/pulled at audit startup and RAG-indexed.
+  // Agents query the index before proposing any fix — prior solutions surface first.
+  // Only genuinely new patterns are contributed back; existing ones are updated.
+  "pattern_repos": [
+    {
+      "name":       "caller-patterns",
+      "url":        "git@git.dailycaller.com:DailyCaller/caller-patterns.git",
+      "local_path": "../caller-patterns",
+      "namespace":  "patterns"
+    }
+    // Add more per-org or per-stack pattern repos here.
+  ],
+
+  // ── Extra skill directories ─────────────────────────────────────────────────
+  // Paths (relative to repo root) containing Claude Code skill folders.
+  // Each is linked into ~/.claude/skills/ at startup so their slash commands
+  // are available during the audit session.
+  "extra_skill_dirs": [
+    "../caller-audit"
+    // "../my-org-skills"
+  ],
+
+  // ── Extra repos ─────────────────────────────────────────────────────────────
+  // Cloned/pulled at startup for reference. Not RAG-indexed unless also listed
+  // in pattern_repos.
+  "extra_repos": [
+    // { "url": "...", "local_path": "..." }
+  ],
+
+  // ── MCP services ────────────────────────────────────────────────────────────
+  // Started before the first audit agent turn.
+  // Template vars available in args: ${project}, ${org}, ${cwd}.
+  "mcp_services": [
+    {
+      "name":    "memory-bank",
+      "cwd":     ".agent/skills/agent-memory",
+      "command": "npm run start-server",
+      "args":    ["${project}", "${cwd}"]
+    }
+  ],
+
+  // ── Extra audit domains ─────────────────────────────────────────────────────
+  // Custom check tables beyond the six built-in scanner modules.
+  // Each points to a markdown file in the repo with vulnerability definitions
+  // in the same format as the tables in this document.
+  "extra_domains": [
+    // { "name": "supabase-rls", "prompt_file": "docs/patterns-rls.md" }
+  ]
+}
+```
+
+### How the skill uses this config
+
+When `/tdd-audit` is invoked as a Claude Code slash command, the skill reads `.tdd-audit.json` from the repo root before any audit phase runs:
+
+1. **Pattern repos** — each entry is cloned/pulled then RAG-indexed into its namespace. Agents query the index via `/rag-engineer retrieve` before proposing any fix. If a prior solution is found, the agent leads with it instead of deriving from scratch.
+2. **Extra skill dirs** — linked into `~/.claude/skills/` so their commands are available during the session.
+3. **MCP services** — started and awaited before the first agent turn. The memory bank, if configured, is queried at session start to pre-load prior audit findings and known patterns.
+4. **Extra domains** — loaded alongside the built-in six. Each domain's check table is given to its parallel audit agent.
+5. **Branding** — `org` and `project` appear in the audit report header, SECURITY.md, and pattern contribution PRs. `tdd_site` and `badge_label` control the README badge and all external links in scan output.
+
+### Wrapping tdd-audit
+
+To distribute a pre-configured version to your team:
+
+1. Create a wrapper skill (e.g., `caller-audit`) that depends on `tdd-remediation`.
+2. Ship a `.tdd-audit.json` template in your wrapper's `references/` directory.
+3. Update your installer to copy `prompts/auto-audit.md` from tdd-audit and register it as `~/.claude/commands/tdd-audit.md` — the skill reads the same config file regardless of which installer registered it.
+4. Your team runs `/tdd-audit` as normal; it picks up your org's config automatically.
 
 ---
 
@@ -334,3 +432,145 @@ These patterns are checked against `.md` files in `prompts/`, `skills/`, `.claud
 **Grep signature:** `"postinstall": "curl https://..."`, `"preinstall": "wget http://..."`
 **Why it matters:** A postinstall script that shells out to `curl`/`wget` can silently exfiltrate environment variables, `.env` files, or SSH keys to an attacker's server the moment anyone installs your package or its parent.
 **Fix:** Remove network calls from lifecycle scripts. If data collection is needed, make it explicit and user-consented, never automatic on install.
+
+---
+
+## AI / LLM Advanced Patterns (v1.17.0+)
+
+Patterns sourced from Semgrep ai-best-practices and OWASP LLM Top 10.
+
+### Hardcoded Gemini Key (CRITICAL)
+**Grep signature:** `'AIza...'` (39 chars — Google API key format)
+**Note:** `skipInTests: true`
+**Why it matters:** Gemini/Google API keys grant access to all Google Cloud services associated with the account.
+**Fix:** Use `process.env.GEMINI_API_KEY`. Revoke via Google Cloud Console immediately.
+
+### Hardcoded Cohere Key (CRITICAL)
+**Grep signature:** 40-char alphanumeric string adjacent to `cohere`
+**Note:** `skipInTests: true`
+**Why it matters:** Committed Cohere key leaks billing access and all generation API capabilities.
+**Fix:** Use environment variables. Rotate via dashboard.cohere.com.
+
+### Hardcoded Mistral Key (CRITICAL)
+**Grep signature:** 32-char alphanumeric string adjacent to `mistral`
+**Note:** `skipInTests: true`
+**Why it matters:** Committed Mistral key leaks API billing and model access.
+**Fix:** Use environment variables. Rotate via console.mistral.ai.
+
+### LLM Output to exec (CRITICAL)
+**Grep signature:** `exec(response)`, `execSync(completion)`, `spawn(aiResult)`, `spawnSync(generated)`
+**Why it matters:** Raw LLM text passed to a shell command enables RCE if the model is jailbroken, fine-tuned adversarially, or the response channel is intercepted.
+**Fix:** Never pass LLM output to shell execution functions. Use a strict allowlist of safe commands.
+
+### Missing max_tokens (HIGH)
+**Grep signature:** `messages.create({...})` or `chat.completions.create({...})` without `max_tokens:` in the options object
+**Why it matters:** Without a token cap, a single API call can consume the entire model context window, leading to billing spikes or quota exhaustion.
+**Fix:** Always set `max_tokens` (OpenAI/Anthropic) or `maxOutputTokens` (Gemini). Typical safe cap: 1024–4096 tokens.
+
+### Missing system message (MEDIUM)
+**Grep signature:** `messages` array where first role is `user` with no `system` role present
+**Why it matters:** Without a system message, the model has no safety guardrails, persona boundary, or scope restriction — making jailbreaks and scope creep much easier.
+**Fix:** Always include a `{ role: 'system', content: '...' }` element as the first message.
+
+### MCP Credential in Response (HIGH)
+**Grep signature:** `tool_result` / `toolResult` containing `password`, `secret`, `token`, `api_key`, `credential`
+**Why it matters:** MCP tool results containing credentials are sent back to the LLM context and can be exfiltrated via prompt injection or logged.
+**Fix:** Sanitize all MCP tool outputs before injecting into model context. Strip or redact credential-shaped strings.
+
+### Agent Unbounded Loop (HIGH)
+**Grep signature:** `while(true)` containing `tool_use`, `tool_calls`, `function_call`, `runAgent`, or `agent.run`
+**Why it matters:** An agentic loop with no iteration cap can exhaust compute resources, API quota, and time budgets — equivalent to a self-inflicted DoS.
+**Fix:** Add an explicit iteration counter and max: `if (++iterations > MAX_ITERATIONS) throw new Error('Agent loop limit exceeded')`.
+
+### Unsafe Model Load (HIGH)
+**Grep signature:** `torch.load(` without `weights_only=True`; `pickle.load(` from a URL or user-supplied path
+**Why it matters:** PyTorch `torch.load()` and Python `pickle.load()` execute arbitrary code during deserialization. A malicious model file achieves full RCE.
+**Fix:** Use `torch.load(path, weights_only=True)` (PyTorch ≥1.13). Never load models from user-supplied URLs.
+
+---
+
+## Node.js Advanced Patterns (v1.17.0+)
+
+Patterns sourced from njsscan, Bearer CLI, and eslint-plugin-security.
+
+### Host Header Injection (HIGH)
+**Grep signature:** `req.headers['host']`, `req.hostname`, or `req.get('host')` used in redirect URL, email link, or `href` construction
+**Why it matters:** An attacker supplies a forged `Host:` header, redirecting victims to an attacker-controlled domain via password-reset emails or redirects.
+**Fix:** Use a hard-coded trusted base URL from environment config (`process.env.BASE_URL`). Never derive it from the request.
+
+### Headless Browser SSRF (CRITICAL)
+**Grep signature:** `page.goto(req.query.url)`, `wkhtmltopdf(req.body.url)`, `page.navigate(userInput)`
+**Why it matters:** Server-side headless browsers have access to the internal network. Attacker can reach cloud metadata (`169.254.169.254`), internal services, or local files.
+**Fix:** Validate URL against an allowlist of allowed hostnames. Block private IP ranges (`10.`, `172.16–31.`, `192.168.`, `127.`, `169.254.`).
+
+### Body Parser DoS (HIGH)
+**Grep signature:** `express.json()` or `bodyParser.json()` with no arguments (no `limit:` option)
+**Why it matters:** A single large request can exhaust Node.js process memory, DoSing the server.
+**Fix:** Always set a `limit`: `express.json({ limit: '100kb' })`.
+
+### vm2 Deprecated (CRITICAL)
+**Grep signature:** `require('vm2')` or `from 'vm2'`
+**Why it matters:** The `vm2` library was publicly abandoned in May 2023 with unfixed sandbox-escape CVEs (CVE-2023-29017 CVSS 9.8, CVE-2023-32314 CVSS 9.8). Any code using it is vulnerable to host compromise.
+**Fix:** Replace with `isolated-vm` for true V8 isolate sandboxing.
+
+### Pug Raw Output (HIGH)
+**Grep signature:** `!{userValue}` in Pug templates
+**Why it matters:** The `!{}` syntax renders content without HTML escaping — XSS if `userValue` is user-controlled.
+**Fix:** Use `#{userValue}` (auto-escaped) instead of `!{userValue}`.
+
+### EJS Unescaped Output (HIGH)
+**Grep signature:** `<%-` tag in EJS templates
+**Why it matters:** `<%-` renders raw HTML — XSS if the variable is user-controlled.
+**Fix:** Use `<%= %>` (auto-escaped) for all user-derived values.
+
+### Handlebars Triple-Stache (HIGH)
+**Grep signature:** `{{{userValue}}}` in Handlebars templates
+**Why it matters:** Triple-stache disables HTML escaping — XSS if `userValue` is user-controlled.
+**Fix:** Use `{{userValue}}` (double-stache, auto-escaped) for all user-derived values.
+
+### postMessage No Origin (HIGH)
+**Grep signature:** `addEventListener('message', handler)` where `handler` body does not reference `event.origin`
+**Why it matters:** Without origin validation, any page (including attacker-controlled iframes) can send arbitrary messages to your handler.
+**Fix:** Check `event.origin` against an explicit allowlist before processing any message data.
+
+### Dynamic Import User Input (HIGH)
+**Grep signature:** `import(req.query.module)`, `import(req.params.name)`, `` import(`./plugins/${req.params.name}`) ``
+**Why it matters:** User-controlled module paths enable path traversal to load arbitrary modules including `child_process` or `fs`.
+**Fix:** Use a static allowlist Map of permitted imports keyed by user-friendly name.
+
+### JWT No Revocation (HIGH)
+**Grep signature:** `jwt.sign({...}, secret, { expiresIn: '7d' })` with no token blocklist or session store
+**Why it matters:** Long-lived JWTs with no revocation mechanism cannot be invalidated after theft or logout. The token remains valid until natural expiry.
+**Fix:** Use short-lived access tokens (15 min) with a JTI blocklist in Redis, or use opaque session tokens instead.
+
+### X-Powered-By Exposed (MEDIUM)
+**Grep signature:** `const app = express()` with no subsequent `disable('x-powered-by')` or `helmet()` call
+**Why it matters:** `X-Powered-By: Express` advertises the framework and version, enabling targeted exploit selection.
+**Fix:** Add `app.use(require('helmet')())` or `app.disable('x-powered-by')`.
+
+### GraphQL Introspection On (HIGH)
+**Grep signature:** `introspection: true` in ApolloServer config
+**Why it matters:** Introspection exposes the entire schema to unauthenticated clients — a reconnaissance goldmine for attackers.
+**Fix:** Set `introspection: process.env.NODE_ENV !== 'production'`. Disable the playground in production.
+
+### GraphQL No Depth Limit (MEDIUM)
+**Grep signature:** `new ApolloServer({...})` without `depthLimit` or `createDepthLimitPlugin`
+**Why it matters:** Without depth limits, a deeply nested query can trigger O(n²) or worse resolver execution — DoS.
+**Fix:** Add `createDepthLimitPlugin(7)` and a complexity limit plugin to all ApolloServer configurations.
+
+### Sequelize TLS Disabled (HIGH)
+**Grep signature:** `dialectOptions: { ssl: false }` or `ssl: { rejectUnauthorized: false }` in Sequelize/pg/mysql2 config
+**Why it matters:** Disables certificate validation on the database connection, exposing credentials and data to MitM.
+**Fix:** Use `ssl: { require: true, rejectUnauthorized: true, ca: fs.readFileSync('./certs/ca.pem') }`.
+
+### Silent Exception Swallow (MEDIUM)
+**Grep signature:** `catch(e) {}` — empty or comment-only catch blocks
+**Note:** `skipInTests: true`
+**Why it matters:** Silently discarded exceptions hide auth failures, validation errors, and crypto failures — making incidents invisible.
+**Fix:** Always log and re-throw or return a safe error response from every catch block.
+
+### Insecure WebSocket URL (MEDIUM)
+**Grep signature:** `new WebSocket('ws://...')` — non-localhost `ws://` URL
+**Note:** `skipInTests: true`
+**Why it matters:** Unencrypted WebSocket connections expose message content and credentials to network observers.
+**Fix:** Always use `wss://` in production. Gate on `NODE_ENV`: `process.env.NODE_ENV === 'production' ? 'wss://...' : 'ws://localhost'`.

package/index.js

@@ -11,17 +11,23 @@ const {
   quickScan,
   printFindings,
 } = require('./lib/scanner');
-const { toJson, toSarif, toText } = require('./lib/reporter');
 const { writeInitConfig, loadConfig, parseCliOverrides } = require('./lib/config');
 const { badgeLine, injectBadge } = require('./lib/badge');
 
 const args = process.argv.slice(2);
-const isLocal   = args.includes('--local');
-const isClaude  = args.includes('--claude');
-const withHooks = args.includes('--with-hooks');
-const skipScan  = args.includes('--skip-scan');
-const scanOnly  = args.includes('--scan-only') || args.includes('--scan');
-const isServe   = args[0] === 'serve';
+const isLocal    = args.includes('--local');
+const isClaude   = args.includes('--claude');
+const withHooks  = args.includes('--with-hooks');
+const skipScan   = args.includes('--skip-scan');
+const isServe    = args[0] === 'serve';
+const isAI       = args.includes('--ai');
+const allowWrites = args.includes('--allow-writes');
+const isVerbose  = args.includes('--verbose');
+
+// --depth tier-1|tier-2|tier-3|tier-4  (output depth for --ai --json mode)
+// tier-4 also auto-enables --allow-writes
+const depthIdx = args.indexOf('--depth');
+const depth    = depthIdx !== -1 ? args[depthIdx + 1] : 'tier-1';
 
 // --json or --format json → structured JSON output
 // --format sarif          → SARIF 2.1.0 output
@@ -72,25 +78,30 @@ if (isServe) {
   return; // server stays alive — do not fall through to installer
 }
 
-// ─── Scan-only early exit ─────────────────────────────────────────────────────
-
-if (scanOnly) {
-  if (outputFormat !== 'text') process.stdout.write('\n🔍 Scanning...\n');
-  else process.stdout.write('\n🔍 Scanning for vulnerability patterns...');
-  const findings = quickScan(projectDir);
-  const exempted = findings.exempted || [];
-  if (outputFormat === 'json') {
-    process.stdout.write('\n');
-    console.log(JSON.stringify(toJson(findings, exempted), null, 2));
-  } else if (outputFormat === 'sarif') {
-    process.stdout.write('\n');
-    console.log(JSON.stringify(toSarif(findings, projectDir), null, 2));
-  } else {
-    process.stdout.write('\n');
-    printFindings(findings, exempted);
-  }
-  injectBadge(projectDir, badgeLine(findings, config.tdd_site));
-  process.exit(0);
+// ─── AI Audit mode early exit ─────────────────────────────────────────────────
+// tdd-audit --ai [--scan-only] [--json | --format sarif] [--allow-writes]
+//           [--provider anthropic] [--model claude-opus-4-6] [--api-key sk-...]
+//           [--base-url https://...] [--config .tdd-audit.json] [--verbose]
+
+if (isAI) {
+  const { runAudit } = require('./lib/auditor');
+  runAudit({
+    projectDir,
+    packageDir: __dirname,
+    provider:   config.provider,
+    apiKey:     config.apiKey,
+    model:      config.model,
+    baseUrl:    config.baseUrl,
+    outputFormat,
+    depth,
+    // tier-4 auto-enables writes; explicit --allow-writes also works
+    allowWrites: allowWrites || depth === 'tier-4',
+    verbose:    isVerbose,
+  }).catch(err => {
+    console.error(`\n❌ AI Audit failed: ${err.message}`);
+    process.exit(1);
+  });
+  return;
 }
 
 // ─── Install Skill Files ──────────────────────────────────────────────────────