@lhi/tdd-audit 1.16.0 → 1.20.0

package/docs/configuration.md

@@ -0,0 +1,236 @@
+# Configuration Reference
+
+All `tdd-audit` behaviour is controlled by `.tdd-audit.json` at your repo root. CLI flags override file config; file config overrides built-in defaults.
+
+Generate a starter file:
+```bash
+npx @lhi/tdd-audit@latest init
+npx @lhi/tdd-audit@latest init --provider anthropic
+```
+
+---
+
+## Full schema
+
+```jsonc
+{
+  // ── Core ──────────────────────────────────────────────────────────────────
+  "output":            "text",      // "text" | "json" | "sarif" | "report"
+  "severityThreshold": "LOW",       // minimum severity to include: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
+  "ignore":            [],          // path prefixes to skip: ["node_modules", "dist"]
+  "port":              3000,        // port for `tdd-audit serve`
+  "serverApiKey":      null,        // required on REST API calls; falls back to TDD_AUDIT_API_KEY env var
+
+  // ── AI provider ───────────────────────────────────────────────────────────
+  "provider":  "anthropic",         // "anthropic" | "openai" | "gemini" | "ollama"
+  "model":     "claude-opus-4-6",
+  "apiKeyEnv": "ANTHROPIC_API_KEY", // env var to read the key from
+  "baseUrl":   null,                // override for OpenAI-compatible providers
+
+  // ── Branding ──────────────────────────────────────────────────────────────
+  // For wrapper/rebranded distributions. See docs/extensibility.md.
+  "org":          "Daily Caller",
+  "project":      "my-project",
+  "badge_label":       "dc-audit",                   // replaces "tdd-audit" in the shields.io badge
+  "tdd_site":          "https://security.example.com", // replaces npm link in badge + SARIF
+  "security_name":     "Alice Smith",                   // name of the security contact — stamped into SECURITY.md, compliance reports, and webhook payloads
+  "security_email":    "security@example.com",           // email for the vulnerability reporting address in SECURITY.md and payloads
+
+  // ── Policy as code ────────────────────────────────────────────────────────
+  // Override the default severity for any named pattern.
+  // Useful when a pattern's default severity doesn't match your org's risk model.
+  "severity_overrides": {
+    "CORS Wildcard":   "CRITICAL",  // default: MEDIUM
+    "Sensitive Log":   "HIGH",      // default: MEDIUM
+    "Cleartext Traffic": "HIGH"     // default: MEDIUM
+  },
+
+  // ── Notifications ─────────────────────────────────────────────────────────
+  // Fired when a scan completes. Both can be set simultaneously.
+  "webhook_url":   "https://hooks.example.com/tdd-audit",
+  // POST body: { project, timestamp, summary: { critical, high, medium, low }, findings: [...] }
+
+  "slack_webhook": "https://hooks.slack.com/services/...",
+  "slack_channel": "#security",     // optional override; uses webhook default if absent
+
+  // ── Workflow integration ───────────────────────────────────────────────────
+  "open_pr":      true,   // open a GitHub PR per finding instead of committing directly
+  "github_token": null,   // falls back to GITHUB_TOKEN env var
+  "github_repo":  null,   // "owner/repo" — auto-detected from git remote if null
+
+  // ── CI / scheduled modes ──────────────────────────────────────────────────
+  "pr_mode":   false,     // lightweight static scan only — fast, designed for PR gates
+  "org_scan":  null,      // "my-github-org" — scan all repos in the org
+  "schedule":  null,      // cron expression for external schedulers: "0 2 * * *"
+
+  // ── Output additions ──────────────────────────────────────────────────────
+  "sbom":   false,    // generate CycloneDX SBOM alongside the audit
+  "report": false,    // generate human-readable compliance report (markdown)
+  "watch":  false,    // re-scan affected files on save (watch mode)
+
+  // ── Secret rotation ───────────────────────────────────────────────────────
+  "rotate_secrets": false,  // when a hardcoded key is detected, prompt to rotate via provider API
+
+  // ── Extensibility ─────────────────────────────────────────────────────────
+  // See docs/extensibility.md for full documentation.
+  "pattern_repos":    [],
+  "extra_skill_dirs": [],
+  "extra_repos":      [],
+  "mcp_services":     [],
+  "extra_domains":    []
+}
+```
+
+---
+
+## CLI flag equivalents
+
+| Config key | CLI flag |
+|---|---|
+| `output: "json"` | `--json` or `--format json` |
+| `output: "sarif"` | `--format sarif` |
+| `output: "report"` | `--format report` |
+| `pr_mode: true` | `--pr` |
+| `org_scan: "myorg"` | `--org myorg` |
+| `open_pr: true` | `--open-pr` |
+| `sbom: true` | `--sbom` |
+| `watch: true` | `--watch` |
+| `report: true` | `--report` |
+| `rotate_secrets: true` | `--rotate-secrets` |
+| `provider: "openai"` | `--provider openai` |
+| `model: "gpt-4o"` | `--model gpt-4o` |
+| `severityThreshold: "HIGH"` | `--threshold HIGH` |
+
+CLI flags always win over file config.
+
+---
+
+## Policy as code
+
+`severity_overrides` lets you redefine what severity means for your org without forking the scanner. The key is the exact pattern name from the [vulnerability patterns reference](./vulnerability-patterns.md).
+
+```json
+"severity_overrides": {
+  "CORS Wildcard": "CRITICAL"
+}
+```
+
+This is applied before findings are reported, before notifications fire, and before PR gates are evaluated. A pattern overridden to `CRITICAL` will block a PR merge just like any built-in CRITICAL.
+
+---
+
+## Notifications
+
+Both `webhook_url` and `slack_webhook` fire after every scan (CLI, `--ai`, and `POST /scan`).
+
+**Webhook payload:**
+```json
+{
+  "project":   "my-project",
+  "org":       "My Org",
+  "timestamp": "2026-03-26T12:00:00Z",
+  "duration_ms": 4200,
+  "summary":   { "critical": 1, "high": 3, "medium": 2, "low": 0 },
+  "findings":  [ ... ]
+}
+```
+
+**Slack message format:**
+```
+🔴 tdd-audit — my-project
+1 critical · 3 high · 2 medium
+Run /caller-audit to remediate.
+```
+
+---
+
+## PR mode (`--pr`)
+
+Designed for CI PR gates. Runs only the static scanner — no AI agents, no RAG, no fixes. Completes in under a second.
+
+```yaml
+- run: npx @lhi/tdd-audit@latest --pr --threshold HIGH
+```
+
+Exits non-zero if any finding meets or exceeds `severityThreshold`. Wire into your branch protection rules to block merges automatically.
+
+Use `severity_overrides` to tune what counts as a blocker for your stack.
+
+---
+
+## Auto-fix PR (`--open-pr`)
+
+Instead of committing fixes directly to the working branch, opens a GitHub PR per finding. Each PR contains:
+- The exploit test (Red)
+- The patch (Green)
+- A description linking to the vulnerability pattern
+
+Requires `GITHUB_TOKEN` in the environment or `github_token` in config.
+
+---
+
+## Watch mode (`--watch`)
+
+```bash
+npx @lhi/tdd-audit@latest --watch
+```
+
+Re-runs the static scanner on any modified file on save. Reports new findings immediately in the terminal. Does not run agents or apply fixes — use `/caller-audit` for that.
+
+---
+
+## SBOM (`--sbom`)
+
+Generates a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials in JSON format alongside the audit report. Output to `sbom.json` in the project root.
+
+Required for US federal contracts (EO 14028), increasingly required in enterprise vendor questionnaires.
+
+---
+
+## Compliance report (`--format report` / `--report`)
+
+Generates a markdown report suitable for attaching to a SOC 2 audit, ISO 27001 evidence package, or vendor security questionnaire. Includes:
+
+- Findings summary table (severity, location, status)
+- Fix evidence (exploit test name, patch commit, suite result)
+- Coverage gate result
+- Hardening controls applied
+- SBOM reference (if generated)
+- Timestamp and auditor (org/project from config)
+
+---
+
+## Org scan (`--org`)
+
+```bash
+npx @lhi/tdd-audit@latest --org my-github-org --format report
+```
+
+Discovers all repos in a GitHub org, runs `--pr` mode on each, and produces a cross-org summary:
+
+```
+my-github-org security posture — 2026-03-26
+
+✅ repo-a     0 critical · 0 high
+⚠️  repo-b     0 critical · 2 high
+🔴 repo-c     1 critical · 4 high
+
+3 repos scanned · 1 critical · 6 high total
+```
+
+Fires `webhook_url` and `slack_webhook` with the aggregate payload if configured.
+
+---
+
+## Secret rotation (`--rotate-secrets`)
+
+When a hardcoded API key is detected, prompts to rotate it via the provider's API. Supported providers:
+
+| Secret type | Rotation method |
+|---|---|
+| OpenAI key (`sk-...`) | OpenAI API — revoke + generate new key |
+| Anthropic key (`sk-ant-...`) | Anthropic console link + clipboard |
+| GitHub token | GitHub API — revoke token |
+| Supabase service key | Supabase API — regenerate |
+
+After rotation, updates the relevant `.env` file and removes the hardcoded value from source. The old key is invalidated whether you commit the change or not.

package/docs/rest-api.md

@@ -1,6 +1,6 @@
 # REST API
 
-`tdd-audit serve` turns the scanner into an authenticated HTTP API built on **Fastify**. Use it to integrate vulnerability scanning and AI remediation into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
+`tdd-audit serve` exposes an authenticated HTTP API built on **Fastify**. Use it to integrate AI-powered security audits into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
 
 ---
 
@@ -59,7 +59,7 @@ By default the rate limiter keys on the **socket IP**, not `X-Forwarded-For`, to
 
 ### Path validation
 
-`POST /scan` and `POST /audit` validate that the requested path is inside the server's working directory. The check is normalised with a trailing path separator to prevent sibling-directory prefix bypasses (e.g. `/app-evil` cannot escape via `/app`). Paths outside cwd return `400`.
+`POST /audit` and `POST /audit/ai` validate that the requested path is inside the server's working directory. The check is normalised with a trailing path separator to prevent sibling-directory prefix bypasses (e.g. `/app-evil` cannot escape via `/app`). Paths outside cwd return `400`.
 
 ### Security headers
 
@@ -80,60 +80,117 @@ X-Frame-Options:         DENY
 No auth required. Returns server status and version.
 
 ```json
-{ "status": "ok", "version": "1.13.0" }
+{ "status": "ok", "version": "1.17.0" }
 ```
 
 ---
 
-### `POST /scan`
+### `POST /audit/ai`
 
-Scan a local path and return structured findings synchronously.
+**The primary endpoint.** Runs a full agentic LLM audit using tool calls (`read_file`, `list_files`, `search_in_files`, `write_file`). Returns immediately with a `jobId`; poll `GET /jobs/:id` or stream `GET /jobs/:id/stream` for results.
+
+Provider and API key can be supplied in the request body or pre-configured in `.tdd-audit.json`.
 
 **Request**
 ```json
 {
-  "path":   ".",
-  "format": "json"
+  "path":     ".",
+  "provider": "anthropic",
+  "apiKey":   "sk-ant-...",
+  "model":    "claude-opus-4-6",
+  "baseUrl":  null,
+  "depth":    "tier-2"
 }
 ```
 
-| Field | Type | Default | Description |
+| Field | Required | Default | Description |
 |---|---|---|---|
-| `path` | string | cwd | Absolute or relative path to scan. Must be inside server cwd. |
-| `format` | `"json"` \| `"sarif"` | `"json"` | Output format |
+| `path` | no | cwd | Path to audit. Must be inside server cwd. |
+| `provider` | yes* | cfg | `anthropic` \| `openai` \| `gemini` \| `ollama` |
+| `apiKey` | yes* | cfg | Provider API key |
+| `model` | no | provider default | Model override |
+| `baseUrl` | no | — | Base URL for OpenAI-compatible services |
+| `depth` | no | `tier-1` | Output depth tier (see below) |
+| `scanOnly` | no | — | Override depth-derived scan mode |
+| `allowWrites` | no | `false` | Override depth-derived write permission |
+| `findings` | no | — | Pre-identified findings array (triggers targeted-apply mode when `depth=tier-4`) |
+
+*Required unless configured in `.tdd-audit.json`.
+
+**Response — 202 Accepted**
+
+```
+HTTP/1.1 202 Accepted
+Location: /jobs/job_1_...
+Retry-After: 5
+```
+```json
+{ "jobId": "job_1_1711363200000" }
+```
+
+**Job result envelope** (available via `GET /jobs/:id` after completion)
 
-**Response — JSON**
 ```json
 {
-  "version":              "1.13.0",
-  "summary":              { "CRITICAL": 1, "HIGH": 3, "MEDIUM": 1, "LOW": 0 },
-  "findings":             [ ... ],
+  "version":             "1.16.0",
+  "provider":            "anthropic",
+  "model":               "claude-opus-4-6",
+  "depth":               "tier-2",
+  "mode":                "scan-only",
+  "stack":               "Node.js / Express",
+  "summary":             { "CRITICAL": 1, "HIGH": 2, "MEDIUM": 0, "LOW": 1 },
+  "patchesApplied":      0,
+  "findings":            [ ... ],
   "likelyFalsePositives": [ ... ],
-  "exempted":             [],
-  "scannedAt":            "2026-03-25T12:00:00.000Z",
-  "duration":             42
+  "remediation":         [],
+  "scannedAt":           "2026-03-26T12:00:00.000Z"
 }
 ```
 
-**Response — SARIF**
+`patchesApplied` is the billable unit for `tier-4`: the count of `remediation` entries where `status === "fixed"`.
+
+---
+
+### Depth tiers
+
+| Tier | Mode | Finding fields added | `allowWrites` |
+|---|---|---|---|
+| `tier-1` | scan-only | `name`, `severity`, `file`, `line`, `snippet` | no |
+| `tier-2` | scan-only | + `risk`, `effort`, `cwe`, `owasp`, `references` | no |
+| `tier-3` | full audit | + `patch` (copy-ready), `testSnippet` | no |
+| `tier-4` | full audit | LLM calls `write_file`; `remediation` array tracks each patch | yes |
+
+---
+
+### Targeted apply (tier-4 + findings)
 
-Returns a SARIF 2.1.0 object ready to upload to GitHub code scanning.
+When `depth=tier-4` and a `findings` array is supplied, the LLM skips the scan phase entirely and applies only the patches you specify. Use this to apply a single finding from a previous tier-3 report:
 
-**Errors**
+```json
+{
+  "provider": "anthropic",
+  "apiKey":   "sk-ant-...",
+  "depth":    "tier-4",
+  "findings": [
+    {
+      "name":    "SQL Injection",
+      "file":    "src/db.js",
+      "line":    42,
+      "patch":   "const stmt = db.prepare('SELECT * FROM users WHERE id = ?');\nstmt.run(id);"
+    }
+  ]
+}
+```
 
-| Status | Reason |
-|---|---|
-| 400 | Path traversal attempt, oversized body (> 512 KB), or invalid JSON |
-| 401 | Missing or invalid API key |
-| 429 | Rate limit exceeded |
+The job mode will be reported as `targeted-apply/tier-4(1)`. Only the listed findings are touched — no full re-scan.
 
 ---
 
 ### `POST /remediate`
 
-Queue an AI-powered remediation job for a **provided findings list**. Returns immediately with a `jobId`; poll `GET /jobs/:id` (or stream `GET /jobs/:id/stream`) for results.
+Queue an AI-powered remediation job for a **provided findings list**. Returns immediately with a `jobId`.
 
-Use `POST /audit` instead if you want the server to run the scan itself.
+Use `POST /audit/ai` for a fully agentic audit instead.
 
 **Request**
 ```json
@@ -142,34 +199,28 @@ Use `POST /audit` instead if you want the server to run the scan itself.
   "provider": "anthropic",
   "apiKey":   "sk-ant-...",
   "model":    "claude-opus-4-6",
-  "baseUrl":  null,
-  "severity": "HIGH"
+  "baseUrl":  null
 }
 ```
 
 | Field | Required | Description |
 |---|---|---|
-| `findings` | yes | Array of finding objects from `POST /scan` |
+| `findings` | yes | Array of finding objects |
 | `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) |
+| `model` | no | Defaults per provider |
+| `baseUrl` | no | Override base URL for OpenAI-compatible services |
 
 **Response — 202 Accepted**
 ```json
 { "jobId": "job_1_1711363200000" }
 ```
 
-Job lifecycle: `pending → running → done | error`
-
 ---
 
 ### `POST /audit`
 
-Full automated pipeline: **scan + AI remediation in one shot**. No interaction needed. Returns immediately with a `jobId`.
-
-If no `provider`/`apiKey` are supplied, the server runs the scan only (no remediation) and the job transitions to `done` with just the `findings` array.
+Static scan + AI remediation pipeline in one shot. Runs `quickScan` then passes findings to the remediator. If no `provider`/`apiKey` are supplied, runs the scan only.
 
 **Request**
 ```json
@@ -185,7 +236,7 @@ If no `provider`/`apiKey` are supplied, the server runs the scan only (no remedi
 
 | Field | Required | Description |
 |---|---|---|
-| `path` | no | Path to scan. Defaults to cwd. Must be inside server cwd. |
+| `path` | no | Path to scan. Defaults to cwd. |
 | `provider` | no | If supplied with `apiKey`, AI remediation runs after the scan |
 | `apiKey` | no | Provider API key |
 | `model` | no | Defaults per provider |
@@ -196,69 +247,21 @@ If no `provider`/`apiKey` are supplied, the server runs the scan only (no remedi
 
 ```
 HTTP/1.1 202 Accepted
-Location: /jobs/job_1_1711363200000
+Location: /jobs/job_1_...
 Retry-After: 2
 ```
-```json
-{ "jobId": "job_1_1711363200000" }
-```
 
 Job lifecycle: `pending → scanning → scanned → remediating → done | error`
 
-Poll `GET /jobs/:id` or stream `GET /jobs/:id/stream` for progress.
-
-**Job object during remediation**
-```json
-{
-  "id":        "job_1_...",
-  "status":    "remediating",
-  "total":     8,
-  "completed": 3,
-  "current":   "SQL Injection"
-}
-```
-
-**Job object when done**
-```json
-{
-  "id":          "job_1_...",
-  "status":      "done",
-  "createdAt":   "...",
-  "startedAt":   "...",
-  "completedAt": "...",
-  "findings":    [ ... ],
-  "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"]
-    }
-  ]
-}
-```
-
 ---
 
 ### `GET /jobs/:id`
 
-Poll for job status. Works for jobs created by both `POST /remediate` and `POST /audit`.
+Poll for job status. Works for jobs created by `POST /audit/ai`, `POST /remediate`, and `POST /audit`.
 
-**Response — pending / scanning**
+**Response — pending / running**
 ```json
-{ "id": "job_1_...", "status": "scanning", "createdAt": "..." }
-```
-
-**Response — remediating (with progress)**
-```json
-{
-  "id":        "job_1_...",
-  "status":    "remediating",
-  "total":     8,
-  "completed": 3,
-  "current":   "SQL Injection"
-}
+{ "id": "job_1_...", "status": "running", "depth": "tier-2", "createdAt": "..." }
 ```
 
 **Response — done**
@@ -269,7 +272,7 @@ Poll for job status. Works for jobs created by both `POST /remediate` and `POST
   "createdAt":   "...",
   "startedAt":   "...",
   "completedAt": "...",
-  "results":     [ ... ]
+  "result": { ... }
 }
 ```
 
@@ -293,18 +296,14 @@ curl -N http://localhost:3000/jobs/job_1_.../stream \
 
 **Event format**
 ```
-data: {"id":"job_1_...","status":"scanning","createdAt":"..."}
-
-data: {"id":"job_1_...","status":"scanned","findings":[...]}
-
-data: {"id":"job_1_...","status":"remediating","total":8,"completed":1,"current":"SQL Injection"}
+data: {"id":"job_1_...","status":"running","depth":"tier-2","log":"🔍 Exploring..."}
 
-data: {"id":"job_1_...","status":"done","completedAt":"...","results":[...]}
+data: {"id":"job_1_...","status":"done","completedAt":"...","result":{...}}
 ```
 
-The connection is closed automatically after the terminal state (`done` / `error`). If you connect to an already-completed job, the server pushes the current state and closes immediately.
+The connection closes automatically after the terminal state. Connecting to an already-completed job pushes the current state and closes immediately.
 
-**Node.js example using EventSource**
+**Node.js example**
 ```javascript
 const es = new EventSource(
   'http://localhost:3000/jobs/job_1_.../stream',
@@ -312,7 +311,7 @@ const es = new EventSource(
 );
 es.onmessage = (e) => {
   const job = JSON.parse(e.data);
-  if (job.status === 'done') { console.log(job.results); es.close(); }
+  if (job.status === 'done') { console.log(job.result); es.close(); }
   if (job.status === 'error') { console.error(job.error); es.close(); }
 };
 ```
@@ -321,28 +320,19 @@ es.onmessage = (e) => {
 
 ## Full workflow examples
 
-### curl — scan only
+### curl — tier-2 audit with polling
 
 ```bash
 npx @lhi/tdd-audit serve --port 3000 --api-key mysecret &
 
-curl -s -X POST http://localhost:3000/scan \
-  -H "Authorization: Bearer mysecret" \
-  -H "Content-Type: application/json" \
-  -d '{"path": "."}' | jq '.summary'
-```
-
-### curl — full pipeline with polling
-
-```bash
-# Kick off audit
-JOB=$(curl -s -X POST http://localhost:3000/audit \
+# Start the audit
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer mysecret" \
   -H "Content-Type: application/json" \
   -d '{
-    "path":     ".",
     "provider": "anthropic",
-    "apiKey":   "sk-ant-..."
+    "apiKey":   "sk-ant-...",
+    "depth":    "tier-2"
   }' | jq -r '.jobId')
 
 # Poll until done
@@ -351,30 +341,53 @@ while true; do
     -H "Authorization: Bearer mysecret" | jq -r '.status')
   echo "Status: $STATUS"
   [ "$STATUS" = "done" ] || [ "$STATUS" = "error" ] && break
-  sleep 2
+  sleep 3
 done
+
+# Print findings summary
+curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer mysecret" | jq '.result.summary'
 ```
 
-### curl — SARIF output for GitHub code scanning
+### curl — tier-3 report then targeted apply
 
 ```bash
-curl -s -X POST http://localhost:3000/scan \
+# Step 1: get copy-ready patches (no writes)
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer mysecret" \
   -H "Content-Type: application/json" \
-  -d '{"path": ".", "format": "sarif"}' > results.sarif
+  -d '{"provider":"anthropic","apiKey":"sk-ant-...","depth":"tier-3"}' \
+  | jq -r '.jobId')
+
+# (wait for done)
+
+# Step 2: apply one specific patch
+FINDING=$(curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer mysecret" \
+  | jq '.result.findings[0]')
+
+curl -s -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"provider\": \"anthropic\",
+    \"apiKey\":   \"sk-ant-...\",
+    \"depth\":    \"tier-4\",
+    \"findings\": [$FINDING]
+  }" | jq '.jobId'
 ```
 
-### Node.js — scan
+### curl — SARIF output for GitHub code scanning
 
-```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}`);
+```bash
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"anthropic","apiKey":"sk-ant-...","depth":"tier-2","format":"sarif"}' \
+  | jq -r '.jobId')
+
+# (wait for done)
+
+curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer mysecret" | jq '.result' > results.sarif
 ```