@lhi/tdd-audit 1.15.0 → 1.18.0

package/README.md

@@ -1,7 +1,8 @@
 # @lhi/tdd-audit
+![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
 [![tdd-audit](https://img.shields.io/badge/tdd--audit-passing-brightgreen)](https://www.npmjs.com/package/@lhi/tdd-audit) <!-- tdd-audit-badge -->
 
-> **v1.15.0** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — prove the hole exists, apply the fix, prove it's closed. Enforces ≥ 95% test coverage, README badge, and SECURITY.md on every audit.
+> **v1.18.0** — AI-powered security audit skill for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Four output depth tiers let you choose between a fast scan report, a rich findings report, copy-ready patches, or fully automated patch application — all backed by an agentic LLM with tool use.
 
 ## Install
 
@@ -11,11 +12,10 @@ npx @lhi/tdd-audit
 
 On first run the installer:
 
-1. Scans your codebase for **57 vulnerability patterns** across 6 scanner modules and prints a severity-ranked report
-2. Scaffolds `__tests__/security/` with a framework-matched exploit test boilerplate
-3. Adds `test:security` to `package.json`
-4. Creates `.github/workflows/security-tests.yml` with SHA-pinned actions and `npm audit`
-5. Installs the `/tdd-audit` skill for your AI agent
+1. Scaffolds `__tests__/security/` with a framework-matched exploit test boilerplate
+2. Adds `test:security` to `package.json`
+3. Creates `.github/workflows/security-tests.yml` with SHA-pinned actions and `npm audit`
+4. Installs the `/tdd-audit` skill for your AI agent
 
 ### Flags
 
@@ -25,9 +25,6 @@ On first run the installer:
 | `--claude` | Use `.claude/` instead of `.agents/` |
 | `--with-hooks` | Add a pre-commit hook that blocks commits on failing security tests |
 | `--skip-scan` | Skip the vulnerability scan on install |
-| `--scan` / `--scan-only` | Scan only — no install, no code changes |
-| `--json` | Output findings as JSON |
-| `--format sarif` | Output findings as SARIF 2.1.0 (GitHub code scanning) |
 | `--config <path>` | Load config from an explicit file path |
 
 ### Platform
@@ -37,13 +34,57 @@ On first run the installer:
 | Claude Code | `npx @lhi/tdd-audit --local --claude` |
 | Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
 
-## Usage
+## AI Audit (`--ai`)
 
-```text
-/tdd-audit
+```bash
+npx @lhi/tdd-audit --ai \
+  --provider anthropic \
+  --api-key $ANTHROPIC_API_KEY \
+  --depth tier-2 \
+  --format json
+```
+
+The `--ai` flag triggers a full agentic audit: the LLM explores your codebase using `read_file`, `list_files`, and `search_in_files` tool calls, then produces a structured findings report shaped by `--depth`.
+
+### Depth tiers
+
+| Tier | Mode | Output | Billing unit |
+|---|---|---|---|
+| `tier-1` | scan-only | `name`, `severity`, `file`, `line`, `snippet` | per report |
+| `tier-2` | scan-only | + `risk`, `effort`, `cwe`, `owasp`, `references` | per report |
+| `tier-3` | full audit, read-only | + `patch` (copy-ready), `testSnippet` | per report |
+| `tier-4` | full audit, writes enabled | LLM applies patches via `write_file`; `patchesApplied` in envelope | per applied patch |
+
+```bash
+# Minimal scan report
+npx @lhi/tdd-audit --ai --depth tier-1 --format json
+
+# Rich report with CWE/OWASP/references — no changes made
+npx @lhi/tdd-audit --ai --depth tier-2 --format json
+
+# Copy-ready patches in every finding — apply manually
+npx @lhi/tdd-audit --ai --depth tier-3 --format json
+
+# Let the LLM apply the patches for you
+npx @lhi/tdd-audit --ai --depth tier-4 --allow-writes
+
+# Targeted apply: apply one specific patch from a prior tier-3 report
+# (via REST API — see docs/rest-api.md)
 ```
 
-The agent detects your stack, presents a CRITICAL → LOW findings report, waits for confirmation, then works through each vulnerability one at a time using Red-Green-Refactor. Pass `--scan` for a report-only run with no code changes.
+### AI flags
+
+| Flag | Description |
+|---|---|
+| `--ai` | Enable LLM agentic audit |
+| `--depth tier-1\|tier-2\|tier-3\|tier-4` | Output depth tier (default: `tier-1`) |
+| `--allow-writes` | Permit the LLM to write files (auto-enabled for `tier-4`) |
+| `--provider <name>` | `anthropic` \| `openai` \| `gemini` \| `ollama` |
+| `--api-key <key>` | Provider API key |
+| `--model <name>` | Model override (e.g. `claude-opus-4-6`, `gpt-4o`) |
+| `--base-url <url>` | Base URL for any OpenAI-compatible service |
+| `--format json\|sarif` | Structured output format (default: streaming text) |
+| `--verbose` | Print tool call details to stderr |
 
 ## Config file
 
@@ -63,7 +104,7 @@ npx @lhi/tdd-audit init ~/configs/my-audit.json
   "model":             "gpt-4o",
   "apiKeyEnv":         "OPENAI_API_KEY",
   "baseUrl":           null,
-  "output":            "text",
+  "output":            "json",
   "severityThreshold": "LOW",
   "port":              3000,
   "serverApiKey":      null,
@@ -78,30 +119,36 @@ Point to a config anywhere with `--config`:
 npx @lhi/tdd-audit serve --config ~/configs/prod-audit.json
 ```
 
-## REST API + AI remediation
+## REST API
 
 ```bash
-# Start the API server (now powered by Fastify)
+# Start the API server
 npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
 
-# Scan any path → JSON
-curl -X POST http://localhost:3000/scan \
-  -H "Authorization: Bearer YOUR_SECRET" \
-  -d '{"path": "."}' | jq '.summary'
-
-# Full automated pipeline: scan + remediate in one shot
-curl -X POST http://localhost:3000/audit \
+# AI audit — returns jobId immediately
+curl -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer YOUR_SECRET" \
   -H "Content-Type: application/json" \
-  -d '{"path": ".", "provider": "anthropic", "apiKey": "sk-ant-..."}' \
+  -d '{"provider": "anthropic", "apiKey": "sk-ant-...", "depth": "tier-2"}' \
   | jq '.jobId'
 
 # Poll job status
 curl http://localhost:3000/jobs/<jobId>
 
-# Or stream real-time updates via SSE
+# Or stream real-time LLM output via SSE
 curl -N http://localhost:3000/jobs/<jobId>/stream
 
+# Targeted apply: re-apply a specific patch from a tier-3 report
+curl -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer YOUR_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider": "anthropic",
+    "apiKey": "sk-ant-...",
+    "depth": "tier-4",
+    "findings": [{ "name": "SQL Injection", "file": "src/db.js", "line": 10, "patch": "..." }]
+  }'
+
 # Use any OpenAI-compatible service (Groq, OpenRouter, Together AI, etc.)
 npx @lhi/tdd-audit serve \
   --provider openai \
@@ -117,41 +164,40 @@ Supported providers: `anthropic` · `openai` · `gemini` · `ollama` (local) ·
 | Method | Path | Auth | Description |
 |---|---|---|---|
 | `GET` | `/health` | No | Version + liveness check |
-| `POST` | `/scan` | Yes | Scan a path, return findings |
-| `POST` | `/remediate` | Yes | AI-fix a findings list; returns `jobId` |
-| `POST` | `/audit` | Yes | Full scan+remediate pipeline; returns `jobId` |
+| `POST` | `/audit/ai` | Yes | Agentic LLM audit with depth tiers; returns `jobId` |
+| `POST` | `/remediate` | Yes | AI-fix a provided findings list; returns `jobId` |
+| `POST` | `/audit` | Yes | Static scan + AI remediation pipeline; returns `jobId` |
 | `GET` | `/jobs/:id` | Yes | Poll job status |
 | `GET` | `/jobs/:id/stream` | Yes | SSE stream — real-time job progress |
 
-## Output formats
+## Agent skill
 
-```bash
-npx @lhi/tdd-audit --scan --json          # structured JSON
-npx @lhi/tdd-audit --scan --format sarif  # GitHub code scanning (inline PR annotations)
-npx @lhi/tdd-audit --scan                 # human-readable text (default)
+```text
+/tdd-audit
 ```
 
+The agent detects your stack, presents a CRITICAL → LOW findings report, waits for confirmation, then works through each vulnerability one at a time using Red-Green-Refactor (prove the hole exists, apply the fix, prove it's closed). Enforces ≥ 95% test coverage, README badge, and SECURITY.md on every audit.
+
 ## Testing
 
-586 tests across unit, E2E, and security suites:
+791 tests across unit, E2E, and security suites:
 
 ```bash
 npm test                  # full suite
-npm run test:unit         # unit tests with coverage (96.6% branch coverage)
+npm run test:unit         # unit tests with coverage (95.6% branch coverage)
 npm run test:security     # security regression tests only
 npm run test:e2e          # end-to-end REST API tests
 ```
 
-Security tests cover prompt injection, path traversal, rate limiting, timing-safe auth, job store bounds, SARIF schema, and more. See [__tests__/security/](__tests__/security/) for all 22 regression tests.
+Security tests cover prompt injection, path traversal, rate limiting, timing-safe auth, job store bounds, SARIF schema, and more. See [__tests__/security/](__tests__/security/) for all regression tests.
 
 ## Documentation
 
 | | |
 |---|---|
-| [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, trust-proxy, request/response schema |
+| [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, depth tiers, targeted apply |
 | [AI Remediation](docs/ai-remediation.md) | Provider setup, `--base-url` for compatible APIs, config file |
-| [Scanner](docs/scanner.md) | Architecture, detection logic, false-positive handling |
-| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 57 patterns — descriptions, grep signatures, fix pointers |
+| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 79 patterns — descriptions, grep signatures, fix pointers |
 | [TDD Protocol](docs/tdd-protocol.md) | Red-Green-Refactor in full, with framework templates for all 6 stacks |
 | [Agentic AI Security](docs/agentic-ai-security.md) | ASI01–ASI10 — prompt injection, MCP supply chain, Actions injection |
 | [Hardening](docs/hardening.md) | Phase 4 controls — Helmet, CSP, CSRF, rate limiting, gitleaks, SRI |

package/SKILL.md

@@ -1,4 +1,8 @@
 ---
+# IMPORTANT CONSTRAINTS
+# 1. NEVER add AI attribution trailers to commits (no "Co-Authored-By: Claude ..." lines).
+# 2. NEVER add AI attribution to any file, comment, or commit message.
+# 3. All commits must appear as human-authored work only.
 name: TDD Remediation Protocol
 description: A comprehensive toolkit for applying Red-Green-Refactor to fix security vulnerabilities.
 category: security
@@ -12,6 +16,8 @@ audit_status: safe
 
 # TDD Remediation Protocol
 
+> **Non-negotiable rule:** Never add AI attribution to any commit, file, or comment. Do not append `Co-Authored-By`, `Generated by`, or any similar trailer. All commits must be plain, human-authored messages.
+
 Applying Test-Driven Development (TDD) to code that has already been generated requires Test-Driven Remediation. You must prove the security hole exists by writing a test that exploits it, apply the fix, and then prove the hole is closed.
 
 ## Autonomous Audit Mode

package/docs/ai-remediation.md

@@ -1,6 +1,31 @@
 # AI Remediation
 
-Pass a provider and API key to have tdd-audit autonomously generate exploit tests, patches, and regression checks for each finding — no agent required.
+`tdd-audit --ai` runs a fully agentic LLM audit: the model explores your codebase with tool calls, identifies vulnerabilities, and (depending on the depth tier) provides copy-ready patches or applies them directly. No agent shell required.
+
+---
+
+## Depth tiers
+
+| Tier | What you get | Writes files? | Billing unit |
+|---|---|---|---|
+| `tier-1` | Scan report: name, severity, file, line, snippet | no | per report |
+| `tier-2` | + risk, effort, CWE, OWASP category, references | no | per report |
+| `tier-3` | + copy-ready `patch` and `testSnippet` per finding | no | per report |
+| `tier-4` | LLM applies patches via `write_file`; `patchesApplied` count in envelope | yes | per applied patch |
+
+```bash
+# Fast scan report
+npx @lhi/tdd-audit --ai --depth tier-1 --format json
+
+# Rich report with CWE/OWASP — review and decide what to fix
+npx @lhi/tdd-audit --ai --depth tier-2 --format json
+
+# Patch included in every finding — copy and apply yourself
+npx @lhi/tdd-audit --ai --depth tier-3 --format json
+
+# Let the LLM write the fixes
+npx @lhi/tdd-audit --ai --depth tier-4
+```
 
 ---
 
@@ -25,13 +50,13 @@ Edit `.tdd-audit.json`:
 `apiKeyEnv` names the environment variable to read the key from — no key ever touches disk. Then just:
 
 ```bash
-npx @lhi/tdd-audit serve
+npx @lhi/tdd-audit --ai --depth tier-2 --format json
 ```
 
 Point to a config at any path:
 
 ```bash
-npx @lhi/tdd-audit serve --config ~/configs/my-audit.json
+npx @lhi/tdd-audit --ai --config ~/configs/my-audit.json --depth tier-3
 ```
 
 ---
@@ -40,15 +65,17 @@ npx @lhi/tdd-audit serve --config ~/configs/my-audit.json
 
 ```bash
 # Anthropic
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider anthropic \
-  --api-key $ANTHROPIC_API_KEY
+  --api-key $ANTHROPIC_API_KEY \
+  --depth tier-2
 
 # OpenAI
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --api-key $OPENAI_API_KEY \
-  --model gpt-4o-mini
+  --model gpt-4o-mini \
+  --depth tier-1
 ```
 
 ---
@@ -60,28 +87,28 @@ The API key is sent in the `Authorization: Bearer` header — never in the URL.
 
 ```bash
 # Groq (fast inference)
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url https://api.groq.com/openai/v1 \
   --model llama-3.3-70b-versatile \
   --api-key $GROQ_API_KEY
 
 # OpenRouter (access 200+ models)
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url https://openrouter.ai/api/v1 \
   --model meta-llama/llama-3.3-70b-instruct \
   --api-key $OPENROUTER_API_KEY
 
 # Together AI
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url https://api.together.xyz/v1 \
   --model mistralai/Mixtral-8x7B-Instruct-v0.1 \
   --api-key $TOGETHER_API_KEY
 
 # LM Studio / vLLM / llama.cpp (fully local)
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url http://localhost:1234/v1 \
   --model local-model
@@ -116,53 +143,95 @@ In `.tdd-audit.json`:
 ## REST API usage
 
 ```bash
-# 1. Scan and get findings
-FINDINGS=$(curl -s -X POST http://localhost:3000/scan \
-  -H "Authorization: Bearer $SERVER_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"path": "."}' | jq '.findings')
+# Start the server
+npx @lhi/tdd-audit serve --port 3000 --api-key $SERVER_KEY
 
-# 2. Submit remediation job (using Groq via --base-url)
-JOB=$(curl -s -X POST http://localhost:3000/remediate \
+# Launch a tier-2 audit job
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer $SERVER_KEY" \
   -H "Content-Type: application/json" \
   -d "{
-    \"findings\": $FINDINGS,
     \"provider\": \"openai\",
-    \"apiKey\": \"$GROQ_API_KEY\",
-    \"baseUrl\": \"https://api.groq.com/openai/v1\",
-    \"model\": \"llama-3.3-70b-versatile\",
-    \"severity\": \"HIGH\"
-  }")
+    \"apiKey\":   \"$GROQ_API_KEY\",
+    \"baseUrl\":  \"https://api.groq.com/openai/v1\",
+    \"model\":    \"llama-3.3-70b-versatile\",
+    \"depth\":    \"tier-2\"
+  }" | jq -r '.jobId')
+
+# Poll until done
+while true; do
+  STATUS=$(curl -s http://localhost:3000/jobs/$JOB \
+    -H "Authorization: Bearer $SERVER_KEY" | jq -r '.status')
+  [ "$STATUS" = "done" ] || [ "$STATUS" = "error" ] && break
+  sleep 3
+done
+
+# Print summary
+curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer $SERVER_KEY" | jq '.result.summary'
+```
+
+### Targeted apply (tier-4)
 
-JOB_ID=$(echo $JOB | jq -r '.jobId')
+Take a single finding from a tier-3 report and apply its patch without re-scanning:
+
+```bash
+# Get the first finding from a previous tier-3 job
+FINDING=$(curl -s http://localhost:3000/jobs/$TIER3_JOB_ID \
+  -H "Authorization: Bearer $SERVER_KEY" \
+  | jq '.result.findings[0]')
 
-# 3. Poll for results
-curl -s "http://localhost:3000/jobs/$JOB_ID" \
-  -H "Authorization: Bearer $SERVER_KEY" | jq '.status'
+# Apply only that patch
+curl -s -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer $SERVER_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"provider\": \"anthropic\",
+    \"apiKey\":   \"$ANTHROPIC_API_KEY\",
+    \"depth\":    \"tier-4\",
+    \"findings\": [$FINDING]
+  }" | jq '.jobId'
 ```
 
+See [REST API](rest-api.md) for the full endpoint reference.
+
 ---
 
-## What the model returns
+## Output envelope
 
-For each finding the remediator sends a structured prompt and expects back:
+All structured output (`--format json` or via REST API) returns the same envelope shape regardless of tier:
 
 ```json
 {
-  "exploitTest": {
-    "filename": "__tests__/security/xss-comments.test.js",
-    "content": "..."
-  },
-  "patch": {
-    "filename": "src/routes/comments.js",
-    "diff": "--- a/src/routes/comments.js\n+++ ..."
-  },
-  "refactorChecks": ["npm test", "npm run test:security"]
+  "version":             "1.17.0",
+  "provider":            "anthropic",
+  "model":               "claude-opus-4-6",
+  "depth":               "tier-3",
+  "mode":                "full",
+  "stack":               "Node.js / Express",
+  "summary":             { "CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 0 },
+  "patchesApplied":      0,
+  "findings": [
+    {
+      "name":        "SQL Injection",
+      "severity":    "HIGH",
+      "file":        "src/db.js",
+      "line":        42,
+      "snippet":     "db.query(userInput)",
+      "risk":        "Full database read/write via UNION injection",
+      "effort":      "low",
+      "cwe":         "CWE-89",
+      "patch":       "const stmt = db.prepare('SELECT ...');\nstmt.run(id);",
+      "testSnippet": "test('prevents injection', () => { ... });"
+    }
+  ],
+  "likelyFalsePositives": [],
+  "remediation":          [],
+  "scannedAt":            "2026-03-26T12:00:00.000Z"
 }
 ```
 
-The result is returned as-is from the API — review and apply patches manually or pipe into your own automation.
+`patchesApplied` is always `0` for tiers 1–3 (no files written). For tier-4 it counts `remediation` entries where `status === "fixed"` — the billable unit.
 
 ---
 
@@ -174,9 +243,12 @@ ollama pull codellama
 ollama serve
 
 # Run tdd-audit against it
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider ollama \
-  --model codellama
+  --model codellama \
+  --depth tier-1
 ```
 
 No API key required. Ollama must be running on `http://localhost:11434`.
+
+Ollama does not support the tool-use API, so the audit runs in single-shot mode: the project files are bundled into the prompt rather than explored interactively with tool calls. For best results, use `tier-1` or `tier-2` with Ollama.