securevibe 0.1.8 → 0.1.10

package/README.md

@@ -27,6 +27,7 @@ midnight). The `--staged` commit guard is never limited. See [`LICENSE`](LICENSE
 | `securevibe scan [path]` | Full scan → findings + security score (default command) |
 | `securevibe init [path]` | **Wire SecureVibe in: pre-commit guard + GitHub Action + gitignore** (doc 12) |
 | `securevibe fix [path]` | **Autonomously fix findings, then re-scan to verify** (doc 05) |
+| `securevibe explain [path]` | AI-powered plain-language explanations for critical/high findings |
 | `securevibe deps [path]` | Audit dependencies for known CVEs against the local OSV database (SCA) |
 | `securevibe db <update\|status>` | Manage the local OSV database — `update` is the only networked command |
 | `securevibe ready [path]` | Launch readiness scorecard: pass/fail gates + go/no-go verdict |
@@ -78,11 +79,20 @@ Anything that fails the gate is rolled back and surfaced as a manual instruction
   is kept **only if it passes the verification gate**, otherwise it falls back to a precise manual
   instruction. Groq is used by default when both keys are present (lower bar to try it at all);
   set `SECUREVIBE_LLM_PROVIDER=anthropic` to force Claude instead.
-- **Setting a key:** either export it yourself (`GROQ_API_KEY=...`), or run
-  `securevibe config set-key groq` — it prompts interactively (never as a command argument, so it
-  never lands in shell history) and saves it to `~/.securevibe/config.json`, used automatically by
-  `fix` whenever the env var isn't already set. Run `fix --apply` with no key configured and it will
-  offer to set one up on the spot. `securevibe config show` lists what's stored (masked).
+- **Setting a key:** `securevibe init` is the primary path — if it detects an LLM SDK dependency
+  (openai, `@anthropic-ai/sdk`, langchain, ...) and no key is already set, it offers to set one up
+  on the spot, once per project (declining is remembered so it won't ask again). You can also
+  export a key yourself (`GROQ_API_KEY=...`), or run `securevibe config set-key groq` any time — it
+  prompts interactively (never as a command argument, so it never lands in shell history) and saves
+  it to `~/.securevibe/config.json`, used automatically whenever the env var isn't already set.
+- **A second AI feature, `securevibe explain`:** for critical/high findings, asks
+  the same configured provider for a plain-language explanation grounded in the
+  actual flagged code (not just the generic why/fix text every finding of that
+  detector shares). Capped at the top 10 qualifying findings per run. Falls back to
+  the static why/fix text with no key configured, or if a call fails — an
+  explanation is always additional context, never required to use the command.
+  `fix --apply` with no key configured still offers to set one up as a fallback.
+  `securevibe config show` lists what's stored (masked).
 
 **Honesty (read this):**
 - A "fixed" finding means *our detector no longer flags it* — not that the app is proven secure.

package/dist/engine/explain.js

@@ -0,0 +1,79 @@
+/**
+ * `securevibe explain` (AI feature #2, 2026-07-10). Turns a critical/high
+ * finding's generic why/fix text into a plain-language explanation grounded
+ * in the actual flagged code. Read-only — no files are modified, so there is
+ * no verification/rollback gate the way `fix` needs one.
+ *
+ * Capped at EXPLAIN_MAX_FINDINGS per run to bound worst-case AI cost/latency:
+ * a scan with dozens of criticals should never turn into dozens of API calls
+ * without the caller asking for it. Degrades gracefully with no provider
+ * configured (or a failed call) — every finding still gets a result, with
+ * explanation: null, so the UI layer falls back to the static why/fix text.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { SEVERITY_ORDER } from "./types.js";
+import { llmChat, llmAvailability } from "./fix/llm.js";
+export const EXPLAIN_MAX_FINDINGS = 10;
+const EXPLAIN_SEVERITIES = new Set(["critical", "high"]);
+const SNIPPET_CONTEXT_LINES = 4;
+const EXPLAIN_SYSTEM = [
+    "You are a senior application-security engineer explaining one specific vulnerability finding to the developer who wrote the code.",
+    "You will receive the finding's detector, severity, generic why/fix guidance, and a snippet of the actual flagged code (the vulnerable line is marked with >>).",
+    "Write a short plain-language explanation (3-5 sentences) of the concrete risk IN THIS CODE specifically — reference the actual variable, function, or endpoint names visible in the snippet, not generic advice.",
+    "Do not repeat the generic why/fix text verbatim. Do not add a heading, bullet list, or markdown formatting. Return prose only.",
+].join("\n");
+function explainUserPrompt(finding, snippet) {
+    return [
+        `Finding: ${finding.title}`,
+        `Detector: ${finding.detector}  Severity: ${finding.severity}${finding.cwe ? `  ${finding.cwe}` : ""}`,
+        `File: ${finding.file}:${finding.line}`,
+        "",
+        "Generic why:",
+        finding.why,
+        "",
+        "Generic fix:",
+        finding.fix,
+        "",
+        "Code snippet (flagged line marked with >>):",
+        snippet,
+    ].join("\n");
+}
+/** A fixed window of lines around `line` (1-indexed), clamped to file bounds. */
+export function extractSnippet(code, line) {
+    const lines = code.split(/\r?\n/);
+    const idx = Math.min(Math.max(line - 1, 0), lines.length - 1);
+    const start = Math.max(0, idx - SNIPPET_CONTEXT_LINES);
+    const end = Math.min(lines.length, idx + SNIPPET_CONTEXT_LINES + 1);
+    const out = [];
+    for (let i = start; i < end; i++) {
+        out.push(`${i === idx ? ">>" : "  "} ${i + 1}: ${lines[i]}`);
+    }
+    return out.join("\n");
+}
+export async function explainFindings(scanResult, opts = {}) {
+    const qualifying = scanResult.findings
+        .filter((f) => EXPLAIN_SEVERITIES.has(f.severity))
+        .sort((a, b) => SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity] || b.confidence - a.confidence);
+    const capped = qualifying.slice(0, EXPLAIN_MAX_FINDINGS);
+    const truncatedCount = qualifying.length - capped.length;
+    const avail = llmAvailability(false);
+    const results = [];
+    for (const finding of capped) {
+        opts.onProgress?.(`Explaining ${finding.file}:${finding.line}…`);
+        let explanation = null;
+        if (avail.available) {
+            let snippet;
+            try {
+                const code = await fs.readFile(path.join(scanResult.root, finding.file), "utf8");
+                snippet = extractSnippet(code, finding.line);
+            }
+            catch {
+                snippet = "(source unavailable)";
+            }
+            explanation = await llmChat(EXPLAIN_SYSTEM, explainUserPrompt(finding, snippet));
+        }
+        results.push({ finding, explanation });
+    }
+    return { root: scanResult.root, results, truncatedCount, llmAvailable: avail.available };
+}

package/dist/engine/fix/llm.js

@@ -94,18 +94,30 @@ function userPrompt(input) {
 export async function llmFix(input) {
     if (input.code.length > MAX_FILE_CHARS)
         return null;
+    const text = await llmChat(SYSTEM, userPrompt(input));
+    if (text == null)
+        return null;
+    return parseFile(text, input.code);
+}
+/**
+ * Generic single-turn chat call against whichever provider is configured.
+ * Shared by llmFix (full-file rewrites) and engine/explain.ts (plain-language
+ * finding explanations) so the Groq/Anthropic HTTP plumbing lives in one place.
+ * Returns null on no-provider / network / auth / quota failure — callers degrade
+ * gracefully and must never throw because of this.
+ */
+export async function llmChat(system, user) {
     const provider = selectProvider();
     if (!provider)
         return null;
     try {
-        const text = provider === "groq" ? await callGroq(input) : await callAnthropic(input);
-        return parseFile(text, input.code);
+        return provider === "groq" ? await callGroq(system, user) : await callAnthropic(system, user);
     }
     catch {
-        return null; // network / auth / quota failure → fall back to manual
+        return null;
     }
 }
-async function callAnthropic(input) {
+async function callAnthropic(system, user) {
     let Anthropic;
     try {
         ({ default: Anthropic } = await import("@anthropic-ai/sdk"));
@@ -117,13 +129,13 @@ async function callAnthropic(input) {
     const msg = await client.messages.create({
         model: modelFor("anthropic"),
         max_tokens: 8192,
-        system: SYSTEM,
-        messages: [{ role: "user", content: userPrompt(input) }],
+        system,
+        messages: [{ role: "user", content: user }],
     });
     return extractAnthropicText(msg);
 }
 /** Groq's chat-completions endpoint is OpenAI-compatible — plain fetch, no SDK. */
-async function callGroq(input) {
+async function callGroq(system, user) {
     const res = await fetch("https://api.groq.com/openai/v1/chat/completions", {
         method: "POST",
         headers: {
@@ -134,8 +146,8 @@ async function callGroq(input) {
             model: modelFor("groq"),
             max_tokens: 8192,
             messages: [
-                { role: "system", content: SYSTEM },
-                { role: "user", content: userPrompt(input) },
+                { role: "system", content: system },
+                { role: "user", content: user },
             ],
         }),
     });

package/dist/engine/init.js

@@ -9,6 +9,43 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { isGitRepo, gitDir } from "./git.js";
+export function projectConfigPath(root) {
+    return path.join(path.resolve(root), "securevibe.config.json");
+}
+/** Tolerant read: a missing or corrupt config is treated as empty. */
+export async function readProjectConfig(root) {
+    try {
+        const raw = await fs.readFile(projectConfigPath(root), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function patchProjectConfig(root, patch) {
+    const current = await readProjectConfig(root);
+    const next = { ...current, ...patch };
+    await fs.writeFile(projectConfigPath(root), JSON.stringify(next, null, 2) + "\n", "utf8");
+}
+// Package names/imports that mark a repo as "uses an LLM SDK" — matched against
+// package.json (dependency keys) and requirements.txt (package names) so the
+// init-time AI-fixer offer only fires where it's actually relevant.
+const AI_PACKAGE_RE = /"(openai|@anthropic-ai\/sdk|anthropic|langchain|@langchain\/[\w.-]+|cohere-ai|@google\/generative-ai|llamaindex|@modelcontextprotocol\/sdk)"\s*:|^\s*(openai|anthropic|langchain|cohere|google-generativeai|llama-index)\b/im;
+export async function looksAiRelated(root) {
+    const absRoot = path.resolve(root);
+    for (const rel of ["package.json", "requirements.txt"]) {
+        try {
+            const content = await fs.readFile(path.join(absRoot, rel), "utf8");
+            if (AI_PACKAGE_RE.test(content))
+                return true;
+        }
+        catch {
+            /* file absent — try the next */
+        }
+    }
+    return false;
+}
 const GITIGNORE_LINES = [".env", ".env.local", ".env.*.local", ".securevibe-backup/"];
 const CONFIG = `{
   "failOn": "block",

package/dist/index-support.js

@@ -30,3 +30,32 @@ export async function maybeOfferAiFixerSetup() {
     process.env.GROQ_API_KEY = key;
     process.stderr.write(`  Saved to ${configFilePath()}. This run will use it.\n\n`);
 }
+/**
+ * Runs once at the end of `init`, interactive-only. Users were learning a
+ * provider key was needed only mid-`fix` — too late, past the point of
+ * expecting the fixer to already work. `init` already runs once per project
+ * before any `fix`, so it's the right place to surface this early — but only
+ * for repos that actually use an LLM SDK, and only once (a decline is
+ * remembered per-project so we don't nag).
+ */
+export async function maybeOfferAiFixerSetupDuringInit(root, deps) {
+    const { applyStoredKeysToEnv } = await import("./config.js");
+    await applyStoredKeysToEnv(deps?.configFile);
+    if (process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)
+        return;
+    const { readProjectConfig, patchProjectConfig, looksAiRelated } = await import("./engine/init.js");
+    const cfg = await readProjectConfig(root);
+    if (cfg.aiFixerPromptDismissed)
+        return;
+    if (!(await looksAiRelated(root)))
+        return;
+    const isInteractive = deps?.isInteractive ?? (await import("./ui/prompt.js")).isInteractive;
+    if (!isInteractive())
+        return;
+    process.stderr.write("\n  This project uses an LLM SDK — SecureVibe can auto-fix AI-specific findings\n  (tool-hijack, prompt-injection sinks) with a free key.\n");
+    const offer = deps?.offer ?? maybeOfferAiFixerSetup;
+    await offer();
+    if (!(process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+        await patchProjectConfig(root, { aiFixerPromptDismissed: true });
+    }
+}

package/dist/index.js

@@ -128,6 +128,8 @@ program
     const { renderInit } = await import("./ui/init.js");
     const result = await runInit(pathArg ?? ".", { force: opts.force });
     process.stdout.write(renderInit(result) + "\n");
+    const { maybeOfferAiFixerSetupDuringInit } = await import("./index-support.js");
+    await maybeOfferAiFixerSetupDuringInit(pathArg ?? ".");
 });
 program
     .command("fix")
@@ -169,6 +171,36 @@ program
     }
     await maybeNotifyUpdate({ json: opts.json });
 });
+program
+    .command("explain")
+    .description("AI-powered plain-language explanations for critical/high findings")
+    .argument("[path]", "path to the repository", ".")
+    .option("--json", "output machine-readable JSON")
+    .option("--no-color", "disable coloured output")
+    .action(async (pathArg, opts) => {
+    if (opts.color === false)
+        process.env.NO_COLOR = "1";
+    const { applyStoredKeysToEnv } = await import("./config.js");
+    await applyStoredKeysToEnv();
+    if (!opts.json) {
+        const { maybeOfferAiFixerSetup } = await import("./index-support.js");
+        await maybeOfferAiFixerSetup();
+    }
+    const { result, usage } = await runScan(pathArg, { json: opts.json, color: opts.color });
+    const { explainFindings } = await import("./engine/explain.js");
+    const report = await explainFindings(result, {
+        onProgress: opts.json ? undefined : (m) => process.stderr.write(`  · ${m}\n`),
+    });
+    if (opts.json) {
+        const { explainToJson } = await import("./ui/explain.js");
+        process.stdout.write(explainToJson(report) + "\n");
+    }
+    else {
+        const { renderExplain } = await import("./ui/explain.js");
+        process.stdout.write(renderExplain(report, usage) + "\n");
+    }
+    await maybeNotifyUpdate({ json: opts.json });
+});
 addCommon(program
     .command("ai-audit")
     .description("Focus on the AI-application / agent attack surface (doc 04)")

package/dist/repl.js

@@ -44,6 +44,7 @@ const HELP = [
     "  Commands:",
     "    scan [--json]                 full scan",
     "    fix [--apply] [--yes] [--no-llm] [--json]   fix findings",
+    "    explain [--json]               AI explanations for critical/high findings",
     "    ai-audit | protect | attack-map | score | deps | ready   [--json]",
     "    init [--force]                 wire up the pre-commit guard + CI",
     "    config show | set-key <groq|anthropic> | unset-key <groq|anthropic>",
@@ -149,11 +150,35 @@ async function dispatch(cmd, tokens, state, io) {
         }
         return;
     }
+    if (cmd === "explain") {
+        if (!asJson) {
+            const { maybeOfferAiFixerSetup } = await import("./index-support.js");
+            await maybeOfferAiFixerSetup();
+        }
+        const { explainFindings } = await import("./engine/explain.js");
+        const usage = await meterOrPrint(io);
+        const { scan } = await import("./engine/scan.js");
+        const scanResult = await scan(state.root, { onProgress: asJson ? undefined : (m) => write(io, `  · ${m}\n`) });
+        state.lastResult = scanResult;
+        const report = await explainFindings(scanResult, {
+            onProgress: asJson ? undefined : (m) => write(io, `  · ${m}\n`),
+        });
+        if (asJson) {
+            const { explainToJson } = await import("./ui/explain.js");
+            write(io, explainToJson(report) + "\n\n");
+            return;
+        }
+        const { renderExplain } = await import("./ui/explain.js");
+        write(io, renderExplain(report, usage) + "\n");
+        return;
+    }
     if (cmd === "init") {
         const { runInit } = await import("./engine/init.js");
         const { renderInit } = await import("./ui/init.js");
         const result = await runInit(state.root, { force: hasFlag(tokens, "--force") });
         write(io, renderInit(result) + "\n");
+        const { maybeOfferAiFixerSetupDuringInit } = await import("./index-support.js");
+        await maybeOfferAiFixerSetupDuringInit(state.root);
         return;
     }
     if (cmd === "config") {

package/dist/ui/explain.js

@@ -0,0 +1,72 @@
+/**
+ * `explain` view. Shows the AI-generated explanation per finding when
+ * available, falling back to the existing static why/fix text otherwise —
+ * an AI explanation is additional context, never a replacement, so the
+ * static text stays a guaranteed field in both the human and JSON output.
+ */
+import pc from "picocolors";
+import { renderBanner } from "./banner.js";
+import { renderUsageLine } from "./usage.js";
+const SEV_TAG = {
+    critical: (s) => pc.bgRed(pc.white(pc.bold(s))),
+    high: (s) => pc.red(pc.bold(s)),
+    medium: (s) => pc.yellow(s),
+    low: (s) => pc.blue(s),
+    info: (s) => pc.dim(s),
+};
+export function renderExplain(report, usage) {
+    const L = [];
+    L.push(renderBanner({ subtitle: "AI-powered finding explanations" }));
+    L.push(pc.dim(`  ${report.root}`));
+    L.push("");
+    if (usage) {
+        L.push(renderUsageLine(usage));
+        L.push("");
+    }
+    if (report.results.length === 0) {
+        L.push(pc.green("  No critical/high findings to explain."));
+        L.push("");
+        return L.join("\n");
+    }
+    for (const r of report.results) {
+        const f = r.finding;
+        const sev = SEV_TAG[f.severity](` ${f.severity.toUpperCase()} `);
+        L.push(`  ${sev} ${pc.bold(f.title)} ${pc.dim(`(${f.file}:${f.line})`)}`);
+        if (r.explanation) {
+            L.push(`    ${pc.cyan("AI:")} ${r.explanation.trim()}`);
+        }
+        else {
+            L.push(`    ${pc.dim("why:")} ${f.why}`);
+            L.push(`    ${pc.dim("fix:")} ${f.fix}`);
+        }
+        L.push("");
+    }
+    if (report.truncatedCount > 0) {
+        const total = report.results.length + report.truncatedCount;
+        L.push(pc.dim(`  Showing the top ${report.results.length} of ${total} critical/high findings — re-run \`scan\` to see the rest.`));
+        L.push("");
+    }
+    if (!report.llmAvailable) {
+        L.push(pc.dim("  Set GROQ_API_KEY (free tier) or ANTHROPIC_API_KEY for AI-generated explanations — showing static guidance above. Run `securevibe config set-key groq`."));
+        L.push("");
+    }
+    return L.join("\n");
+}
+export function explainToJson(report) {
+    return JSON.stringify({
+        root: report.root,
+        llmAvailable: report.llmAvailable,
+        truncatedCount: report.truncatedCount,
+        results: report.results.map((r) => ({
+            id: r.finding.id,
+            detector: r.finding.detector,
+            severity: r.finding.severity,
+            file: r.finding.file,
+            line: r.finding.line,
+            title: r.finding.title,
+            why: r.finding.why,
+            fix: r.finding.fix,
+            explanation: r.explanation,
+        })),
+    }, null, 2);
+}

package/dist/version.js

@@ -2,4 +2,4 @@
 // Single source of truth for the CLI's own version, so it can't drift from
 // what commander reports and what the update-check compares against.
 // Kept in sync with the "version" field in package.json by hand at release time.
-export const VERSION = "0.1.8";
+export const VERSION = "0.1.10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securevibe",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Autonomous AI security engineer for AI generated apps: scan, fix, verify, and gate every commit before you launch",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",