guardvibe 3.0.57 → 3.1.1

package/README.md

@@ -228,7 +228,7 @@ Malicious postinstall scripts, unpinned GitHub Actions, typosquat detection
 | `verify_fix` | Verify a security fix was applied correctly — returns fixed/still_vulnerable/new_issues |
 | `security_workflow` | Get recommended tool workflow for your current task (writing, pre-commit, PR review, etc.) |
 | `auth_coverage` | **Auth coverage map** — enumerate routes, parse middleware matchers, detect auth guards, report coverage % |
-| `deep_scan` | **LLM-powered deep analysis** — IDOR, business logic, race conditions, privilege escalation (requires API key) |
+| `deep_scan` | **LLM-powered deep analysis** — IDOR, business logic, race conditions, auth bypass. Defaults to Claude Haiku 4.5 (~cents/scan). Pass `model: 'sonnet'` for deeper analysis. CLI: `npx guardvibe deep-scan <file> --focus idor` |
 | `full_audit` | **Single source of truth** — runs ALL checks in one call, returns PASS/FAIL/WARN verdict + score + coverage % + deterministic result hash |
 | `remediation_plan` | **Remediation plan** — generates section-by-section fix checklist after audit |
 | `verify_remediation` | **Remediation verification** — compares before/after audit, flags skipped sections |

package/build/cli/deep-scan.d.ts

@@ -0,0 +1 @@
+export declare function runDeepScan(args: string[]): Promise<void>;

package/build/cli/deep-scan.js

@@ -0,0 +1,79 @@
+/**
+ * CLI: guardvibe deep-scan <file>
+ * LLM-powered deep security analysis.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { resolve, extname } from "node:path";
+import { parseArgs } from "./args.js";
+import { buildDeepScanPrompt, callLLM, parseDeepScanResult, formatDeepScanFindings, DEFAULT_MAX_BYTES, } from "../tools/deep-scan.js";
+const EXT_TO_LANG = {
+    ".ts": "typescript", ".tsx": "typescript", ".mts": "typescript", ".cts": "typescript",
+    ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
+    ".py": "python", ".go": "go", ".rb": "ruby", ".java": "java",
+    ".rs": "rust", ".php": "php", ".cs": "csharp",
+};
+const VALID_FOCUS = ["all", "idor", "business-logic", "auth-bypass", "race-condition"];
+export async function runDeepScan(args) {
+    const { flags, positional } = parseArgs(args);
+    const file = positional[0];
+    if (!file) {
+        console.error("  [ERR] Please specify a file: npx guardvibe deep-scan <file>");
+        console.error("");
+        console.error("  Options:");
+        console.error("    --focus <area>     all (default) | idor | business-logic | auth-bypass | race-condition");
+        console.error("    --model <model>    haiku (default, ~cents/scan) | sonnet (deeper, more expensive)");
+        console.error("    --max-bytes <n>    Truncate input to N bytes (default 10000)");
+        console.error("    --format <type>    markdown (default) | json");
+        console.error("");
+        console.error("  Requires ANTHROPIC_API_KEY (or OPENAI_API_KEY) environment variable.");
+        process.exit(1);
+    }
+    const path = resolve(file);
+    let content;
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile()) {
+            console.error(`  [ERR] Not a file: ${path}`);
+            process.exit(1);
+        }
+        content = readFileSync(path, "utf-8");
+    }
+    catch (e) {
+        console.error(`  [ERR] Cannot read file: ${path}`);
+        console.error(`        ${e.message}`);
+        process.exit(1);
+    }
+    if (!process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY) {
+        console.error("  [ERR] No LLM API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY in your environment.");
+        console.error("        Default model is Claude Haiku 4.5 — typically ~cents per scan.");
+        process.exit(1);
+    }
+    const focusArg = flags.focus ?? "all";
+    if (!VALID_FOCUS.includes(focusArg)) {
+        console.error(`  [ERR] Invalid --focus: ${focusArg}. Use one of: ${VALID_FOCUS.join(", ")}`);
+        process.exit(1);
+    }
+    const focus = focusArg;
+    const modelArg = flags.model ?? "haiku";
+    if (modelArg !== "haiku" && modelArg !== "sonnet") {
+        console.error(`  [ERR] Invalid --model: ${modelArg}. Use haiku or sonnet.`);
+        process.exit(1);
+    }
+    const model = modelArg;
+    const maxBytes = flags["max-bytes"] != null ? Number(flags["max-bytes"]) : DEFAULT_MAX_BYTES;
+    if (!Number.isFinite(maxBytes) || maxBytes < 500 || maxBytes > 50_000) {
+        console.error(`  [ERR] --max-bytes must be 500..50000 (got ${flags["max-bytes"]})`);
+        process.exit(1);
+    }
+    const format = (flags.format === "json" ? "json" : "markdown");
+    const language = EXT_TO_LANG[extname(path).toLowerCase()] ?? "unknown";
+    const prompt = buildDeepScanPrompt(content, language, [], focus);
+    const llmResponse = await callLLM(prompt, { model, maxBytes });
+    if (llmResponse === null) {
+        console.error("  [ERR] LLM call failed — check API key validity and network.");
+        process.exit(1);
+    }
+    const findings = parseDeepScanResult(llmResponse);
+    const output = formatDeepScanFindings(findings, format);
+    console.log(output);
+}

package/build/cli.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 import { createRequire } from "module";
+import { checkForUpdate } from "./utils/update-check.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
+// Fire-and-forget update notification (writes to stderr if newer version exists).
+// Skipped when GUARDVIBE_NO_UPDATE_CHECK=1, NO_UPDATE_NOTIFIER=1, or CI=true.
+checkForUpdate(pkg.version);
 // ── Scan entry point detection ──────────────────────────────────────
 const SCAN_SCRIPT_DETECTED = process.argv[1]?.endsWith("guardvibe-scan") ||
     process.argv[1]?.endsWith("guardvibe-scan.js");
@@ -28,6 +32,7 @@ function printUsage() {
     npx guardvibe check-cmd "<cmd>"  Check if a shell command is safe to execute
     npx guardvibe auth-coverage [path]  Auth coverage analysis (Next.js routes)
     npx guardvibe compliance [path]     Compliance report (--framework SOC2|GDPR|...)
+    npx guardvibe deep-scan <file>   LLM-powered deep scan (IDOR, business logic, race conditions)
     npx guardvibe init <platform>    Setup MCP server configuration
     npx guardvibe hook install       Install pre-commit security hook
     npx guardvibe hook uninstall     Remove pre-commit security hook
@@ -152,6 +157,10 @@ async function main() {
         const { runCompliance } = await import("./cli/compliance.js");
         await runCompliance(subArgs);
     }
+    else if (command === "deep-scan") {
+        const { runDeepScan } = await import("./cli/deep-scan.js");
+        await runDeepScan(subArgs);
+    }
     else {
         console.error(`  Unknown command: ${command}`);
         printUsage();

package/build/index.js

@@ -863,20 +863,24 @@ server.tool("auth_coverage", "Analyze authentication coverage across Next.js App
     return { content: [{ type: "text", text: output }] };
 });
 // Tool 32: LLM-powered deep scan
-server.tool("deep_scan", "LLM-powered deep security analysis for vulnerabilities that pattern-matching cannot detect: IDOR, business logic flaws, race conditions, stale auth, mass assignment, privilege escalation. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable. Run pattern scan first, then use this for deeper analysis.", {
+server.tool("deep_scan", "LLM-powered deep security analysis for vulnerabilities that pattern-matching cannot detect: IDOR, business logic flaws, race conditions, stale auth, mass assignment, privilege escalation. Defaults to Claude Haiku 4.5 (~cents per scan); pass `model: 'sonnet'` for deeper analysis at higher cost. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY env var.", {
     code: z.string().describe("Code to analyze"),
     language: z.string().describe("Programming language"),
     context: z.string().optional().describe("Additional context (e.g., 'This is a payment endpoint')"),
     existingFindings: z.array(z.string()).default([]).describe("Already-detected findings to avoid duplicating"),
+    focus: z.enum(["all", "idor", "business-logic", "auth-bypass", "race-condition"]).default("all").describe("Focus area — narrows the prompt to a specific vulnerability class"),
+    model: z.enum(["haiku", "sonnet"]).default("haiku").describe("LLM model. haiku = fast & cheap (default), sonnet = deeper analysis"),
+    maxBytes: z.number().int().min(500).max(50_000).default(10_000).describe("Max prompt size in bytes — caps cost. Code over this limit is truncated."),
     format: z.enum(["markdown", "json"]).default("markdown").describe("Output format"),
-}, async ({ code, language, context, existingFindings, format }) => {
-    const prompt = buildDeepScanPrompt(code, language, existingFindings);
-    const llmResponse = await callLLM(context ? `${prompt}\n\nAdditional context: ${context}` : prompt);
+}, async ({ code, language, context, existingFindings, focus, model, maxBytes, format }) => {
+    const prompt = buildDeepScanPrompt(code, language, existingFindings, focus);
+    const fullPrompt = context ? `${prompt}\n\nAdditional context: ${context}` : prompt;
+    const llmResponse = await callLLM(fullPrompt, { model, maxBytes });
     if (llmResponse === null) {
         return {
             content: [{
                     type: "text",
-                    text: "## Deep Scan — Setup Required\n\nNo LLM API key found. Set one of:\n- `ANTHROPIC_API_KEY` — uses Claude\n- `OPENAI_API_KEY` — uses GPT-4o\n\nThe deep scan sends code to the LLM API for semantic vulnerability analysis.",
+                    text: "## Deep Scan — Setup Required\n\nNo LLM API key found. Set one of:\n- `ANTHROPIC_API_KEY` — uses Claude (default: Haiku 4.5; pass `model: 'sonnet'` for deeper analysis)\n- `OPENAI_API_KEY` — uses GPT-4o-mini / GPT-4o\n\nThe deep scan sends code to the LLM API for semantic vulnerability analysis. Default cost is a few cents per scan with Haiku.",
                 }],
         };
     }
@@ -994,6 +998,9 @@ export async function startMcpServer() {
     return main();
 }
 async function main() {
+    // Fire-and-forget npm update check (writes a banner to stderr if newer version exists).
+    const { checkForUpdate } = await import("./utils/update-check.js");
+    checkForUpdate(pkg.version);
     // Load plugins
     const config = loadConfig(process.cwd());
     const plugins = await discoverPlugins(process.cwd(), config.plugins);

package/build/tools/deep-scan.d.ts

@@ -12,10 +12,14 @@ export interface DeepScanFinding {
     location: string;
     fix: string;
 }
+export type DeepScanFocus = "all" | "idor" | "business-logic" | "auth-bypass" | "race-condition";
+export type DeepScanModel = "haiku" | "sonnet";
+export declare const MODEL_IDS: Record<DeepScanModel, string>;
+export declare const DEFAULT_MAX_BYTES = 10000;
 /**
  * Build a structured prompt for the LLM to analyze code.
  */
-export declare function buildDeepScanPrompt(code: string, language: string, existingFindings: string[]): string;
+export declare function buildDeepScanPrompt(code: string, language: string, existingFindings: string[], focus?: DeepScanFocus): string;
 /**
  * Parse LLM response into structured findings.
  * Handles raw JSON, JSON in markdown code blocks, and malformed responses.
@@ -25,9 +29,16 @@ export declare function parseDeepScanResult(response: string): DeepScanFinding[]
  * Format deep scan findings as markdown or JSON.
  */
 export declare function formatDeepScanFindings(findings: DeepScanFinding[], format: "markdown" | "json"): string;
+export interface CallLLMOptions {
+    model?: DeepScanModel;
+    maxBytes?: number;
+}
 /**
  * Call an LLM API for deep analysis. Uses native fetch.
  * Supports Anthropic (ANTHROPIC_API_KEY) or OpenAI (OPENAI_API_KEY).
  * Returns null if no API key is available.
+ *
+ * Defaults to Haiku 4.5 for cost; pass `model: "sonnet"` for higher-quality analysis.
+ * `maxBytes` truncates the prompt to keep cost bounded (default 10 KB).
  */
-export declare function callLLM(prompt: string): Promise<string | null>;
+export declare function callLLM(prompt: string, options?: CallLLMOptions): Promise<string | null>;

package/build/tools/deep-scan.js

@@ -5,7 +5,7 @@
  *
  * Uses native fetch — no extra dependencies.
  */
-const FOCUS_AREAS = [
+const ALL_AREAS = [
     "IDOR (Insecure Direct Object Reference) — can users access resources belonging to other users?",
     "Business logic flaws — are there authorization bypasses, price manipulation, or state machine violations?",
     "Race conditions — are there TOCTOU issues, double-spend, or concurrent mutation without locking?",
@@ -13,18 +13,50 @@ const FOCUS_AREAS = [
     "Mass assignment — can users set fields they shouldn't (role, isAdmin, price)?",
     "Privilege escalation — can a regular user perform admin actions through parameter manipulation?",
 ];
+const FOCUS_AREAS = {
+    all: ALL_AREAS,
+    idor: [
+        "IDOR (Insecure Direct Object Reference) — can users access resources belonging to other users?",
+        "Missing ownership scope on database queries (where: { id } instead of { id, userId })",
+        "URL/path parameters used directly as DB keys without authorization gate",
+    ],
+    "business-logic": [
+        "Authorization bypass via parameter manipulation (e.g., role/isAdmin in body)",
+        "Price/amount manipulation or coupon stacking",
+        "State machine violations (skip steps, replay completed actions)",
+        "Idempotency / replay protection on payment / order paths",
+    ],
+    "auth-bypass": [
+        "Missing or insufficient auth check before sensitive operations",
+        "Stale tokens / sessions still accepted after revoke",
+        "Cookie / JWT validation skipped on a subset of routes",
+        "Privilege-elevation through parameter manipulation",
+    ],
+    "race-condition": [
+        "TOCTOU between read and write (check-then-act without locking)",
+        "Concurrent rate-limit increments without atomic ops",
+        "Double-spend / double-grant via parallel requests",
+        "Optimistic-update races on shared mutable state",
+    ],
+};
+export const MODEL_IDS = {
+    haiku: "claude-haiku-4-5-20251001",
+    sonnet: "claude-sonnet-4-6",
+};
+export const DEFAULT_MAX_BYTES = 10_000;
 /**
  * Build a structured prompt for the LLM to analyze code.
  */
-export function buildDeepScanPrompt(code, language, existingFindings) {
+export function buildDeepScanPrompt(code, language, existingFindings, focus = "all") {
+    const areas = FOCUS_AREAS[focus] ?? FOCUS_AREAS.all;
     const lines = [
         "You are a senior application security engineer performing a deep code review.",
         "Analyze the following code for security vulnerabilities that automated pattern-matching scanners miss.",
         "",
-        "## Focus Areas",
+        `## Focus Areas (${focus})`,
         "",
     ];
-    for (const area of FOCUS_AREAS) {
+    for (const area of areas) {
         lines.push(`- ${area}`);
     }
     lines.push("");
@@ -123,11 +155,20 @@ export function formatDeepScanFindings(findings, format) {
  * Call an LLM API for deep analysis. Uses native fetch.
  * Supports Anthropic (ANTHROPIC_API_KEY) or OpenAI (OPENAI_API_KEY).
  * Returns null if no API key is available.
+ *
+ * Defaults to Haiku 4.5 for cost; pass `model: "sonnet"` for higher-quality analysis.
+ * `maxBytes` truncates the prompt to keep cost bounded (default 10 KB).
  */
-export async function callLLM(prompt) {
+export async function callLLM(prompt, options = {}) {
     // guardvibe-ignore — API URLs are hardcoded trusted endpoints, not user-controlled
     const anthropicKey = process.env.ANTHROPIC_API_KEY;
     const openaiKey = process.env.OPENAI_API_KEY;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const model = options.model ?? "haiku";
+    // Truncate prompt to keep token budget bounded
+    const trimmedPrompt = prompt.length > maxBytes
+        ? prompt.slice(0, maxBytes) + "\n\n[truncated by GuardVibe to stay within budget]"
+        : prompt;
     if (anthropicKey) {
         const res = await fetch("https://api.anthropic.com/v1/messages", {
             method: "POST",
@@ -137,9 +178,9 @@ export async function callLLM(prompt) {
                 "anthropic-version": "2023-06-01",
             },
             body: JSON.stringify({
-                model: "claude-sonnet-4-6",
+                model: MODEL_IDS[model],
                 max_tokens: 2048,
-                messages: [{ role: "user", content: prompt }],
+                messages: [{ role: "user", content: trimmedPrompt }],
             }),
         });
         if (!res.ok)
@@ -155,9 +196,9 @@ export async function callLLM(prompt) {
                 "Authorization": `Bearer ${openaiKey}`,
             },
             body: JSON.stringify({
-                model: "gpt-4o",
+                model: model === "sonnet" ? "gpt-4o" : "gpt-4o-mini",
                 max_tokens: 2048,
-                messages: [{ role: "user", content: prompt }],
+                messages: [{ role: "user", content: trimmedPrompt }],
             }),
         });
         if (!res.ok)

package/build/utils/update-check.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Non-blocking npm update notification.
+ *
+ * On startup of the CLI or MCP server, fires an async GET against
+ * https://registry.npmjs.org/guardvibe/latest. Result is cached for 24h
+ * in ~/.cache/guardvibe/version-check.json so we never hit npm twice in
+ * a day from one machine. If a newer version is available, a 5-line
+ * banner is written to stderr — never stdout, so the MCP JSON-RPC stream
+ * is untouched.
+ *
+ * Disable with GUARDVIBE_NO_UPDATE_CHECK=1, NO_UPDATE_NOTIFIER=1,
+ * or CI=true (CI runners don't need version banners).
+ */
+/**
+ * Compare two semver strings. Returns true if `latest` is strictly newer.
+ * Handles plain MAJOR.MINOR.PATCH (no pre-release / build metadata).
+ */
+export declare function isNewer(latest: string, current: string): boolean;
+/**
+ * Fire-and-forget version check. Never throws, never blocks.
+ *
+ * Behavior:
+ *   - If env var disables it → no-op.
+ *   - If cache is fresh (< 24h) and indicates newer version → announce immediately.
+ *   - If cache is stale → fire async fetch, update cache, announce if newer.
+ */
+export declare function checkForUpdate(currentVersion: string): void;

package/build/utils/update-check.js

@@ -0,0 +1,125 @@
+/**
+ * Non-blocking npm update notification.
+ *
+ * On startup of the CLI or MCP server, fires an async GET against
+ * https://registry.npmjs.org/guardvibe/latest. Result is cached for 24h
+ * in ~/.cache/guardvibe/version-check.json so we never hit npm twice in
+ * a day from one machine. If a newer version is available, a 5-line
+ * banner is written to stderr — never stdout, so the MCP JSON-RPC stream
+ * is untouched.
+ *
+ * Disable with GUARDVIBE_NO_UPDATE_CHECK=1, NO_UPDATE_NOTIFIER=1,
+ * or CI=true (CI runners don't need version banners).
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir, tmpdir } from "node:os";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const NPM_URL = "https://registry.npmjs.org/guardvibe/latest";
+const FETCH_TIMEOUT_MS = 2000;
+function cachePath() {
+    const home = process.env.HOME ?? homedir();
+    const baseDir = home && home.length > 0 ? join(home, ".cache", "guardvibe") : join(tmpdir(), "guardvibe");
+    return join(baseDir, "version-check.json");
+}
+function readCache() {
+    try {
+        const raw = readFileSync(cachePath(), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(data) {
+    try {
+        const path = cachePath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(data));
+    }
+    catch {
+        // Cache write failure is non-fatal; silently swallow.
+    }
+}
+/**
+ * Compare two semver strings. Returns true if `latest` is strictly newer.
+ * Handles plain MAJOR.MINOR.PATCH (no pre-release / build metadata).
+ */
+export function isNewer(latest, current) {
+    const parse = (v) => v.split(".").map(n => parseInt(n, 10));
+    const la = parse(latest);
+    const ca = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const l = la[i] ?? 0;
+        const c = ca[i] ?? 0;
+        if (l !== c)
+            return l > c;
+    }
+    return false;
+}
+async function fetchLatest() {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+        // guardvibe-ignore VG120 — NPM_URL is a hardcoded module-level constant, not user input
+        const res = await fetch(NPM_URL, { signal: ctrl.signal });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return typeof data.version === "string" ? data.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function announceUpdate(latest, current) {
+    const lines = [
+        "",
+        "  ┌──────────────────────────────────────────────────────────┐",
+        `  │  GuardVibe ${current} → ${latest} available`,
+        "  │  Upgrade: re-run `npx guardvibe init <host>` to pin the new",
+        "  │           version into your .mcp.json (or `npx guardvibe@latest`)",
+        "  │  Silence: set GUARDVIBE_NO_UPDATE_CHECK=1",
+        "  └──────────────────────────────────────────────────────────┘",
+        "",
+    ];
+    process.stderr.write(lines.join("\n"));
+}
+function isDisabled() {
+    return (process.env.GUARDVIBE_NO_UPDATE_CHECK === "1" ||
+        process.env.NO_UPDATE_NOTIFIER === "1" ||
+        process.env.CI === "true" ||
+        process.env.CI === "1");
+}
+/**
+ * Fire-and-forget version check. Never throws, never blocks.
+ *
+ * Behavior:
+ *   - If env var disables it → no-op.
+ *   - If cache is fresh (< 24h) and indicates newer version → announce immediately.
+ *   - If cache is stale → fire async fetch, update cache, announce if newer.
+ */
+export function checkForUpdate(currentVersion) {
+    if (isDisabled())
+        return;
+    const cache = readCache();
+    const now = Date.now();
+    if (cache && cache.latest && now - cache.checkedAt < CACHE_TTL_MS) {
+        if (isNewer(cache.latest, currentVersion)) {
+            announceUpdate(cache.latest, currentVersion);
+        }
+        return;
+    }
+    // Cache missing or stale — refresh in background, don't await.
+    fetchLatest()
+        .then(latest => {
+        writeCache({ checkedAt: now, latest });
+        if (latest && isNewer(latest, currentVersion)) {
+            announceUpdate(latest, currentVersion);
+        }
+    })
+        .catch(() => {
+        // Non-fatal.
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardvibe",
-  "version": "3.0.57",
+  "version": "3.1.1",
   "mcpName": "io.github.goklab/guardvibe",
   "description": "Security MCP for vibe coding. 390 rules, 36 tools, CLI + doctor. Host security, auth coverage mapping, LLM-powered deep scan (IDOR/business logic), taint analysis, +25 AI-native rules (MCP supply-chain, RAG/vector poisoning, agent loop DoS, public-prefix LLM keys, sandbox bypass). Plus Next.js, Supabase, Clerk, Stripe, Prisma, tRPC, Hono, GraphQL, Convex, Turso, Uploadthing, AI SDK, and the full AI-generated stack.",
   "type": "module",