iamsecure 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravindra Bisht
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# iamsecure
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/iamsecure?color=d93a2b&label=npm)](https://www.npmjs.com/package/iamsecure)
+[![license: MIT](https://img.shields.io/badge/license-MIT-2f7fd8)](https://github.com/Ravindrabisht12/iamsecure/blob/main/LICENSE)
+![zero dependencies](https://img.shields.io/badge/dependencies-0-12a03b)
+![node >= 18](https://img.shields.io/badge/node-%E2%89%A518-339933)
+
+**Find vulnerable dependencies and insecure code, ranked by how dangerous they are in *your* app, not just by CVSS.**
+
+```bash
+npx iamsecure        # scan the current folder
+npx iamsecure --ui   # open the dashboard
+```
+
+<p align="center">
+  <img src="docs/images/terminal.png" alt="iamsecure terminal report" width="680">
+</p>
+
+Every finding is ranked in two ways:
+
+- **Real risk (worst first)** is the default. It shows how dangerous each issue is for *this* codebase.
+- **Severity (high → low)** is the raw CVSS / rule severity, the same thing `npm audit` shows.
+
+The two rankings differ a lot in practice. A 9.8 CVE in a dev-only CLI tool drops to *low*. An 8.1 lodash advisory rises to *critical* because your API route calls the exact `_.template` function the advisory names.
+
+It has **zero runtime dependencies** and needs only Node ≥ 18. A security scanner shouldn't add 300 packages to your supply chain.
+
+### Example: OWASP Juice Shop
+
+A scan of [OWASP Juice Shop](https://github.com/juice-shop/juice-shop), a deliberately vulnerable Node.js app:
+
+| | critical | high | medium | low |
+|---|---|---|---|---|
+| By raw severity | 16 | 51 | 44 | 2 |
+| **By real risk** | **16** | **40** | **44** | **13** |
+
+It covered 1,181 packages and 377 source files in about 5 seconds, and found the app's planted SQL injection in `routes/login.ts`, its `eval`, its path traversal routes and 11 hard-coded secrets.
+
+Twelve "high" findings dropped to medium or low:
+- Nine are in `tar`, which is installed but never imported anywhere.
+- The rest are in a dev-only build tool and a test file.
+
+One "high" `jsonwebtoken` advisory rose to *critical*, because the server's auth code imports that package.
+
+## Dashboard
+
+`npx iamsecure --ui` opens a local dashboard. Its **Fix list** groups every issue into one action, explains it in plain language (what's wrong, what could happen, where it runs, how to fix) and gives the exact install command.
+
+<p align="center">
+  <img src="docs/images/dashboard.png" alt="iamsecure dashboard: fix list" width="820">
+</p>
+
+The **Dependency tree** shows which of your direct dependencies brings in each vulnerable package. Its search answers "why is this installed?".
+
+<p align="center">
+  <img src="docs/images/dependency-tree.png" alt="iamsecure dependency tree" width="820">
+</p>
+
+## Quick start
+
+```bash
+npx iamsecure                 # scan the current directory, print to terminal
+npx iamsecure --ui            # open the interactive dashboard on http://localhost:4477
+npx iamsecure --ai claude-cli # let Claude double-check the top findings
+```
+
+To get `npm run iamsecure` in a project:
+
+```bash
+npm i -D iamsecure
+npm pkg set scripts.iamsecure="iamsecure --ui"
+npm run iamsecure
+```
+
+## What it does
+
+| Step | How |
+|---|---|
+| 1. Full dependency tree | Parses `package-lock.json` (v1–v3), `yarn.lock` (classic + berry), `pnpm-lock.yaml` (v5–v9), `composer.lock`, `uv.lock`, `poetry.lock`, `Pipfile.lock`, pinned `requirements*.txt`. It records *why* each package is installed (`next › postcss › nanoid`) and whether it's production or dev-only. |
+| 2. Known vulnerabilities | Batch-queries [OSV.dev](https://osv.dev), which aggregates GitHub Advisories, npm, PyPA, Packagist and others, including `MAL-` **malicious package** reports. Picks the fix version from the range that contains your version. |
+| 3. Your own code | Rules for JS/TS, PHP and Python: command/SQL/template injection, SSRF, path traversal, XSS, open redirect, unsafe deserialization, JWT mistakes, disabled TLS, weak crypto, risky Next.js config, secrets exposed through `NEXT_PUBLIC_*`. It also finds hard-coded secrets and `.env` files that are committed or not gitignored. Lightweight taint tracking tells `exec(userInput)` (critical) apart from `exec("ls")` (not reported). |
+| 4. Validate | Context scoring (below), and optionally AI review of the top findings. |
+
+## How "real risk" is calculated
+
+```
+risk = severity × exposure × attack vector × exploit intel × reachability  (× AI verdict)
+```
+
+- **Exposure** depends on where the code runs. The tool classifies every file as server, browser, both, or build/test. It understands Next.js `app/`, `pages/api`, `'use client'`, middleware, Vite/CRA SPAs, Node servers, Nuxt/SvelteKit/Remix, PHP and Python. A vulnerable package inherits the exposure of the direct dependencies that pull it in.
+- **Vulnerability class decides the browser discount.** A ReDoS in browser-only code is ×0.2, because an attacker can only freeze their own tab. SSRF and path traversal in the browser are ×0.25. XSS stays ×0.95. Dev/build-only code is ×0.3. Installed-but-never-imported packages are ×0.5. Malicious packages are always 10, because install scripts run on every machine that installs them.
+- **Attack vector.** Advisories that need local access (CVSS `AV:L`) or high privileges score lower.
+- **Exploit intel.** A CVE in [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) (exploited in the wild) gets a floor of 9.0. A high [EPSS](https://www.first.org/epss/) exploitation probability boosts the score.
+- **Reachability.** If your code calls a function the advisory names (`_.template`, `jwt.verify`), the risk goes up. If not, it goes down slightly.
+
+Every adjustment adds a plain-English reason that shows in the terminal, the dashboard and SARIF, so the ranking can be explained.
+
+## AI validation (optional)
+
+| `--ai` | Uses | Notes |
+|---|---|---|
+| `claude-cli` | Your existing Claude Code login | No API key. Runs `claude -p` with all tools disabled. |
+| `anthropic` | `ANTHROPIC_API_KEY` | Needs `@anthropic-ai/sdk` installed (loaded only when used). Defaults to `claude-opus-5-5`. |
+| `openai` | `OPENAI_API_KEY` | `OPENAI_BASE_URL` works with OpenRouter, Groq, LM Studio, vLLM… |
+| `ollama` | Local Ollama | Nothing leaves your machine. |
+
+- Only the finding and the surrounding code snippets are sent, never the whole repo. Run `--ai-dry-run` to see exactly what would be sent.
+- The model returns `exploitable / likely / unlikely / not_exploitable` with a confidence, reasoning and a fix. That verdict adjusts the risk score.
+- For example, it demoted the Next.js middleware-bypass CVE (EPSS 99%) to "unlikely" because the project has no `middleware.ts`.
+- Code and advisory text are passed as untrusted data, which defends against prompt injection.
+- Results are cached in `~/.cache/iamsecure`, so re-runs are free.
+- In the dashboard, every finding has an **Ask AI** button.
+
+## CI
+
+```yaml
+# .github/workflows/iamsecure.yml
+name: iamsecure
+on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions: { security-events: write, contents: read }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npx iamsecure --sarif --fail-on critical
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with: { sarif_file: iamsecure.sarif }
+```
+
+The SARIF `security-severity` field is the contextual risk score, so GitHub's alert severities follow the real-risk ranking.
+
+## Options
+
+```
+--sort <risk|severity>   ranking order (default risk)
+--min <level>            hide findings below critical|high|medium|low
+--limit <n>              findings printed in the terminal (default 30)
+--ui / --port / --no-open  dashboard (binds 127.0.0.1 only, token-protected API)
+--json [file]            full report as JSON
+--sarif [file]           SARIF 2.1.0
+--fail-on <level>        exit 1 when real risk ≥ level
+--ai <provider> / --ai-model / --ai-max <n> / --ai-dry-run
+--no-deps / --no-code / --offline-intel
+```
+
+Environment variables:
+- `IAMSECURE_CACHE_DIR` and `IAMSECURE_NO_CACHE=1` control the cache.
+- `IAMSECURE_AI_TIMEOUT` sets the AI timeout in seconds (default 180).
+- `IAMSECURE_OPENAI_MODEL` and `IAMSECURE_OLLAMA_MODEL` override those providers' models.
+
+## Layout
+
+```
+bin/iamsecure.js          CLI
+src/scan.js               orchestrator → report object
+src/deps/                 lockfile parsers, dependency graph, OSV client, CVSS
+src/code/                 file walker, server/browser classification, rules + taint engine, secrets
+src/risk/                 exploit intel (KEV/EPSS) and the risk model
+src/ai/                   prompt builder and providers (claude-cli, anthropic, openai, ollama)
+src/report/               terminal and SARIF output
+src/ui/                   localhost dashboard: fix list, all findings, dependency tree (single HTML file, no CDN)
+```
+
+To try it from a clone of this repo, run `node bin/iamsecure.js /path/to/your/project --ui`.
+
+## Limitations
+
+- Code rules are pattern- and taint-based, not a full data-flow engine. Taint tracking is per file and name-based, so two variables with the same name in different scopes can cause false positives. Use `--ai` to triage them.
+- The reachability check needs the advisory to name the function. Many advisories don't, and in that case the tool says so.
+- Packages are matched against published advisories. A zero-day nobody has reported yet won't show up.
+- Python and PHP import usage isn't mapped to packages yet. Their runtime dependencies are treated as server-side.

package/bin/iamsecure.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { scan, summarize, sortFindings, VERSION } from '../src/scan.js';
+import { aiReview, makeAnalyzer } from '../src/ai/index.js';
+import { printReport, c } from '../src/report/terminal.js';
+import { serveDashboard } from '../src/ui/server.js';
+import { toSarif } from '../src/report/sarif.js';
+
+const HELP = `
+${c.bold('iamsecure')} — find vulnerable dependencies and insecure code, ranked by real-world risk
+
+${c.bold('Usage')}
+  npx iamsecure [path] [options]
+
+${c.bold('Options')}
+  --sort <risk|severity>   risk = worst for THIS codebase first (default); severity = raw CVSS high → low
+  --min <level>            only show findings at or above critical|high|medium|low
+  --limit <n>              max findings printed in the terminal (default 30)
+  --ui                     open the interactive report in your browser (localhost only)
+  --port <n>               dashboard port (default 4477; next free port is used if taken)
+  --no-open                with --ui: don't launch the browser, just print the URL
+  --json [file]            write the full report as JSON (default iamsecure-report.json)
+  --sarif [file]           write SARIF for GitHub/GitLab code scanning (default iamsecure.sarif)
+  --fail-on <level>        exit 1 if any finding's real risk is at/above critical|high|medium|low (CI)
+
+${c.bold('AI validation')} (optional — only code snippets around each finding are sent, never the whole repo)
+  --ai <provider>          claude-cli (uses your Claude Code login) | anthropic (ANTHROPIC_API_KEY)
+                           | openai (OPENAI_API_KEY, OPENAI_BASE_URL for compatible APIs) | ollama (local)
+  --ai-model <id>          override the provider's default model
+  --ai-max <n>             how many top findings to review (default 15)
+  --ai-dry-run             print the prompts that would be sent, send nothing
+  --no-deps                skip the dependency scan
+  --no-code                skip source analysis (exposure then becomes "unknown")
+  --offline-intel          skip CISA KEV / EPSS lookups
+  -v, --version            print version
+  -h, --help               show this help
+
+${c.bold('Examples')}
+  npx iamsecure                       scan the current directory
+  npx iamsecure ../my-next-app --sort severity
+  npx iamsecure --ui                  interactive dashboard on http://localhost:4477
+  npx iamsecure --ai claude-cli       let Claude double-check the top 15 findings
+`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    sort: { type: 'string', default: 'risk' },
+    min: { type: 'string' },
+    limit: { type: 'string', default: '30' },
+    json: { type: 'string' },
+    sarif: { type: 'string' },
+    'fail-on': { type: 'string' },
+    ui: { type: 'boolean', default: false },
+    port: { type: 'string', default: '4477' },
+    'no-open': { type: 'boolean', default: false },
+    ai: { type: 'string' },
+    'ai-model': { type: 'string' },
+    'ai-max': { type: 'string', default: '15' },
+    'ai-dry-run': { type: 'boolean', default: false },
+    'no-deps': { type: 'boolean', default: false },
+    'no-code': { type: 'boolean', default: false },
+    'offline-intel': { type: 'boolean', default: false },
+    version: { type: 'boolean', short: 'v' },
+    help: { type: 'boolean', short: 'h' },
+  },
+  // `--json` / `--sarif` with no value are allowed; parseArgs needs a value, so patch argv below.
+  args: process.argv.slice(2).flatMap((a, i, arr) => {
+    const defaults = { '--json': 'iamsecure-report.json', '--sarif': 'iamsecure.sarif' };
+    return defaults[a] && (arr[i + 1] === undefined || arr[i + 1].startsWith('-')) ? [a, defaults[a]] : [a];
+  }),
+});
+
+if (values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (values.version) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+const root = path.resolve(positionals[0] ?? '.');
+if (!fs.existsSync(root)) {
+  console.error(`Path not found: ${root}`);
+  process.exit(2);
+}
+
+const log = (m) => process.stderr.write(c.dim(`› ${m}\n`));
+
+const runScan = async () => {
+  const report = await scan(root, { deps: !values['no-deps'], code: !values['no-code'], exploit: !values['offline-intel'], log });
+  if (values.ai) {
+    await aiReview(report, { provider: values.ai, model: values['ai-model'], max: Number(values['ai-max']), dryRun: values['ai-dry-run'], log });
+    report.summary = summarize(report.findings);
+    report.findings = sortFindings(report.findings, 'risk');
+  }
+  return report;
+};
+
+try {
+  const report = await runScan();
+  printReport(report, { sort: values.sort, limit: values.ui ? Math.min(Number(values.limit), 10) : Number(values.limit), min: values.min });
+  if (values.json) {
+    fs.writeFileSync(values.json, JSON.stringify(report, null, 2));
+    log(`JSON report written to ${values.json}`);
+  }
+  if (values.sarif) {
+    fs.writeFileSync(values.sarif, JSON.stringify(toSarif(report), null, 2));
+    log(`SARIF report written to ${values.sarif}`);
+  }
+  const order = ['critical', 'high', 'medium', 'low'];
+  if (values['fail-on'] && !values.ui) {
+    if (!order.includes(values['fail-on'])) throw new Error(`--fail-on must be one of ${order.join(', ')}`);
+    const failing = report.findings.filter((f) => order.indexOf(f.risk) !== -1 && order.indexOf(f.risk) <= order.indexOf(values['fail-on']));
+    if (failing.length) {
+      console.error(c.red(`✖ ${failing.length} finding(s) at or above "${values['fail-on']}" real risk.`));
+      process.exitCode = 1;
+    }
+  }
+  if (values.ui) {
+    const { url } = await serveDashboard(report, {
+      port: Number(values.port),
+      open: !values['no-open'],
+      rescan: runScan,
+      aiProvider: values.ai ?? null,
+      analyze: values.ai ? makeAnalyzer({ provider: values.ai, model: values['ai-model'] }) : undefined,
+    });
+    console.log(`\n${c.bold('Dashboard:')} ${c.cyan(url)}  ${c.dim('(Ctrl+C to stop)')}`);
+  }
+} catch (err) {
+  console.error(c.red(`iamsecure failed: ${err.stack ?? err.message}`));
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "iamsecure",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Scan a codebase for vulnerable dependencies and insecure code, ranked by real-world risk \u2014 with an optional AI second opinion.",
+  "author": "Ravindra Bisht",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ravindrabisht12/iamsecure.git"
+  },
+  "homepage": "https://github.com/Ravindrabisht12/iamsecure#readme",
+  "bugs": {
+    "url": "https://github.com/Ravindrabisht12/iamsecure/issues"
+  },
+  "type": "module",
+  "bin": {
+    "iamsecure": "bin/iamsecure.js"
+  },
+  "files": [
+    "bin",
+    "src/**/*.js",
+    "src/ui/index.html"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "iamsecure": "node bin/iamsecure.js"
+  },
+  "keywords": [
+    "security",
+    "vulnerability",
+    "audit",
+    "osv",
+    "sca",
+    "sast"
+  ],
+  "license": "MIT"
+}

package/src/ai/index.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { mapLimit } from '../util/http.js';
+import { cacheGet, cacheSet } from '../util/cache.js';
+import { levelFromScore } from '../deps/cvss.js';
+import { createProvider } from './providers.js';
+
+const VERDICTS = { exploitable: 1.15, likely: 1, unlikely: 0.6, not_exploitable: 0.3 };
+const MAX_DETAILS = 3000;
+
+function readLines(root, rel, center, radius) {
+  const abs = path.resolve(root, rel);
+  if (!abs.startsWith(path.resolve(root) + path.sep)) return null;
+  let text;
+  try {
+    text = fs.readFileSync(abs, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = text.split('\n');
+  const from = Math.max(1, center - radius);
+  const to = Math.min(lines.length, center + radius);
+  const body = lines.slice(from - 1, to).map((l, i) => `${String(from + i).padStart(4)}| ${l}`).join('\n');
+  return `<code file="${rel}" lines="${from}-${to}">\n${body}\n</code>`;
+}
+
+/** Evidence the model needs: the finding plus the code that uses it. */
+export function buildPrompt(f, report) {
+  const root = report.project.root;
+  const parts = [];
+  const meta = {
+    type: f.kind,
+    title: f.title,
+    framework: report.project.framework,
+    whereItRuns: f.exposure?.label,
+    scannerSeverity: f.severityScore,
+    scannerRisk: f.riskScore,
+    scannerReasons: f.reasons,
+  };
+  if (f.kind === 'dependency') {
+    Object.assign(meta, {
+      package: `${f.package.name}@${f.package.version}`,
+      direct: f.package.direct,
+      productionDependency: f.package.prod,
+      installedVia: f.package.path,
+      advisory: f.advisory.id,
+      aliases: f.advisory.aliases,
+      cwes: f.advisory.cwes,
+      cvss: f.advisory.cvss?.vector,
+      fixedIn: f.package.fixedIn,
+      advisoryText: `${f.advisory.summary}\n\n${f.advisory.details}`.slice(0, MAX_DETAILS),
+    });
+  } else {
+    Object.assign(meta, { rule: f.ruleId, cwe: f.cwe, userInputDetected: !!f.tainted, location: `${f.location.file}:${f.location.line}` });
+  }
+  parts.push(`<finding>\n${JSON.stringify(meta, null, 2)}\n</finding>`);
+
+  if (f.kind === 'dependency') {
+    // Show where the package (or the direct dependency that pulls it in) is used.
+    const evid = [];
+    if (f.reachable?.file) evid.push([f.reachable.file, f.reachable.line]);
+    for (const e of f.exposure?.evidence ?? []) {
+      const m = e.match(/in (.+):(\d+)$/);
+      if (m) evid.push([m[1], Number(m[2])]);
+    }
+    const seen = new Set();
+    for (const [file, line] of evid) {
+      if (seen.has(file) || seen.size >= 3) continue;
+      seen.add(file);
+      const block = readLines(root, file, line, 25);
+      if (block) parts.push(block);
+    }
+    if (!seen.size) parts.push('(No source file imports this package directly; it is pulled in transitively or loaded by the framework.)');
+    if (report.sourceFiles?.length) {
+      const list = report.sourceFiles.slice(0, 120).map((s) => `${s.file} [${s.context}]`).join('\n');
+      parts.push(`Project source files (to judge whether the affected feature is used):\n${list}`);
+    }
+  } else {
+    const block = readLines(root, f.location.file, f.location.line, 30);
+    if (block) parts.push(block);
+  }
+
+  parts.push(`Question: is this finding actually exploitable in this codebase, as deployed in production?
+Consider: can an attacker reach it (network-facing route, user input), does the vulnerable code path get used, is input validated or sanitised first, does it only run in the browser or at build time, and what an attacker gains.
+
+Respond with ONLY a JSON object, no markdown:
+{"verdict": "exploitable" | "likely" | "unlikely" | "not_exploitable",
+ "confidence": <number 0..1>,
+ "reasoning": "<at most 3 sentences citing the specific code>",
+ "fix": "<the concrete change to make; a short code snippet if it helps>"}`);
+  return parts.join('\n\n');
+}
+
+function parseVerdict(text) {
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end <= start) throw new Error('AI response had no JSON object');
+  const obj = JSON.parse(text.slice(start, end + 1));
+  const verdict = String(obj.verdict ?? '').toLowerCase().replace(/[\s-]+/g, '_');
+  if (!(verdict in VERDICTS)) throw new Error(`AI returned unknown verdict "${obj.verdict}"`);
+  const confidence = Math.min(1, Math.max(0, Number(obj.confidence) || 0.5));
+  return { verdict, confidence, reasoning: String(obj.reasoning ?? '').slice(0, 1200), fix: String(obj.fix ?? '').slice(0, 2000) };
+}
+
+/** Fold an AI verdict into the risk score; low confidence moves it less. */
+function applyVerdict(f, ai) {
+  const m = 1 + (VERDICTS[ai.verdict] - 1) * ai.confidence;
+  f.ai = ai;
+  f.riskScore = Math.round(Math.min(10, f.riskScore * m) * 10) / 10;
+  f.risk = levelFromScore(f.riskScore);
+  f.reasons = [...(f.reasons ?? []), `AI (${ai.provider}) judged it ${ai.verdict.replace('_', ' ')} (${Math.round(ai.confidence * 100)}% confidence)`];
+}
+
+async function reviewOne(f, report, provider) {
+  const prompt = buildPrompt(f, report);
+  const key = `${provider.name}:${provider.model}:${crypto.createHash('sha256').update(prompt).digest('hex')}`;
+  let ai = cacheGet('ai', key);
+  if (!ai) {
+    ai = { ...parseVerdict(await provider.complete(prompt)), provider: provider.name, model: provider.model };
+    cacheSet('ai', key, ai);
+  }
+  applyVerdict(f, ai);
+  return ai;
+}
+
+/**
+ * Ask an AI provider to validate the top findings.
+ * @param {any} report scan report (findings are updated in place)
+ * @param {{provider: string, model?: string, max?: number, dryRun?: boolean, log?: (m:string)=>void}} opts
+ */
+export async function aiReview(report, { provider: name, model, max = 15, dryRun = false, log = () => {} }) {
+  const provider = createProvider(name, { model, root: report.project.root });
+  const candidates = [...report.findings]
+    .filter((f) => f.riskScore >= 4 && !f.ai && !f.advisory?.malicious)
+    .sort((a, b) => b.riskScore - a.riskScore)
+    .slice(0, max);
+  if (!candidates.length) return { reviewed: 0, failed: 0, provider };
+
+  if (dryRun) {
+    for (const f of candidates) log(`--- prompt for ${f.id} ---\n${buildPrompt(f, report)}\n`);
+    log(`Dry run: ${candidates.length} prompts shown above; nothing was sent.`);
+    return { reviewed: 0, failed: 0, provider };
+  }
+
+  log(`Asking ${provider.name} (${provider.model}) to validate the top ${candidates.length} findings…`);
+  let done = 0;
+  let failed = 0;
+  const errors = new Set();
+  await mapLimit(candidates, provider.concurrency, async (f) => {
+    try {
+      await reviewOne(f, report, provider);
+    } catch (err) {
+      failed++;
+      errors.add(err.message);
+    }
+    log(`  AI review ${++done}/${candidates.length}`);
+  });
+  if (errors.size) report.warnings.push(`AI review: ${failed} of ${candidates.length} failed — ${[...errors].slice(0, 2).join('; ')}`);
+  return { reviewed: candidates.length - failed, failed, provider };
+}
+
+/** Single on-demand review (dashboard "Ask AI" button). */
+export function makeAnalyzer({ provider: name, model }) {
+  let provider;
+  return async (f, report) => {
+    provider ??= createProvider(name, { model, root: report.project.root });
+    return reviewOne(f, report, provider);
+  };
+}