guardvibe 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to GuardVibe are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0] - 2026-06-07
+
+### Fixed — VG120 SSRF false-positive narrowing (sustain 0-FP) (438 rules / 37 tools)
+- **VG120 (SSRF) no longer fires on URLs that are provably not request-controlled.** The regex flags `fetch(variable)` for any bare identifier; it now skips when the URL variable is assigned from a **literal `https://` constant** or **`process.env`** (including an env default parameter, e.g. `webhook = process.env.SOLUTIONS_WEBHOOK`), and skips **minified bundles**. `new URL(...)` is deliberately NOT treated as safe (it may wrap user input).
+- **Validated against the corpus (clean old-vs-new diff): 1 false positive removed, 0 true positives lost, 0 new findings, 0 drift in any other rule.** Recall on genuinely user-controlled URLs is preserved (covered by tests).
+- **Honest limitation:** URLs built from a constant *base variable* (`` `${apiBase}/path` ``) or returned from a helper still need real dataflow to classify safely, so they are intentionally left as-is for a future AST/dataflow engine rather than narrowed by regex (which would risk hiding a real SSRF). The precise signal for user-input→request flows already exists via the SSRF taint sink.
+- No rule or tool changes (438 / 37).
+
+Gate green (build / lint / test / self-audit PASS / A / 0).
+
+## [3.5.0] - 2026-06-07
+
+### Added — agent-native structured output (`guardvibe.agent.v1`) (438 rules / 37 tools)
+- **New `agent` output format** that returns one stable, documented contract per finding so a coding agent can act on data instead of parsing prose: `{ id, name, severity, owasp, file, line, confidence, autoFixable, exactEdit, manualFix, verify }`.
+- **`exactEdit`** is the structured line edit when the finding is auto-applicable (from `fix_code`); **`confidence`** is surfaced per finding; **`verify`** is a deterministic, runnable step (`guardvibe check … --format json`, expect the rule absent) so the agent can *prove* the fix landed.
+- Exposed via CLI `guardvibe check <file> --format agent` and the MCP `scan_file` tool (`format: "agent"`). New module `src/tools/agent-output.ts` (`buildAgentReport`); deterministic, no new dependency.
+- This unifies what was scattered across `fix_code`, `scan_file` and per-finding confidence into a single agent contract; complements `secure_this` (auto-apply loop) with a structured manual-fix path.
+- No rule or tool changes (438 / 37).
+
+Gate green (build / lint / test / self-audit PASS / A / 0).
+
 ## [3.4.0] - 2026-06-07
 
 ### Added — dependency reachability: is the vulnerable package actually imported? (438 rules / 37 tools)

package/README.md

@@ -330,7 +330,9 @@ npx guardvibe-scan                   # Scan staged files (for pre-commit)
 npx guardvibe-scan --format sarif --output results.sarif  # CI mode
 
 # Options (all scan commands)
-#   --format markdown|json|sarif|buddy
+#   --format markdown|json|sarif|buddy|agent
+#       agent = guardvibe.agent.v1 — per finding: { id, severity, confidence, exactEdit, manualFix, verify }
+#       so an AI agent can apply the exact edit and run the verify step to prove the fix
 #   --output <file>     Write results to file
 #   --fail-on <level>   Exit 1 on findings: critical|high|medium|low|none
 #   --full              Bypass response-size caps (50 JSON / 30 markdown / 200-file taint)

package/build/cli/args.js

@@ -1,7 +1,7 @@
 /**
  * CLI argument parsing utilities
  */
-const VALID_FORMATS = new Set(["markdown", "json", "sarif", "buddy"]);
+const VALID_FORMATS = new Set(["markdown", "json", "sarif", "buddy", "agent"]);
 export function getStringFlag(flags, key) {
     const val = flags[key];
     if (val === undefined || val === true)

package/build/cli/scan.js

@@ -206,9 +206,17 @@ export async function runFileCheck(filePath, flags) {
         process.exit(1);
     }
     const format = validateFormat(flags);
-    const formatArg = format === "json" ? "json" : format === "buddy" ? "buddy" : "markdown";
     const findings = analyzeFileSecurity(content, language, undefined, resolved, undefined);
-    const result = renderFindings(findings, language, undefined, formatArg, resolved);
+    let result;
+    if (format === "agent") {
+        // Agent-native contract: finding + exact-edit + confidence + verify step.
+        const { buildAgentReport } = await import("../tools/agent-output.js");
+        result = JSON.stringify(buildAgentReport(findings, content, language, resolved));
+    }
+    else {
+        const formatArg = format === "json" ? "json" : format === "buddy" ? "buddy" : "markdown";
+        result = renderFindings(findings, language, undefined, formatArg, resolved);
+    }
     const outputFile = getOutputPath(flags);
     if (outputFile) {
         safeWriteOutput(outputFile, result);

package/build/cli.js

@@ -44,7 +44,8 @@ function printUsage() {
     npx guardvibe-scan --format sarif --output results.sarif
 
   Options:
-    --format <type>       Output format: markdown (default), json, sarif, buddy
+    --format <type>       Output format: markdown (default), json, sarif, buddy, agent
+                          agent = guardvibe.agent.v1 (finding + exact edit + confidence + verify)
     --output <file>       Write results to file instead of stdout
     --fail-on <level>     Exit 1 when findings at this level or above exist
                           critical (default) | high | medium | low | none

package/build/index.js

@@ -42,6 +42,7 @@ import { formatHostFindings, redactSecrets } from "./server/types.js";
 import { verifyFix } from "./tools/verify-fix.js";
 import { fixCode as fixCodeTool } from "./tools/fix-code.js";
 import { secureThis } from "./tools/secure-this.js";
+import { buildAgentReport } from "./tools/agent-output.js";
 import { analyzeAuthCoverage, formatAuthCoverage } from "./tools/auth-coverage.js";
 import { buildDeepScanPrompt, parseDeepScanResult, formatDeepScanFindings, callLLM } from "./tools/deep-scan.js";
 import { runFullAudit, formatAuditResult } from "./tools/full-audit.js";
@@ -506,9 +507,9 @@ server.tool("explain_remediation", "Pass a GuardVibe rule ID (e.g. VG154) to get
 });
 // Tool 23: Quick file scan — returns structured findings, not raw file contents.
 // guardvibe-ignore VG880
-server.tool("scan_file", "Scan a single file on disk by path for security vulnerabilities. Pass a file path — the tool reads the file itself. For inline code snippets, use check_code instead. Example: scan_file({file_path: 'src/api/route.ts'})", {
+server.tool("scan_file", "Scan a single file on disk by path for security vulnerabilities. Pass a file path — the tool reads the file itself. For inline code snippets, use check_code instead. The 'agent' format returns the structured guardvibe.agent.v1 contract (finding + exact edit + confidence + verify step). Example: scan_file({file_path: 'src/api/route.ts', format: 'agent'})", {
     file_path: z.string().describe("Absolute or relative path to the file to scan"),
-    format: z.enum(["markdown", "json"]).default("json").describe("Output format"),
+    format: z.enum(["markdown", "json", "agent"]).default("json").describe("Output format. 'agent' = machine-actionable guardvibe.agent.v1 (exact edits + confidence + verify)"),
 }, async ({ file_path, format }) => {
     const { readFileSync, existsSync } = await import("fs");
     const { resolve, extname, basename, dirname } = await import("path");
@@ -529,6 +530,11 @@ server.tool("scan_file", "Scan a single file on disk by path for security vulner
     }
     const rules = getRules();
     const findings = analyzeFileSecurity(content, language, undefined, resolved, dirname(resolved), rules);
+    if (format === "agent") {
+        const cwdA = dirname(resolved);
+        recordScan(cwdA, { toolName: "scan_file", filesScanned: 1, findings: findings.map(f => ({ severity: f.rule.severity, ruleId: f.rule.id })) });
+        return { content: [{ type: "text", text: JSON.stringify(buildAgentReport(findings, content, language, resolved, rules)) }] };
+    }
     const result = renderFindings(findings, language, undefined, format, resolved);
     const cwd = dirname(resolved);
     recordScan(cwd, { toolName: "scan_file", filesScanned: 1, findings: findings.map(f => ({ severity: f.rule.severity, ruleId: f.rule.id })) });

package/build/tools/agent-output.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agent-native structured output (FAZ 4).
+ *
+ * Coding agents act on data, not prose. This builds one stable, documented
+ * contract per finding so an agent can: read severity + confidence, apply the
+ * exact edit deterministically when one exists, and run a verify step to prove
+ * the issue is gone. It unifies what was scattered across fix_code (edits),
+ * scan_file (suggested_fixes) and the finding's own confidence into a single
+ * `guardvibe.agent.v1` shape.
+ *
+ * No new dependency, fully deterministic (same findings + code → same report).
+ */
+import type { Finding } from "./check-code.js";
+import { type StructuredEdit } from "./fix-code.js";
+import type { SecurityRule } from "../data/rules/types.js";
+export interface AgentFinding {
+    id: string;
+    name: string;
+    severity: string;
+    owasp?: string;
+    file: string;
+    line: number;
+    confidence: "high" | "medium" | "low";
+    autoFixable: boolean;
+    exactEdit: StructuredEdit | null;
+    manualFix: string;
+    /** A deterministic, runnable step that proves the finding is resolved. */
+    verify: {
+        command: string;
+        expect: string;
+    };
+}
+export interface AgentReport {
+    schema: "guardvibe.agent.v1";
+    file: string;
+    total: number;
+    autoFixable: number;
+    findings: AgentFinding[];
+}
+/**
+ * Normalize a file's findings into the agent-native contract. `fixCode` is run
+ * once to attach exact edits to the findings that have one.
+ */
+export declare function buildAgentReport(findings: Finding[], code: string, language: string, filePath: string, rules?: SecurityRule[]): AgentReport;

package/build/tools/agent-output.js

@@ -0,0 +1,45 @@
+import { fixCode } from "./fix-code.js";
+/**
+ * Normalize a file's findings into the agent-native contract. `fixCode` is run
+ * once to attach exact edits to the findings that have one.
+ */
+export function buildAgentReport(findings, code, language, filePath, rules) {
+    // Map ruleId+line → structured edit (only auto-applicable rules yield one).
+    const edits = new Map();
+    if (findings.length > 0) {
+        try {
+            const parsed = JSON.parse(fixCode(code, language, undefined, filePath, "json", rules));
+            for (const fx of parsed.fixes ?? []) {
+                if (fx.edit)
+                    edits.set(`${fx.ruleId}:${fx.line}`, fx.edit);
+            }
+        }
+        catch { /* fixCode is best-effort; findings still report without edits */ }
+    }
+    const agentFindings = findings.map(f => {
+        const exactEdit = edits.get(`${f.rule.id}:${f.line}`) ?? null;
+        return {
+            id: f.rule.id,
+            name: f.rule.name,
+            severity: f.rule.severity,
+            owasp: f.rule.owasp,
+            file: filePath,
+            line: f.line,
+            confidence: f.confidence,
+            autoFixable: !!exactEdit,
+            exactEdit,
+            manualFix: f.rule.fix,
+            verify: {
+                command: `npx guardvibe check ${filePath} --format json`,
+                expect: `${f.rule.id} no longer reported at ${filePath}:${f.line}`,
+            },
+        };
+    });
+    return {
+        schema: "guardvibe.agent.v1",
+        file: filePath,
+        total: agentFindings.length,
+        autoFixable: agentFindings.filter(f => f.autoFixable).length,
+        findings: agentFindings,
+    };
+}

package/build/tools/check-code.js

@@ -3,6 +3,7 @@ import { owaspRules } from "../data/rules/index.js";
 import { loadConfig } from "../utils/config.js";
 import { loadIgnoreFile, isIgnored } from "../utils/ignore.js";
 import { securityBanner } from "../utils/banner.js";
+import { looksMinified } from "../utils/constants.js";
 /** CVE version-pin rule IDs are VG900-VG931 (and only these). Other VG9xx IDs
  * (VG983 Turso, VG990 SVG, VG998 OpenAI browser flag, etc.) are regular code-pattern
  * rules and should NOT be exempted from comment / string-literal skip logic. */
@@ -873,6 +874,25 @@ export function analyzeCode(code, language, framework, filePath, configDir, rule
                         continue;
                 }
             }
+            // VG120 (SSRF via User-Controlled URL): the regex flags `fetch(variable)` for any
+            // bare identifier, so it over-fires on constant/config endpoints. Safely skip the
+            // cases that are provably NOT request-controlled: a minified bundle (not real
+            // source; taint already skips these), or a URL variable assigned from a literal
+            // https:// constant or process.env (incl. an env default parameter). Template URLs
+            // built from a constant *base var* (`${apiBase}/path`) and method-returned URLs
+            // need real dataflow to classify and are deliberately LEFT for the AST engine —
+            // narrowing them by regex would risk hiding a genuine SSRF. `new URL(...)` is NOT
+            // treated as safe (it may wrap user input).
+            if (rule.id === "VG120") {
+                if (looksMinified(code))
+                    continue;
+                const v = match[0].match(/\(\s*([A-Za-z_$]\w*)\s*[,)]/)?.[1];
+                if (v) {
+                    const safeOrigin = new RegExp(`\\b${v}\\s*=\\s*(?:["'\\\`]https?:\\/\\/|process\\.env\\b)`);
+                    if (safeOrigin.test(code))
+                        continue;
+                }
+            }
             // Skip matches on comment lines and inside string literals.
             // CVE version-pin rules (VG900-VG931) are exempt — they scan package.json
             // dependency declarations where these contexts don't apply.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardvibe",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "mcpName": "io.github.goklab/guardvibe",
   "description": "Security infrastructure your AI can't be — deterministic, current past your model's training cutoff, whole-repo-aware, author-independent. Security MCP for vibe coding. 438 rules, 37 tools, CLI + doctor. Host security, auth coverage mapping, LLM-powered deep scan (IDOR/business logic), taint analysis. 67 CVE rules refreshed daily from GHSA/OSV/CISA KEV — Miasma @redhat-cloud-services compromise, Next.js May 2026 13-advisory cluster, Drizzle/MikroORM/Kysely SQL injection, Axios proxy-auth redirect leak, Hono setCookie attribute injection, Clerk SSRF, tRPC prototype pollution, @tanstack supply-chain, node-ipc protestware, OpenClaude sandbox bypass, plus the full AI-generated stack (Supabase, Stripe, Prisma, Hono, GraphQL, Convex, Turso, Uploadthing, AI SDK). 68 AI-native rules including OWASP MCP Top 10 tool-description prompt injection (VG1068), model-controlled sandbox-disable flag detection (VG1063), Session messenger exfil endpoint IOC (VG1075), and CI/CD supply-chain hardening (VG1070 npm --expect-provenance / --ignore-scripts enforcement).",
   "type": "module",