guardvibe 3.1.1 → 3.1.3

package/README.md

@@ -64,7 +64,7 @@ GuardVibe is purpose-built for the AI coding workflow. Traditional tools are exc
 npx guardvibe init claude
 ```
 
-Creates `.claude.json` MCP config, `.claude/settings.json` auto-scan hooks, and `CLAUDE.md` security rules. Restart Claude Code after setup.
+Creates `.mcp.json` MCP config (pinned to current version), `.claude/settings.json` auto-scan hooks, and `CLAUDE.md` security rules. Restart Claude Code after setup.
 
 ### Cursor
 
@@ -286,6 +286,13 @@ npx guardvibe doctor --scope host    # + shell profiles, global MCP configs
 npx guardvibe doctor --scope full    # + home dir configs
 npx guardvibe doctor --format json   # JSON output
 
+# LLM-powered deep scan (IDOR, business logic, race conditions, auth bypass)
+npx guardvibe deep-scan <file>                  # Default: Haiku 4.5, all focus areas
+npx guardvibe deep-scan <file> --focus idor     # Narrow to IDOR
+npx guardvibe deep-scan <file> --model sonnet   # Deeper analysis (more expensive)
+npx guardvibe deep-scan <file> --max-bytes 5000 # Truncate input for cost control
+# Requires ANTHROPIC_API_KEY or OPENAI_API_KEY env var
+
 # Setup
 npx guardvibe init <platform>       # Setup MCP server (claude, cursor, gemini, all)
 npx guardvibe hook install           # Install pre-commit hook
@@ -443,9 +450,10 @@ If your AI agent cannot connect to GuardVibe:
 
 1. **Restart your IDE/agent.** MCP servers are started by the host application. After running `npx guardvibe init`, restart Claude Code, Cursor, or Gemini CLI for the config to take effect.
 2. **Check the config path.** Run `npx guardvibe init claude` again and verify the output shows the correct config file location (`.mcp.json` in your project root for Claude Code, `.cursor/mcp.json` for Cursor).
-3. **Re-run `init` to upgrade.** When upgrading GuardVibe, re-run `npx guardvibe init claude` — `.mcp.json` is pinned to a specific version (e.g. `guardvibe@3.0.41`) at init time for fast deterministic startup. Stale pins won't auto-update.
-4. **Verify Node.js version.** GuardVibe requires Node.js >= 18.0.0. Check with `node --version`.
-5. **Check npx cache.** If you upgraded GuardVibe and the old version is cached, run `npx -y guardvibe@latest` to force the latest version.
+3. **Re-run `init` to upgrade.** When upgrading GuardVibe, re-run `npx guardvibe init claude` — `.mcp.json` is pinned to a specific version (e.g. `guardvibe@3.1.3`) at init time for fast deterministic startup. As of v3.1.2 the re-run also rewrites stale pins automatically (`Upgraded GuardVibe pin (3.0.55 → 3.1.3)`). The same applies to `npx guardvibe hook install` and `npx guardvibe ci github` (since v3.1.3) — both are version-pinned at install/generate time and re-run to upgrade.
+4. **Pre-3.1.1 users won't see the auto-update banner.** GuardVibe started writing a once-per-day "newer version available" notice to stderr in v3.1.1. If your install predates that, you'll never see it — run `npx -y guardvibe@latest init <host>` once to bake in the latest pin and start receiving banners on subsequent sessions.
+5. **Verify Node.js version.** GuardVibe requires Node.js >= 18.0.0. Check with `node --version`.
+6. **Check npx cache.** If you upgraded GuardVibe and the old version is cached, run `npx -y guardvibe@latest` to force the latest version.
 
 ### Node.js version requirements
 

package/build/cli/ci.js

@@ -2,9 +2,14 @@
  * CLI: guardvibe ci <provider>
  * Generates CI/CD workflow configurations.
  */
-import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { createRequire } from "module";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { join } from "path";
-const GITHUB_ACTIONS_WORKFLOW = `name: GuardVibe Security Scan
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+function buildGithubActionsWorkflow(version) {
+    return `name: GuardVibe Security Scan
+# Pinned to guardvibe@${version} for reproducible CI builds. Re-run \`npx guardvibe ci github\` to upgrade.
 
 on:
   pull_request:
@@ -30,7 +35,7 @@ jobs:
           node-version: "22"
 
       - name: Run GuardVibe security scan
-        run: npx -y guardvibe-scan --format sarif --output guardvibe-results.sarif
+        run: npx -y guardvibe@${version} scan --format sarif --output guardvibe-results.sarif
 
       - name: Upload SARIF to GitHub Security
         if: always()
@@ -39,18 +44,45 @@ jobs:
           sarif_file: guardvibe-results.sarif
           category: guardvibe
 `;
+}
+/** Extract a pinned guardvibe version from a generated workflow YAML, or "latest"/null for legacy/unrecognized forms. */
+function extractPinnedVersionFromWorkflow(content) {
+    const pinned = content.match(/guardvibe@(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
+    if (pinned)
+        return pinned[1];
+    if (/guardvibe-scan|guardvibe@latest/.test(content))
+        return "latest";
+    return null;
+}
 function generateGitHubActions() {
     const workflowDir = join(process.cwd(), ".github", "workflows");
     if (!existsSync(workflowDir)) {
         mkdirSync(workflowDir, { recursive: true });
     }
     const workflowPath = join(workflowDir, "guardvibe.yml");
+    const fresh = buildGithubActionsWorkflow(pkg.version);
     if (existsSync(workflowPath)) {
-        console.log("  [OK] .github/workflows/guardvibe.yml already exists.");
+        const existing = readFileSync(workflowPath, "utf-8");
+        const existingPin = extractPinnedVersionFromWorkflow(existing);
+        if (existingPin === pkg.version) {
+            console.log(`  [OK] .github/workflows/guardvibe.yml already up-to-date (pinned to v${pkg.version}).`);
+            return;
+        }
+        if (existingPin && existingPin !== "latest") {
+            writeFileSync(workflowPath, fresh, "utf-8");
+            console.log(`  [OK] Upgraded .github/workflows/guardvibe.yml (${existingPin} → ${pkg.version}).`);
+            return;
+        }
+        if (existingPin === "latest") {
+            writeFileSync(workflowPath, fresh, "utf-8");
+            console.log(`  [OK] Pinned .github/workflows/guardvibe.yml (was unpinned → ${pkg.version}).`);
+            return;
+        }
+        console.log("  [OK] .github/workflows/guardvibe.yml exists with custom contents — leaving as-is.");
         return;
     }
-    writeFileSync(workflowPath, GITHUB_ACTIONS_WORKFLOW, "utf-8");
-    console.log("  [OK] Created .github/workflows/guardvibe.yml");
+    writeFileSync(workflowPath, fresh, "utf-8");
+    console.log(`  [OK] Created .github/workflows/guardvibe.yml (pinned to v${pkg.version}).`);
     console.log("  [OK] SARIF results will appear in GitHub Security tab.");
 }
 export function runCi(args) {

package/build/cli/hook.js

@@ -2,16 +2,23 @@
  * CLI: guardvibe hook install|uninstall
  * Manages pre-commit security hooks.
  */
+import { createRequire } from "module";
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, unlinkSync } from "fs";
 import { join } from "path";
-const HOOK_SCRIPT = `#!/bin/sh
-# GuardVibe pre-commit security hook
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+const GUARDVIBE_BLOCK_START = "# GuardVibe pre-commit security hook";
+const GUARDVIBE_BLOCK_END = "✅ GuardVibe: all checks passed.";
+function buildHookScript(version) {
+    return `#!/bin/sh
+${GUARDVIBE_BLOCK_START}
 # Installed by: npx guardvibe hook install
+# Pinned to v${version} for reproducible CI/local behavior. Re-run install to upgrade.
 
 echo "🔒 GuardVibe: scanning staged files..."
 
 # Run guardvibe scan on staged files
-RESULT=$(npx -y guardvibe@latest scan --staged 2>&1)
+RESULT=$(npx -y guardvibe@${version} scan --staged 2>&1)
 EXIT_CODE=$?
 
 if [ $EXIT_CODE -ne 0 ]; then
@@ -22,8 +29,33 @@ if [ $EXIT_CODE -ne 0 ]; then
   exit 1
 fi
 
-echo "✅ GuardVibe: all checks passed."
+echo "${GUARDVIBE_BLOCK_END}"
 `;
+}
+/**
+ * Extract the pinned GuardVibe version from an existing pre-commit hook.
+ * Returns the version string, "latest" for legacy unpinned hooks, or null if no GuardVibe block found.
+ */
+function extractPinnedVersionFromHook(content) {
+    const pinnedMatch = content.match(/guardvibe@(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
+    if (pinnedMatch)
+        return pinnedMatch[1];
+    if (/guardvibe@latest|npx\s+-y\s+guardvibe(?:\s|\b)/.test(content) && content.includes("GuardVibe")) {
+        return "latest";
+    }
+    return null;
+}
+function replaceGuardVibeBlock(existing, fresh) {
+    // Strip any prior GuardVibe block (with or without leading shebang) and append the fresh one.
+    const cleaned = existing
+        .replace(/\n?# GuardVibe pre-commit security hook[\s\S]*?GuardVibe: all checks passed[."]*\n?/g, "")
+        .trimEnd();
+    if (!cleaned || cleaned === "#!/bin/sh")
+        return fresh;
+    // Splice the GuardVibe section in (without its shebang) onto the existing hook.
+    const freshNoShebang = fresh.replace(/^#!\/bin\/sh\n/, "");
+    return cleaned + "\n\n" + freshNoShebang;
+}
 function installHook() {
     const gitDir = join(process.cwd(), ".git");
     if (!existsSync(gitDir)) {
@@ -35,19 +67,33 @@ function installHook() {
         mkdirSync(hooksDir, { recursive: true });
     }
     const hookPath = join(hooksDir, "pre-commit");
+    const freshScript = buildHookScript(pkg.version);
     if (existsSync(hookPath)) {
         const existing = readFileSync(hookPath, "utf-8");
-        if (existing.includes("GuardVibe")) {
-            console.log("  [OK] GuardVibe pre-commit hook already installed.");
+        const existingPin = extractPinnedVersionFromHook(existing);
+        if (existingPin === pkg.version) {
+            console.log(`  [OK] GuardVibe pre-commit hook already up-to-date (v${pkg.version}).`);
+            return;
+        }
+        if (existingPin && existingPin !== "latest") {
+            writeFileSync(hookPath, replaceGuardVibeBlock(existing, freshScript), "utf-8");
+            chmodSync(hookPath, 0o755);
+            console.log(`  [OK] Upgraded GuardVibe pre-commit hook (${existingPin} → ${pkg.version}).`);
+            return;
+        }
+        if (existingPin === "latest") {
+            writeFileSync(hookPath, replaceGuardVibeBlock(existing, freshScript), "utf-8");
+            chmodSync(hookPath, 0o755);
+            console.log(`  [OK] Pinned GuardVibe pre-commit hook (was unpinned → ${pkg.version}).`);
             return;
         }
-        writeFileSync(hookPath, existing + "\n" + HOOK_SCRIPT, "utf-8");
+        writeFileSync(hookPath, existing.trimEnd() + "\n\n" + freshScript, "utf-8");
         console.log("  [OK] GuardVibe added to existing pre-commit hook.");
     }
     else {
-        writeFileSync(hookPath, HOOK_SCRIPT, "utf-8");
+        writeFileSync(hookPath, freshScript, "utf-8");
         chmodSync(hookPath, 0o755);
-        console.log("  [OK] Pre-commit hook installed at .git/hooks/pre-commit");
+        console.log(`  [OK] Pre-commit hook installed at .git/hooks/pre-commit (pinned to v${pkg.version}).`);
     }
 }
 function uninstallHook() {

package/build/cli/init.js

@@ -14,6 +14,18 @@ const GUARDVIBE_MCP_CONFIG = {
     command: "npx",
     args: ["-y", `guardvibe@${pkg.version}`],
 };
+/** Extract a pinned version from an existing MCP server config (`{ args: ["-y", "guardvibe@X.Y.Z"] }`). */
+function extractPinnedVersion(config) {
+    const args = config?.args;
+    if (!Array.isArray(args))
+        return null;
+    for (const arg of args) {
+        if (typeof arg === "string" && arg.startsWith("guardvibe@")) {
+            return arg.slice("guardvibe@".length);
+        }
+    }
+    return null;
+}
 const platforms = {
     claude: {
         path: join(process.cwd(), ".mcp.json"),
@@ -177,12 +189,27 @@ function setupPlatform(name) {
         if (!existing.mcpServers) {
             existing.mcpServers = {};
         }
-        if (existing.mcpServers["guardvibe"]) {
-            console.log(`  [OK] GuardVibe already configured in ${platform.description}`);
+        const servers = existing.mcpServers;
+        if (servers["guardvibe"]) {
+            const existingPin = extractPinnedVersion(servers["guardvibe"]);
+            if (existingPin && existingPin !== pkg.version) {
+                servers["guardvibe"] = GUARDVIBE_MCP_CONFIG;
+                writeJsonFile(platform.path, existing);
+                console.log(`  [OK] Upgraded GuardVibe pin in ${platform.description} (${existingPin} → ${pkg.version})`);
+            }
+            else if (!existingPin) {
+                // Existing config has no pin (legacy unpinned form) — overwrite to pin.
+                servers["guardvibe"] = GUARDVIBE_MCP_CONFIG;
+                writeJsonFile(platform.path, existing);
+                console.log(`  [OK] Pinned GuardVibe in ${platform.description} (was unpinned → ${pkg.version})`);
+            }
+            else {
+                console.log(`  [OK] GuardVibe already up-to-date in ${platform.description} (v${pkg.version})`);
+            }
             setupSecurityGuide(name);
             return true;
         }
-        existing.mcpServers["guardvibe"] = GUARDVIBE_MCP_CONFIG;
+        servers["guardvibe"] = GUARDVIBE_MCP_CONFIG;
         writeJsonFile(platform.path, existing);
     }
     else {

package/build/data/compliance-metadata.js

@@ -15,8 +15,8 @@ export const complianceMetadata = {
     VG002: {
         gdpr: ["GDPR:Art32(1)(b)"],
         iso27001: ["ISO27001:A.8.3", "ISO27001:A.8.24"],
-        exploit: "Attacker sends crafted SQL input through unvalidated form fields or URL parameters to extract, modify, or delete database records.",
-        audit: "Demonstrate that all database queries use parameterized statements or ORM methods. Show code review checklist that includes SQL injection testing.",
+        exploit: "Attacker accesses API endpoints or resources without authentication, reading or modifying data belonging to other users.",
+        audit: "Show middleware/auth layer that protects all sensitive endpoints. Demonstrate that unauthenticated requests return 401/403.",
     },
     VG003: {
         gdpr: ["GDPR:Art32(1)(a)"],
@@ -27,8 +27,8 @@ export const complianceMetadata = {
     VG010: {
         gdpr: ["GDPR:Art32(1)(b)", "GDPR:Art25"],
         iso27001: ["ISO27001:A.8.3", "ISO27001:A.5.15"],
-        exploit: "Attacker accesses API endpoints or resources without authentication, reading or modifying data belonging to other users.",
-        audit: "Show middleware/auth layer that protects all sensitive endpoints. Demonstrate that unauthenticated requests return 401/403.",
+        exploit: "Attacker sends crafted SQL input (e.g., ' OR 1=1--, UNION SELECT, ;DROP TABLE) through unvalidated form fields, URL parameters, or JSON body to extract, modify, or delete database records.",
+        audit: "Demonstrate that all database queries use parameterized statements or ORM methods. Show code review checklist that includes SQL injection testing.",
     },
     VG042: {
         gdpr: ["GDPR:Art32(1)(a)"],

package/build/tools/explain-remediation.js

@@ -66,8 +66,10 @@ function getBreakingRisk(rule) {
     const id = rule.id;
     if (["VG001", "VG062", "VG060"].includes(id))
         return "LOW — Moving to env vars requires .env setup but no code logic changes.";
-    if (["VG402", "VG010", "VG952"].includes(id))
+    if (["VG402", "VG952"].includes(id))
         return "MEDIUM — Adding auth checks may break unauthenticated flows that were working. Test all affected endpoints.";
+    if (["VG010", "VG011", "VG013", "VG014"].includes(id))
+        return "LOW — Parameterized queries are drop-in replacements for most drivers/ORMs. Manual string-concat call sites may need light refactoring; run query coverage after the swap.";
     if (["VG401", "VG960"].includes(id))
         return "MEDIUM — Adding schema validation will reject previously accepted invalid input. Test with real user data.";
     if (["VG403", "VG500", "VG510"].includes(id))
@@ -88,8 +90,10 @@ function getTestStrategy(rule) {
     const id = rule.id;
     if (["VG001", "VG062", "VG060"].includes(id))
         return "1. Move value to .env\n2. Verify app still reads from env\n3. Confirm old hardcoded value removed from git history";
-    if (["VG402", "VG010"].includes(id))
+    if (["VG402"].includes(id))
         return "1. Call endpoint without auth token → expect 401\n2. Call with valid token → expect success\n3. Call with expired token → expect 401";
+    if (["VG010", "VG011", "VG013", "VG014"].includes(id))
+        return "1. Replace concatenated SQL with parameterized query / prepared statement\n2. Submit a malicious payload (`' OR 1=1--`, `;DROP TABLE--`, `UNION SELECT`) → expect literal match, no row exposure, no execution\n3. Re-run normal-input regression tests to confirm queries still return correct results";
     if (["VG401", "VG960"].includes(id))
         return "1. Submit valid data → expect success\n2. Submit empty/malformed data → expect 400 with validation error\n3. Submit oversized data → expect rejection";
     if (["VG403", "VG500"].includes(id))

package/package.json

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