guardvibe 3.0.57 → 3.1.0

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

@@ -28,6 +28,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 +153,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.",
                 }],
         };
     }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardvibe",
-  "version": "3.0.57",
+  "version": "3.1.0",
   "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",