@lhi/tdd-audit 1.8.4 → 1.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @lhi/tdd-audit
 
-> **v1.8.4** — 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.
+> **v1.10.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.
 
 ## Install
 
@@ -25,6 +25,9 @@ On first run the installer:
 | `--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
 
@@ -41,11 +44,87 @@ On first run the installer:
 
 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.
 
+## Config file
+
+Scaffold a starter config with a single command:
+
+```bash
+npx @lhi/tdd-audit init
+# or at a custom path:
+npx @lhi/tdd-audit init ~/configs/my-audit.json
+```
+
+`.tdd-audit.json` — all CLI flags settable here, loaded automatically from your project root:
+
+```json
+{
+  "provider":          "openai",
+  "model":             "gpt-4o",
+  "apiKeyEnv":         "OPENAI_API_KEY",
+  "baseUrl":           null,
+  "output":            "text",
+  "severityThreshold": "LOW",
+  "port":              3000,
+  "serverApiKey":      null,
+  "trustProxy":        false,
+  "ignore":            ["node_modules", "dist", "build", "coverage"]
+}
+```
+
+Point to a config anywhere with `--config`:
+
+```bash
+npx @lhi/tdd-audit serve --config ~/configs/prod-audit.json
+```
+
+## REST API + AI remediation
+
+```bash
+# 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'
+
+# Use any OpenAI-compatible service (Groq, OpenRouter, Together AI, etc.)
+npx @lhi/tdd-audit serve \
+  --provider openai \
+  --base-url https://api.groq.com/openai/v1 \
+  --api-key $GROQ_API_KEY \
+  --model llama-3.3-70b-versatile
+```
+
+Supported providers: `anthropic` · `openai` · `gemini` · `ollama` (local) · **any OpenAI-compatible endpoint via `--base-url`**
+
+## Output formats
+
+```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)
+```
+
+## Testing
+
+323 tests across unit, integration, and security suites:
+
+```bash
+npm test                  # full suite
+npm run test:unit         # unit tests with coverage
+npm run test:security     # security regression tests only
+```
+
+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 17 regression tests.
+
 ## Documentation
 
 | | |
 |---|---|
-| [Scanner](docs/scanner.md) | Architecture, detection logic, false-positive handling, how to add patterns |
+| [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, trust-proxy, request/response schema |
+| [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 34 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 |

package/docs/ai-remediation.md

@@ -0,0 +1,182 @@
+# 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.
+
+---
+
+## Config file (recommended)
+
+Scaffold once, run anywhere:
+
+```bash
+npx @lhi/tdd-audit init
+```
+
+Edit `.tdd-audit.json`:
+
+```json
+{
+  "provider":   "openai",
+  "model":      "gpt-4o",
+  "apiKeyEnv":  "OPENAI_API_KEY"
+}
+```
+
+`apiKeyEnv` names the environment variable to read the key from — no key ever touches disk. Then just:
+
+```bash
+npx @lhi/tdd-audit serve
+```
+
+Point to a config at any path:
+
+```bash
+npx @lhi/tdd-audit serve --config ~/configs/my-audit.json
+```
+
+---
+
+## CLI flags
+
+```bash
+# Anthropic
+npx @lhi/tdd-audit serve \
+  --provider anthropic \
+  --api-key $ANTHROPIC_API_KEY
+
+# OpenAI
+npx @lhi/tdd-audit serve \
+  --provider openai \
+  --api-key $OPENAI_API_KEY \
+  --model gpt-4o-mini
+```
+
+---
+
+## OpenAI-compatible services
+
+Any service that exposes the OpenAI chat completions API works via `--base-url`.
+The API key is sent in the `Authorization: Bearer` header — never in the URL.
+
+```bash
+# Groq (fast inference)
+npx @lhi/tdd-audit serve \
+  --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 \
+  --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 \
+  --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 \
+  --provider openai \
+  --base-url http://localhost:1234/v1 \
+  --model local-model
+  # no --api-key needed for local servers
+```
+
+In `.tdd-audit.json`:
+
+```json
+{
+  "provider":  "openai",
+  "baseUrl":   "https://api.groq.com/openai/v1",
+  "model":     "llama-3.3-70b-versatile",
+  "apiKeyEnv": "GROQ_API_KEY"
+}
+```
+
+---
+
+## Supported providers
+
+| Provider | `--provider` | Default model | Key env var | Notes |
+|---|---|---|---|---|
+| Anthropic | `anthropic` | `claude-opus-4-6` | `ANTHROPIC_API_KEY` | |
+| OpenAI | `openai` | `gpt-4o` | `OPENAI_API_KEY` | Supports `--base-url` |
+| Google Gemini | `gemini` | `gemini-2.0-flash` | `GEMINI_API_KEY` | Key sent via `x-goog-api-key` header |
+| Ollama (local) | `ollama` | `llama3` | — | No key required |
+| Any OpenAI-compat | `openai` | — | varies | Set `--base-url` |
+
+---
+
+## 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')
+
+# 2. Submit remediation job (using Groq via --base-url)
+JOB=$(curl -s -X POST http://localhost:3000/remediate \
+  -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\"
+  }")
+
+JOB_ID=$(echo $JOB | jq -r '.jobId')
+
+# 3. Poll for results
+curl -s "http://localhost:3000/jobs/$JOB_ID" \
+  -H "Authorization: Bearer $SERVER_KEY" | jq '.status'
+```
+
+---
+
+## What the model returns
+
+For each finding the remediator sends a structured prompt and expects back:
+
+```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"]
+}
+```
+
+The result is returned as-is from the API — review and apply patches manually or pipe into your own automation.
+
+---
+
+## Ollama (fully local / air-gapped)
+
+```bash
+# Pull a code model
+ollama pull codellama
+ollama serve
+
+# Run tdd-audit against it
+npx @lhi/tdd-audit serve \
+  --provider ollama \
+  --model codellama
+```
+
+No API key required. Ollama must be running on `http://localhost:11434`.

package/docs/rest-api.md

@@ -0,0 +1,230 @@
+# REST API
+
+`tdd-audit serve` turns the scanner into an authenticated HTTP API. Use it to integrate vulnerability scanning into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
+
+---
+
+## Start the server
+
+```bash
+# Minimal
+npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
+
+# With config file (recommended)
+npx @lhi/tdd-audit init                    # scaffold .tdd-audit.json
+npx @lhi/tdd-audit serve                   # reads config automatically
+
+# Point to a config anywhere
+npx @lhi/tdd-audit serve --config ~/configs/prod.json
+```
+
+**`.tdd-audit.json` server options:**
+
+```json
+{
+  "port":         3000,
+  "serverApiKey": "YOUR_SECRET",
+  "output":       "json",
+  "trustProxy":   false
+}
+```
+
+If `--api-key` / `serverApiKey` is omitted the server starts unauthenticated with a warning. Always set one in production.
+
+---
+
+## Security
+
+### Authentication
+
+All endpoints except `GET /health` require:
+
+```
+Authorization: Bearer YOUR_SECRET
+```
+
+Missing or wrong key → `401 Unauthorized`.
+
+Tokens are compared using **HMAC + `crypto.timingSafeEqual`** to prevent timing-oracle attacks.
+
+### Rate limiting
+
+All endpoints are rate-limited to **60 requests / IP / minute** (default). Exceeding the limit returns `429 Too Many Requests`.
+
+By default the rate limiter keys on the **socket IP**, not `X-Forwarded-For`, to prevent header-spoofing bypasses. Enable proxy-forwarded IPs only if you are behind a trusted reverse proxy:
+
+```json
+{ "trustProxy": true }
+```
+
+### Path validation
+
+`POST /scan` validates that the requested path is inside the server's working directory (normalised with a trailing separator to prevent sibling-directory prefix bypasses). Paths outside cwd return `400`.
+
+### Security headers
+
+Every response includes:
+
+```
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+```
+
+---
+
+## Endpoints
+
+### `GET /health`
+
+No auth required. Returns server status and version.
+
+```json
+{ "status": "ok", "version": "1.9.0" }
+```
+
+---
+
+### `POST /scan`
+
+Scan a local path and return structured findings.
+
+**Request**
+```json
+{
+  "path":   ".",
+  "format": "json"
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `path` | string | cwd | Absolute or relative path to scan. Must be inside server cwd. |
+| `format` | `"json"` \| `"sarif"` | `"json"` | Output format |
+
+**Response — JSON**
+```json
+{
+  "version":             "1.9.0",
+  "summary":             { "CRITICAL": 1, "HIGH": 3, "MEDIUM": 1, "LOW": 0 },
+  "findings":            [ ... ],
+  "likelyFalsePositives": [ ... ],
+  "exempted":            [],
+  "scannedAt":           "2026-03-25T12:00:00.000Z",
+  "duration":            42
+}
+```
+
+**Response — SARIF**
+
+Returns a SARIF 2.1.0 object ready to upload to GitHub code scanning.
+
+**Errors**
+
+| Status | Reason |
+|---|---|
+| 400 | Path traversal attempt, sibling-directory bypass, oversized body (> 512 KB), or invalid JSON |
+| 401 | Missing or invalid API key |
+| 429 | Rate limit exceeded |
+
+---
+
+### `POST /remediate`
+
+Queue an AI-powered remediation job. Returns immediately with a `jobId`; poll `/jobs/:id` for results.
+
+The server stores up to **1 000 jobs** in memory (TTL: 1 hour). Oldest jobs are evicted when the cap is reached.
+
+**Request**
+```json
+{
+  "findings": [ ... ],
+  "provider": "openai",
+  "apiKey":   "sk-...",
+  "model":    "gpt-4o",
+  "baseUrl":  "https://api.groq.com/openai/v1",
+  "severity": "HIGH"
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `findings` | yes | Array of finding objects from `POST /scan` |
+| `provider` | yes | `anthropic` \| `openai` \| `gemini` \| `ollama` |
+| `apiKey` | yes | Provider API key |
+| `model` | no | Defaults per provider (see [AI Remediation](ai-remediation.md)) |
+| `baseUrl` | no | Override base URL for any OpenAI-compatible service |
+| `severity` | no | Minimum severity to fix. Default: `LOW` (fix all) |
+
+**Response**
+```json
+{ "jobId": "job_1_1711363200000" }
+```
+
+---
+
+### `GET /jobs/:id`
+
+Poll for remediation job status.
+
+**Response — pending / running**
+```json
+{ "id": "job_1_...", "status": "pending", "createdAt": "..." }
+```
+
+**Response — done**
+```json
+{
+  "id":          "job_1_...",
+  "status":      "done",
+  "createdAt":   "...",
+  "startedAt":   "...",
+  "completedAt": "...",
+  "results": [
+    {
+      "finding":        { ... },
+      "status":         "remediated",
+      "exploitTest":    { "filename": "__tests__/security/xss.test.js", "content": "..." },
+      "patch":          { "filename": "src/app.js", "diff": "..." },
+      "refactorChecks": ["npm test", "npm run test:security"]
+    }
+  ]
+}
+```
+
+---
+
+## Examples
+
+### curl
+
+```bash
+# Start server
+npx @lhi/tdd-audit serve --port 3000 --api-key mysecret &
+
+# Scan current directory
+curl -s -X POST http://localhost:3000/scan \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d '{"path": "."}' | jq '.summary'
+
+# SARIF output for GitHub upload
+curl -s -X POST http://localhost:3000/scan \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d '{"path": ".", "format": "sarif"}' > results.sarif
+```
+
+### Node.js
+
+```javascript
+const res = await fetch('http://localhost:3000/scan', {
+  method:  'POST',
+  headers: {
+    'Authorization': 'Bearer mysecret',
+    'Content-Type':  'application/json',
+  },
+  body: JSON.stringify({ path: '/path/to/project' }),
+});
+const { findings, summary } = await res.json();
+console.log(`CRITICAL: ${summary.CRITICAL}  HIGH: ${summary.HIGH}`);
+```

package/index.js

@@ -11,13 +11,25 @@ const {
   quickScan,
   printFindings,
 } = require('./lib/scanner');
+const { toJson, toSarif, toText } = require('./lib/reporter');
+const { writeInitConfig } = require('./lib/config');
 
 const args = process.argv.slice(2);
-const isLocal = args.includes('--local');
-const isClaude = args.includes('--claude');
+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 skipScan  = args.includes('--skip-scan');
+const scanOnly  = args.includes('--scan-only') || args.includes('--scan');
+const isServe   = args[0] === 'serve';
+
+// --json or --format json → structured JSON output
+// --format sarif          → SARIF 2.1.0 output
+const formatIdx = args.indexOf('--format');
+const formatArg = formatIdx !== -1 ? args[formatIdx + 1] : null;
+const outputFormat = args.includes('--json') ? 'json'
+  : formatArg === 'sarif' ? 'sarif'
+  : formatArg === 'json'  ? 'json'
+  : 'text';
 
 const agentBaseDir = isLocal ? process.cwd() : os.homedir();
 const agentDirName = isClaude ? '.claude' : '.agents';
@@ -33,13 +45,46 @@ const framework = detectFramework(projectDir);
 const testBaseDir = detectTestBaseDir(projectDir, framework);
 const targetTestDir = path.join(projectDir, testBaseDir, 'security');
 
+// ─── Init mode early exit ────────────────────────────────────────────────────
+
+if (args[0] === 'init') {
+  const destArg = args[1] && !args[1].startsWith('-') ? args[1] : undefined;
+  const force   = args.includes('--force');
+  try {
+    const written = writeInitConfig(destArg, force);
+    console.log(`✅ Created ${path.relative(process.cwd(), written)}`);
+    console.log('   Edit it, then run: node index.js serve   or   node index.js --scan');
+  } catch (e) {
+    console.error(`❌ ${e.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ─── Serve mode early exit ────────────────────────────────────────────────────
+
+if (isServe) {
+  require('./lib/server').start(args);
+  return; // server stays alive — do not fall through to installer
+}
+
 // ─── Scan-only early exit ─────────────────────────────────────────────────────
 
 if (scanOnly) {
-  process.stdout.write('\n🔍 Scanning for vulnerability patterns...');
+  if (outputFormat !== 'text') process.stdout.write('\n🔍 Scanning...\n');
+  else process.stdout.write('\n🔍 Scanning for vulnerability patterns...');
   const findings = quickScan(projectDir);
-  process.stdout.write('\n');
-  printFindings(findings);
+  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);
+  }
   process.exit(0);
 }