@lhi/tdd-audit 1.8.3 → 1.9.0

package/README.md

@@ -1,182 +1,98 @@
 # @lhi/tdd-audit
 
-> **v1.8.3** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — you prove the hole exists, apply the fix, and prove it's closed.
+> **v1.9.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.
 
-## What happens on install
-
-Running the installer does five things immediately:
-
-1. **Scans your codebase** for 34 vulnerability patterns across OWASP Top 10, mobile, agentic AI, and prompt/skill files — prints a severity-ranked findings report to stdout
-2. **Scaffolds `__tests__/security/`** with a framework-matched boilerplate exploit test
-3. **Adds `test:security`** to your `package.json` scripts (Node.js projects)
-4. **Creates `.github/workflows/security-tests.yml`** so the CI gate exists from day one
-5. **Installs the `/tdd-audit` skill** for your AI coding agent
-
-## Installation
+## Install
 
 ```bash
 npx @lhi/tdd-audit
 ```
 
-Or clone and run directly:
+On first run the installer:
 
-```bash
-node index.js
-```
+1. Scans your codebase for **34 vulnerability patterns** 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
 
-### Platform-specific flags
-
-| Platform | Command |
-|---|---|
-| Claude Code | `npx @lhi/tdd-audit --local --claude` |
-| Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
-| With pre-commit hook | add `--with-hooks` |
-| Scan only (no install) | `npx @lhi/tdd-audit --scan` |
-
-### All flags
+### Flags
 
 | Flag | Description |
 |---|---|
-| `--local` | Install skill files into the current project instead of `~` |
-| `--claude` | Use `.claude/` instead of `.agents/` as the skill directory |
-| `--with-hooks` | Install a pre-commit hook that blocks commits if security tests fail |
-| `--skip-scan` | Skip the automatic vulnerability scan on install |
-| `--scan` / `--scan-only` | Run the vulnerability scan without installing anything |
+| `--local` | Install into the current project instead of `~` |
+| `--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 |
 
-### Framework detection
+### Platform
 
-The installer automatically detects your project's test framework and scaffolds the right boilerplate:
-
-| Detected | Boilerplate | `test:security` command |
-|---|---|---|
-| `jest` / `supertest` | `sample.exploit.test.js` | `jest --testPathPatterns=__tests__/security` |
-| `vitest` | `sample.exploit.test.vitest.js` | `vitest run __tests__/security` |
-| `mocha` | `sample.exploit.test.js` | `mocha '__tests__/security/**/*.spec.js'` |
-| `pytest.ini` / `pyproject.toml` | `sample.exploit.test.pytest.py` | `pytest tests/security/ -v` |
-| `go.mod` | `sample.exploit.test.go` | `go test ./security/... -v` |
-| `pubspec.yaml` | `sample_exploit_test.dart` | `flutter test test/security/` |
+| Platform | Command |
+|---|---|
+| Claude Code | `npx @lhi/tdd-audit --local --claude` |
+| Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
 
 ## Usage
 
-Once installed, trigger the autonomous audit in your agent:
-
 ```text
 /tdd-audit
 ```
 
-The agent will:
+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.
 
-1. Detect your tech stack and scope the scan to relevant patterns only
-2. Scan the codebase and present a severity-ranked findings report (CRITICAL / HIGH / MEDIUM / LOW)
-3. **Wait for your confirmation** before making any changes
-4. For each confirmed vulnerability, apply the full Red-Green-Refactor loop:
-   - **Red** — write an exploit test that fails, proving the vulnerability exists
-   - **Green** — apply the targeted patch, making the test pass
-   - **Refactor** — run the full suite to confirm no regressions
-5. Apply proactive hardening controls (security headers, rate limiting, `npm audit`, secret history scan)
-6. Deliver a final Remediation Summary table
-
-The agent works one vulnerability at a time and does not advance until the current one is fully proven closed.
-
-Pass `--scan` in your prompt to get the Audit Report only, without any code changes.
-
-## Vulnerability scanner
-
-The built-in scanner catches **34 patterns** across OWASP Top 10, mobile, agentic AI, and prompt/skill files:
-
-| Category | Patterns |
-|---|---|
-| Injection | SQL Injection, Command Injection, NoSQL Injection, Template Injection |
-| Broken Auth | JWT Alg None, Broken Auth, Timing-Unsafe Comparison, Hardcoded Secret, Secret Fallback |
-| XSS / Output | XSS, eval() Injection, Open Redirect |
-| Crypto | Weak Crypto (MD5/SHA1), Insecure Random, TLS Bypass |
-| Server-side | SSRF, Path Traversal, XXE, Insecure Deserialization |
-| Assignment | Mass Assignment, Prototype Pollution |
-| Mobile | Sensitive Storage, WebView JS Bridge, Deep Link Injection, Android Debuggable |
-| Config / Infra | CORS Wildcard, Cleartext Traffic, Config Secrets, ReDoS |
-| Agentic / Prompt | Deprecated CSRF Package (`csurf`), Unpinned npx MCP Server, Cleartext URL in Prompt |
-
-### Scanner behaviour
-
-- **Test files are flagged but labelled** — findings in `__tests__/`, `tests/`, `spec/`, or `*.test.*` files are shown with a `[test file]` badge. Patterns that mark `skipInTests: true` (e.g. Hardcoded Secret, Sensitive Log, Cleartext Traffic) are further tagged `likelyFalsePositive` and separated at the bottom of the report.
-- **Prompt/skill files get their own scan** — `.md` files inside `prompts/`, `skills/`, `.claude/`, `workflows/`, plus `CLAUDE.md` and `SKILL.md`, are scanned for prompt-specific anti-patterns. Matches inside backtick code spans are suppressed to avoid noise from documentation examples.
-- **`audit_status: safe` exemption** — any prompt file with `audit_status: safe` in its YAML frontmatter is skipped and listed separately so you can verify exemptions are intentional.
-- **Binary and oversized files skipped** — files larger than 512 KB or containing null bytes are skipped to prevent OOM.
-- **Symlinks skipped** — symlinks are never followed, preventing directory-escape on M-series Macs and shared filesystems.
-
-## Running security tests
+## REST API + AI remediation
 
 ```bash
-# Node.js
-npm run test:security
-
-# Python
-pytest tests/security/ -v
+# Start the API server
+npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
 
-# Go
-go test ./security/... -v
+# Scan any path → JSON
+curl -X POST http://localhost:3000/scan \
+  -H "Authorization: Bearer YOUR_SECRET" \
+  -d '{"path": "."}' | jq '.summary'
 
-# Flutter
-flutter test test/security/
+# Auto-fix with any AI provider
+npx @lhi/tdd-audit --scan --fix critical \
+  --provider anthropic --api-key $ANTHROPIC_API_KEY --json
 ```
 
-## CI/CD
-
-The installer creates framework-matched workflow files under `.github/workflows/`. Both `security-tests.yml` and `ci.yml` include:
-
-- SHA-pinned `uses:` references on every action (supply chain hardening)
-- `npm audit --audit-level=high` (or equivalent) to catch vulnerable dependencies
-- The security exploit test suite on every push and pull request
+Supported providers: `anthropic` · `openai` · `gemini` · `ollama` (local)
 
-To add the security gate to an existing pipeline manually:
+## Output formats
 
-```yaml
-- name: Dependency audit
-  run: npm audit --audit-level=high
-
-- name: Run security exploit tests
-  run: npm run test:security   # or pytest tests/security/, flutter test test/security/
+```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)
 ```
 
-## Pre-commit hook
+## Config file
 
-The `--with-hooks` flag appends a security gate to `.git/hooks/pre-commit`. Commits are blocked if any exploit test fails:
+`.tdd-audit.json` in your project root — all CLI flags can be set here:
 
+```json
+{
+  "port": 3000,
+  "output": "json",
+  "provider": "anthropic",
+  "apiKeyEnv": "ANTHROPIC_API_KEY",
+  "severityThreshold": "HIGH"
+}
 ```
-❌ Security tests failed. Commit blocked.
-```
-
-The hook is non-destructive — it appends to existing hook content rather than overwriting it.
-
-## Agentic AI security (ASI01–ASI10)
-
-When the project contains AI agent code, MCP configurations, or `CLAUDE.md` files, the scanner also checks for agentic-specific vulnerabilities:
-
-| ID | Vulnerability | Risk |
-|---|---|---|
-| ASI01 | Prompt injection via tool output | Malicious content in web/file reads hijacks agent behaviour |
-| ASI02 | CLAUDE.md / instructions file injection | Attacker-controlled system prompts override agent identity |
-| ASI03 | MCP server supply chain (unpinned `npx`) | Compromised package version exfiltrates secrets |
-| ASI04 | Excessive tool permissions | Agent can write files or run shell when only read is needed |
-| ASI05 | Secrets in tool call arguments | Tokens/passwords logged by external tools |
-| ASI06 | Unvalidated agent action execution | Agent runs irreversible actions without user confirmation |
-| ASI07 | Insecure direct agent communication | Sub-agent messages trusted without verification |
-| ASI08 | GitHub Actions command injection | `github.event.*` interpolated directly into `run:` steps |
-| ASI09 | Unpinned GitHub Actions (supply chain) | Mutable `@v4` / `@main` tags can be hijacked |
-| ASI10 | Secrets in workflow environment | Secrets printed to logs or embedded in curl URLs |
-
-See [`docs/agentic-ai-security.md`](docs/agentic-ai-security.md) for grep patterns, examples, and fixes.
 
 ## Documentation
 
-| File | Contents |
+| | |
 |---|---|
-| [`docs/scanner.md`](docs/scanner.md) | How the scanner works — architecture, detection logic, false-positive handling |
-| [`docs/vulnerability-patterns.md`](docs/vulnerability-patterns.md) | All 34 patterns with descriptions, grep signatures, and fix pointers |
-| [`docs/tdd-protocol.md`](docs/tdd-protocol.md) | The Red-Green-Refactor protocol in full, with framework templates |
-| [`docs/agentic-ai-security.md`](docs/agentic-ai-security.md) | ASI01–ASI10 agentic AI vulnerability reference |
-| [`docs/hardening.md`](docs/hardening.md) | Phase 4 proactive hardening controls |
-| [`docs/ci-cd.md`](docs/ci-cd.md) | CI/CD integration guide for all supported stacks |
+| [REST API](docs/rest-api.md) | Endpoints, auth, request/response schema, curl examples |
+| [AI Remediation](docs/ai-remediation.md) | Provider setup, CLI flags, Ollama local mode |
+| [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 |
+| [Hardening](docs/hardening.md) | Phase 4 controls — Helmet, CSP, CSRF, rate limiting, gitleaks, SRI |
+| [CI/CD](docs/ci-cd.md) | Workflow templates, existing pipeline integration, secret leak prevention |
 
 ## License
 

package/docs/ai-remediation.md

@@ -0,0 +1,107 @@
+# 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.
+
+---
+
+## CLI usage
+
+```bash
+# Scan and auto-fix all CRITICAL findings via Anthropic
+npx @lhi/tdd-audit --scan --fix critical \
+  --provider anthropic \
+  --api-key $ANTHROPIC_API_KEY
+
+# Fix everything, use a specific model
+npx @lhi/tdd-audit --scan --fix all \
+  --provider openai \
+  --model gpt-4o \
+  --api-key $OPENAI_API_KEY \
+  --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')
+
+# 2. Submit remediation job
+JOB=$(curl -s -X POST http://localhost:3000/remediate \
+  -H "Authorization: Bearer $SERVER_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"findings\": $FINDINGS, \"provider\": \"anthropic\", \"apiKey\": \"$ANTHROPIC_API_KEY\", \"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'
+```
+
+---
+
+## Supported providers
+
+| Provider | `--provider` | Default model | Key env var |
+|---|---|---|---|
+| Anthropic | `anthropic` | `claude-opus-4-6` | `ANTHROPIC_API_KEY` |
+| OpenAI | `openai` | `gpt-4o` | `OPENAI_API_KEY` |
+| Google Gemini | `gemini` | `gemini-2.0-flash` | `GEMINI_API_KEY` |
+| Ollama (local) | `ollama` | `llama3` | — |
+
+---
+
+## Config file
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-opus-4-6",
+  "apiKeyEnv": "ANTHROPIC_API_KEY"
+}
+```
+
+`apiKeyEnv` lets you name the environment variable to read the key from, so no key is ever written to disk.
+
+---
+
+## 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
+# Start Ollama with a code model
+ollama pull codellama
+ollama serve
+
+# Run tdd-audit against it
+npx @lhi/tdd-audit --scan --fix high \
+  --provider ollama \
+  --model codellama
+```
+
+No API key required. Ollama must be running on `http://localhost:11434`.

package/docs/rest-api.md

@@ -0,0 +1,188 @@
+# 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
+npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
+```
+
+Or via config file (`.tdd-audit.json` in your project root):
+
+```json
+{
+  "port": 3000,
+  "serverApiKey": "YOUR_SECRET",
+  "output": "json"
+}
+```
+
+If `--api-key` / `serverApiKey` is omitted the server starts unauthenticated with a warning. Always set one in production.
+
+---
+
+## Authentication
+
+All endpoints except `GET /health` require:
+
+```
+Authorization: Bearer YOUR_SECRET
+```
+
+Missing or wrong key → `401 Unauthorized`.
+
+---
+
+## Endpoints
+
+### `GET /health`
+
+No auth required.
+
+```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 cwd. |
+| `format` | `"json"` \| `"sarif"` | `"json"` | Output format |
+
+**Response — JSON format**
+```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 format**
+
+Returns a SARIF 2.1.0 object ready to upload to GitHub code scanning.
+
+**Errors**
+| Status | Reason |
+|---|---|
+| 400 | Missing path, path traversal attempt, or invalid JSON body |
+| 401 | Missing or invalid API key |
+
+---
+
+### `POST /remediate`
+
+Queue an AI-powered remediation job. Returns immediately with a `jobId`; poll `/jobs/:id` for results.
+
+**Request**
+```json
+{
+  "findings": [ ... ],
+  "provider": "anthropic",
+  "apiKey": "sk-ant-...",
+  "model": "claude-opus-4-6",
+  "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)) |
+| `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**
+```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"]
+    }
+  ]
+}
+```
+
+---
+
+## Example: scan from 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'
+
+# Get SARIF 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
+```
+
+---
+
+## Example: scan from 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,24 @@ const {
   quickScan,
   printFindings,
 } = require('./lib/scanner');
+const { toJson, toSarif, toText } = require('./lib/reporter');
 
 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 +44,30 @@ const framework = detectFramework(projectDir);
 const testBaseDir = detectTestBaseDir(projectDir, framework);
 const targetTestDir = path.join(projectDir, testBaseDir, 'security');
 
+// ─── 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);
 }
 

package/lib/config.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const CONFIG_FILE = '.tdd-audit.json';
+
+const DEFAULTS = {
+  port:             3000,
+  output:           'text',     // 'text' | 'json' | 'sarif'
+  severityThreshold:'LOW',      // minimum severity to include in output
+  ignore:           [],         // path prefixes to skip
+  provider:         null,       // 'anthropic' | 'openai' | 'gemini' | 'ollama'
+  model:            null,
+  apiKey:           null,
+  apiKeyEnv:        null,       // env var name to read the key from
+  serverApiKey:     null,       // key required on REST API calls
+};
+
+/**
+ * Load .tdd-audit.json from cwd (or a given dir), merge with DEFAULTS.
+ * CLI flags (passed as an object) win over file config.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {object} [cliOverrides={}]
+ * @returns {object}
+ */
+function loadConfig(cwd = process.cwd(), cliOverrides = {}) {
+  let fileConfig = {};
+  const filePath = path.join(cwd, CONFIG_FILE);
+  if (fs.existsSync(filePath)) {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      fileConfig = JSON.parse(raw);
+    } catch (err) {
+      process.stderr.write(`⚠️  Could not parse ${CONFIG_FILE}: ${err.message}\n`);
+    }
+  }
+
+  const merged = { ...DEFAULTS, ...fileConfig };
+
+  // CLI overrides — only set keys that were explicitly provided
+  for (const [key, val] of Object.entries(cliOverrides)) {
+    if (val !== undefined && val !== null) merged[key] = val;
+  }
+
+  // Resolve apiKey from env var if apiKeyEnv is set and apiKey isn't already
+  if (!merged.apiKey && merged.apiKeyEnv) {
+    merged.apiKey = process.env[merged.apiKeyEnv] || null;
+  }
+
+  return merged;
+}
+
+/**
+ * Parse relevant CLI args into an overrides object for loadConfig.
+ * @param {string[]} args - process.argv.slice(2)
+ * @returns {object}
+ */
+function parseCliOverrides(args) {
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    return i !== -1 ? args[i + 1] : undefined;
+  };
+  const overrides = {};
+  const port      = get('--port');      if (port)     overrides.port = Number(port);
+  const provider  = get('--provider'); if (provider) overrides.provider = provider;
+  const model     = get('--model');    if (model)    overrides.model = model;
+  const apiKey    = get('--api-key');  if (apiKey)   overrides.apiKey = apiKey;
+  const format    = get('--format');   if (format)   overrides.output = format;
+  const srvKey    = get('--api-key');  if (srvKey)   overrides.serverApiKey = srvKey;
+  if (args.includes('--json')) overrides.output = 'json';
+  return overrides;
+}
+
+module.exports = { loadConfig, parseCliOverrides, DEFAULTS, CONFIG_FILE };

package/lib/github.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// ─── GitHub REST helpers ──────────────────────────────────────────────────────
+
+async function ghFetch(path, token, method = 'GET', body = null) {
+  const opts = {
+    method,
+    headers: {
+      'Accept':        'application/vnd.github+json',
+      'Authorization': `Bearer ${token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'Content-Type':  'application/json',
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+  const res = await fetch(`https://api.github.com${path}`, opts);
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${method} ${path} → ${res.status}: ${text.slice(0, 200)}`);
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+// ─── SARIF upload ─────────────────────────────────────────────────────────────
+
+/**
+ * Upload a SARIF report to GitHub code scanning.
+ * Findings will appear inline in PRs and the Security tab.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.token   - GitHub token with `security_events` write scope
+ * @param {string} opts.ref     - full git ref, e.g. "refs/heads/main"
+ * @param {string} opts.commitSha
+ * @param {object} opts.sarif   - SARIF 2.1.0 object from toSarif()
+ * @returns {Promise<object>}
+ */
+async function uploadSarif({ owner, repo, token, ref, commitSha, sarif }) {
+  const encoded = Buffer.from(JSON.stringify(sarif)).toString('base64');
+  return ghFetch(`/repos/${owner}/${repo}/code-scanning/sarifs`, token, 'POST', {
+    ref,
+    commit_sha: commitSha,
+    sarif:      encoded,
+    tool_name:  '@lhi/tdd-audit',
+  });
+}
+
+// ─── PR review comments ───────────────────────────────────────────────────────
+
+/**
+ * Post inline review comments on a pull request for each finding.
+ * CRITICAL and HIGH findings request changes; others leave comments only.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {number} opts.pull_number
+ * @param {string} opts.token
+ * @param {string} opts.commitSha  - head SHA of the PR
+ * @param {Array}  opts.findings
+ * @returns {Promise<object>} - GitHub review object
+ */
+async function postReviewComments({ owner, repo, pull_number, token, commitSha, findings }) {
+  const real = findings.filter(f => !f.likelyFalsePositive);
+  if (!real.length) return null;
+
+  const hasCritical = real.some(f => f.severity === 'CRITICAL' || f.severity === 'HIGH');
+
+  const comments = real.map(f => ({
+    path:     f.file,
+    line:     f.line,
+    side:     'RIGHT',
+    body:     `**[${f.severity}] ${f.name}**\n\`\`\`\n${f.snippet}\n\`\`\`\nRun \`/tdd-audit\` to remediate.`,
+  }));
+
+  return ghFetch(`/repos/${owner}/${repo}/pulls/${pull_number}/reviews`, token, 'POST', {
+    commit_id: commitSha,
+    body:      `**@lhi/tdd-audit** found ${real.length} issue(s). ${hasCritical ? 'CRITICAL/HIGH findings require changes.' : 'See inline comments.'}`,
+    event:     hasCritical ? 'REQUEST_CHANGES' : 'COMMENT',
+    comments,
+  });
+}
+
+// ─── Parse "owner/repo" helper ────────────────────────────────────────────────
+
+function parseRepo(repoStr) {
+  const [owner, repo] = (repoStr || '').split('/');
+  if (!owner || !repo) throw new Error('--repo must be in "owner/repo" format');
+  return { owner, repo };
+}
+
+module.exports = { uploadSarif, postReviewComments, parseRepo };

package/lib/remediator.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// ─── Provider endpoints ───────────────────────────────────────────────────────
+
+const PROVIDERS = {
+  anthropic: {
+    url:     'https://api.anthropic.com/v1/messages',
+    headers: (apiKey) => ({
+      'Content-Type':      'application/json',
+      'x-api-key':         apiKey,
+      'anthropic-version': '2023-06-01',
+    }),
+    body: (model, prompt) => ({
+      model:      model || 'claude-opus-4-6',
+      max_tokens: 8192,
+      messages:   [{ role: 'user', content: prompt }],
+    }),
+    extract: (data) => data?.content?.[0]?.text || '',
+  },
+  openai: {
+    url:     'https://api.openai.com/v1/chat/completions',
+    headers: (apiKey) => ({
+      'Content-Type':  'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    }),
+    body: (model, prompt) => ({
+      model:    model || 'gpt-4o',
+      messages: [{ role: 'user', content: prompt }],
+    }),
+    extract: (data) => data?.choices?.[0]?.message?.content || '',
+  },
+  gemini: {
+    url:     (apiKey) => `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`,
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    body: (model, prompt) => ({
+      contents: [{ parts: [{ text: prompt }] }],
+    }),
+    extract: (data) => data?.candidates?.[0]?.content?.parts?.[0]?.text || '',
+  },
+  ollama: {
+    url:     'http://localhost:11434/api/generate',
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    body: (model, prompt) => ({
+      model:  model || 'llama3',
+      prompt,
+      stream: false,
+    }),
+    extract: (data) => data?.response || '',
+  },
+};
+
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+
+function buildRemediationPrompt(finding) {
+  return `You are a security engineer applying the Red-Green-Refactor TDD remediation protocol.
+
+VULNERABILITY FINDING:
+- Type: ${finding.name}
+- Severity: ${finding.severity}
+- File: ${finding.file}
+- Line: ${finding.line}
+- Code snippet: ${finding.snippet}
+
+TASK:
+1. Write a Jest/supertest exploit test (Red phase) that proves this vulnerability exists.
+   The test must be placed in __tests__/security/ and must FAIL before the fix.
+2. Write the minimum code patch (Green phase) that closes the vulnerability.
+   Show it as a unified diff against the original file.
+3. Confirm what regression checks to run (Refactor phase).
+
+Respond with valid JSON in exactly this shape:
+{
+  "exploitTest": {
+    "filename": "__tests__/security/<slug>.test.js",
+    "content": "<full test file content>"
+  },
+  "patch": {
+    "filename": "<path to file being patched>",
+    "diff": "<unified diff>"
+  },
+  "refactorChecks": ["<check 1>", "<check 2>"]
+}`;
+}
+
+// ─── HTTP call ────────────────────────────────────────────────────────────────
+
+async function callProvider(provider, apiKey, model, prompt) {
+  const p = PROVIDERS[provider];
+  if (!p) throw new Error(`Unknown provider "${provider}". Supported: ${Object.keys(PROVIDERS).join(', ')}`);
+
+  const url     = typeof p.url === 'function' ? p.url(apiKey) : p.url;
+  const headers = p.headers(apiKey);
+  const body    = JSON.stringify(p.body(model, prompt));
+
+  const res = await fetch(url, { method: 'POST', headers, body });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Provider ${provider} returned ${res.status}: ${text.slice(0, 200)}`);
+  }
+  const data = await res.json();
+  return p.extract(data);
+}
+
+// ─── Parse model response ─────────────────────────────────────────────────────
+
+function parseResponse(text) {
+  // Extract JSON from response (model may wrap it in markdown)
+  const match = text.match(/\{[\s\S]*\}/);
+  if (!match) throw new Error('Model response did not contain a JSON object');
+  return JSON.parse(match[0]);
+}
+
+// ─── Main remediate function ──────────────────────────────────────────────────
+
+/**
+ * Run AI-powered remediation for a list of findings.
+ *
+ * @param {object} opts
+ * @param {Array}  opts.findings  - finding objects from quickScan
+ * @param {string} opts.provider  - 'anthropic' | 'openai' | 'gemini' | 'ollama'
+ * @param {string} opts.apiKey
+ * @param {string} [opts.model]
+ * @param {string} [opts.severity] - minimum severity to fix ('CRITICAL','HIGH','MEDIUM','LOW')
+ * @returns {Promise<Array>} - results per finding
+ */
+async function remediate({ findings, provider, apiKey, model, severity = 'LOW' }) {
+  const ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+  const threshold = ORDER[severity.toUpperCase()] ?? 3;
+
+  const targets = findings
+    .filter(f => !f.likelyFalsePositive && (ORDER[f.severity] ?? 99) <= threshold)
+    .sort((a, b) => (ORDER[a.severity] ?? 99) - (ORDER[b.severity] ?? 99));
+
+  const results = [];
+  for (const finding of targets) {
+    try {
+      const prompt   = buildRemediationPrompt(finding);
+      const raw      = await callProvider(provider, apiKey, model, prompt);
+      const parsed   = parseResponse(raw);
+      results.push({ finding, status: 'remediated', ...parsed });
+    } catch (err) {
+      results.push({ finding, status: 'error', error: err.message });
+    }
+  }
+  return results;
+}
+
+module.exports = { remediate, callProvider, buildRemediationPrompt, PROVIDERS };

package/lib/reporter.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const { version } = require('../package.json');
+
+// ─── JSON ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Return findings as a structured JSON-serialisable object.
+ * @param {Array}    findings
+ * @param {string[]} [exempted=[]]
+ * @returns {object}
+ */
+function toJson(findings, exempted = []) {
+  const real  = findings.filter(f => !f.likelyFalsePositive);
+  const noisy = findings.filter(f =>  f.likelyFalsePositive);
+
+  const summary = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+  for (const f of real) summary[f.severity] = (summary[f.severity] || 0) + 1;
+
+  return {
+    version,
+    summary,
+    findings: real,
+    likelyFalsePositives: noisy,
+    exempted,
+    scannedAt: new Date().toISOString(),
+  };
+}
+
+// ─── SARIF ────────────────────────────────────────────────────────────────────
+
+const SARIF_LEVEL = { CRITICAL: 'error', HIGH: 'error', MEDIUM: 'warning', LOW: 'note' };
+
+// Maps our vuln names to CWE IDs for richer GitHub annotations
+const CWE_MAP = {
+  'SQL Injection':             'CWE-89',
+  'Command Injection':         'CWE-78',
+  'Path Traversal':            'CWE-22',
+  'XSS':                       'CWE-79',
+  'IDOR':                      'CWE-639',
+  'Broken Auth':               'CWE-287',
+  'Hardcoded Secret':          'CWE-798',
+  'SSRF':                      'CWE-918',
+  'Open Redirect':             'CWE-601',
+  'NoSQL Injection':           'CWE-943',
+  'Mass Assignment':           'CWE-915',
+  'Prototype Pollution':       'CWE-1321',
+  'Weak Crypto':               'CWE-327',
+  'Insecure Deserialization':  'CWE-502',
+  'TLS Bypass':                'CWE-295',
+  'Sensitive Storage':         'CWE-312',
+  'JWT Alg None':              'CWE-347',
+  'Secret Fallback':           'CWE-798',
+  'eval() Injection':          'CWE-95',
+  'Template Injection':        'CWE-94',
+  'ReDoS':                     'CWE-1333',
+  'XXE':                       'CWE-611',
+  'CORS Wildcard':             'CWE-942',
+  'Insecure Random':           'CWE-338',
+  'Timing-Unsafe Comparison':  'CWE-208',
+};
+
+/**
+ * Return findings as a SARIF 2.1.0 object (GitHub code scanning compatible).
+ * @param {Array}  findings
+ * @param {string} [projectDir='']  - used to build relative artifact URIs
+ * @returns {object}
+ */
+function toSarif(findings, projectDir = '') {
+  const rules = [];
+  const ruleIndex = {};
+
+  const results = findings.filter(f => !f.likelyFalsePositive).map(f => {
+    if (ruleIndex[f.name] === undefined) {
+      ruleIndex[f.name] = rules.length;
+      const cwe = CWE_MAP[f.name];
+      rules.push({
+        id: f.name.replace(/\s+/g, '-').replace(/[()]/g, '').toLowerCase(),
+        name: f.name,
+        shortDescription: { text: f.name },
+        fullDescription:  { text: `${f.name} detected — severity: ${f.severity}` },
+        defaultConfiguration: { level: SARIF_LEVEL[f.severity] || 'warning' },
+        ...(cwe && { relationships: [{ target: { id: cwe, toolComponent: { name: 'CWE' } } }] }),
+        helpUri: `https://cwe.mitre.org/data/definitions/${cwe ? cwe.replace('CWE-', '') : '0'}.html`,
+      });
+    }
+
+    return {
+      ruleId:    rules[ruleIndex[f.name]].id,
+      ruleIndex: ruleIndex[f.name],
+      level:     SARIF_LEVEL[f.severity] || 'warning',
+      message:   { text: f.snippet || f.name },
+      locations: [{
+        physicalLocation: {
+          artifactLocation: {
+            uri:       f.file.replace(/\\/g, '/'),
+            uriBaseId: '%SRCROOT%',
+          },
+          region: { startLine: f.line },
+        },
+      }],
+    };
+  });
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name:            '@lhi/tdd-audit',
+          version,
+          informationUri:  'https://www.npmjs.com/package/@lhi/tdd-audit',
+          rules,
+        },
+      },
+      results,
+    }],
+  };
+}
+
+// ─── Text (existing printFindings extracted for reuse) ────────────────────────
+
+/**
+ * Return a human-readable text report string (without printing it).
+ * @param {Array}    findings
+ * @param {string[]} [exempted=[]]
+ * @returns {string}
+ */
+function toText(findings, exempted = []) {
+  const lines = [];
+  if (findings.length === 0) {
+    lines.push('   ✅ No obvious vulnerability patterns detected.\n');
+  } else {
+    const real  = findings.filter(f => !f.likelyFalsePositive);
+    const noisy = findings.filter(f =>  f.likelyFalsePositive);
+    const bySeverity = { CRITICAL: [], HIGH: [], MEDIUM: [], LOW: [] };
+    for (const f of real) (bySeverity[f.severity] || bySeverity.LOW).push(f);
+    const icons = { CRITICAL: '🔴', HIGH: '🟠', MEDIUM: '🟡', LOW: '🔵' };
+
+    lines.push(`\n   Found ${real.length} potential issue(s)${noisy.length ? ` (+${noisy.length} in test files — see below)` : ''}:\n`);
+    for (const [sev, list] of Object.entries(bySeverity)) {
+      if (!list.length) continue;
+      for (const f of list) {
+        const badge = f.inTestFile ? ' [test file]' : '';
+        lines.push(`   ${icons[sev]} [${sev}] ${f.name} — ${f.file}:${f.line}${badge}`);
+        lines.push(`         ${f.snippet}`);
+      }
+    }
+    if (noisy.length) {
+      lines.push('\n   ⚪ Likely intentional (in test files — verify manually):');
+      for (const f of noisy) lines.push(`      ${f.name} — ${f.file}:${f.line}`);
+    }
+    lines.push('\n   Run /tdd-audit in your agent to remediate.\n');
+  }
+  if (exempted.length) {
+    lines.push('   ⚠️  Files skipped via audit_status:safe (verify these exemptions are intentional):');
+    for (const p of exempted) lines.push(`      ${p}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+module.exports = { toJson, toSarif, toText };

package/lib/server.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const http  = require('http');
+const path  = require('path');
+const { quickScan, scanPromptFiles } = require('./scanner');
+const { toJson, toSarif, toText }    = require('./reporter');
+const { loadConfig, parseCliOverrides } = require('./config');
+const { version } = require('../package.json');
+
+// ─── Job store (in-memory) ────────────────────────────────────────────────────
+
+const jobs = new Map();
+let jobSeq = 0;
+
+function createJob() {
+  const id = `job_${++jobSeq}_${Date.now()}`;
+  jobs.set(id, { id, status: 'pending', createdAt: new Date().toISOString() });
+  return id;
+}
+
+function updateJob(id, patch) {
+  const job = jobs.get(id);
+  if (job) jobs.set(id, { ...job, ...patch });
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'Content-Type':  'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', chunk => {
+      data += chunk;
+      if (data.length > 1024 * 512) reject(new Error('Request body too large'));
+    });
+    req.on('end', () => {
+      try { resolve(JSON.parse(data || '{}')); }
+      catch { reject(new Error('Invalid JSON body')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Authenticate incoming requests.
+ * If serverApiKey is set, require `Authorization: Bearer <key>`.
+ */
+function authenticate(req, cfg) {
+  if (!cfg.serverApiKey) return true; // no key configured — open
+  const header = req.headers['authorization'] || '';
+  const token  = header.startsWith('Bearer ') ? header.slice(7) : '';
+  return token === cfg.serverApiKey;
+}
+
+/**
+ * Validate and sanitise the `path` field from POST /scan.
+ * Only allow paths inside cwd to prevent path traversal.
+ */
+function safeScanPath(rawPath) {
+  const cwd      = process.cwd();
+  const resolved = path.resolve(cwd, rawPath || cwd);
+  if (!resolved.startsWith(cwd)) throw new Error('Path outside working directory');
+  return resolved;
+}
+
+// ─── Router ───────────────────────────────────────────────────────────────────
+
+async function handleRequest(req, res, cfg) {
+  const { method, url } = req;
+
+  // ── GET /health ────────────────────────────────────────────────────────────
+  if (method === 'GET' && url === '/health') {
+    return json(res, 200, { status: 'ok', version });
+  }
+
+  // All other routes require authentication
+  if (!authenticate(req, cfg)) {
+    return json(res, 401, { error: 'Unauthorized' });
+  }
+
+  // ── POST /scan ─────────────────────────────────────────────────────────────
+  if (method === 'POST' && url === '/scan') {
+    let body;
+    try { body = await readBody(req); }
+    catch (e) { return json(res, 400, { error: e.message }); }
+
+    let scanPath;
+    try { scanPath = safeScanPath(body.path); }
+    catch (e) { return json(res, 400, { error: e.message }); }
+
+    const format  = body.format || cfg.output || 'json';
+    const t0      = Date.now();
+    const findings = quickScan(scanPath);
+    const exempted = findings.exempted || [];
+    const duration = Date.now() - t0;
+
+    if (format === 'sarif') {
+      return json(res, 200, toSarif(findings, scanPath));
+    }
+    return json(res, 200, { ...toJson(findings, exempted), duration });
+  }
+
+  // ── POST /remediate ────────────────────────────────────────────────────────
+  if (method === 'POST' && url === '/remediate') {
+    let body;
+    try { body = await readBody(req); }
+    catch (e) { return json(res, 400, { error: e.message }); }
+
+    const { findings, provider, apiKey, model } = body;
+    if (!findings || !provider || !apiKey) {
+      return json(res, 400, { error: 'findings, provider, and apiKey are required' });
+    }
+
+    const jobId = createJob();
+
+    // Kick off async remediation (non-blocking)
+    setImmediate(async () => {
+      try {
+        updateJob(jobId, { status: 'running', startedAt: new Date().toISOString() });
+        const { remediate } = require('./remediator');
+        const results = await remediate({ findings, provider, apiKey, model: model || cfg.model });
+        updateJob(jobId, { status: 'done', completedAt: new Date().toISOString(), results });
+      } catch (err) {
+        updateJob(jobId, { status: 'error', error: err.message });
+      }
+    });
+
+    return json(res, 202, { jobId });
+  }
+
+  // ── GET /jobs/:id ──────────────────────────────────────────────────────────
+  const jobMatch = url.match(/^\/jobs\/([^/?]+)$/);
+  if (method === 'GET' && jobMatch) {
+    const job = jobs.get(jobMatch[1]);
+    if (!job) return json(res, 404, { error: 'Job not found' });
+    return json(res, 200, job);
+  }
+
+  return json(res, 404, { error: 'Not found' });
+}
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+function start(args = []) {
+  const cfg  = loadConfig(process.cwd(), parseCliOverrides(args));
+  const port = cfg.port;
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      await handleRequest(req, res, cfg);
+    } catch (err) {
+      // Production error handler — no stack traces
+      json(res, 500, { error: 'Internal server error' });
+    }
+  });
+
+  server.listen(port, () => {
+    process.stdout.write(`\n🔒 tdd-audit REST API listening on http://localhost:${port}\n`);
+    if (!cfg.serverApiKey) {
+      process.stderr.write('⚠️  No --api-key set — server is unauthenticated. Set one for production.\n');
+    }
+    process.stdout.write('   GET  /health\n');
+    process.stdout.write('   POST /scan        { path, format? }\n');
+    process.stdout.write('   POST /remediate   { findings, provider, apiKey, model? }\n');
+    process.stdout.write('   GET  /jobs/:id\n\n');
+  });
+
+  return server; // returned for testing
+}
+
+module.exports = { start, jobs, createJob, updateJob, safeScanPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lhi/tdd-audit",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "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": {