guardvibe 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeGuard Security
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# GuardVibe Security
+
+**Security guardian for vibe-coders.** An MCP server that gives your AI coding assistant (Gemini, Claude, Cursor) real-time security knowledge.
+
+Stop shipping vulnerable code. GuardVibe checks your code against OWASP Top 10, scans dependencies for CVEs, and provides framework-specific security guides — all inside your AI workflow.
+
+## Features
+
+- **Code Security Analysis** — Scans code for 45+ vulnerability patterns (SQL injection, XSS, hardcoded secrets, cloud API keys, CORS misconfig, and more)
+- **Directory Scanning** — Scan your entire project directory directly from the filesystem with security scoring (A-F grade)
+- **Secret Detection** — Pattern + entropy-based detection of leaked API keys, tokens, and credentials in code and config files
+- **Dependency CVE Check** — Parse lockfiles (package.json, requirements.txt, go.mod, Gemfile.lock, Cargo.lock) and batch-query Google's OSV database
+- **False Positive Suppression** — `// guardvibe-ignore VG001` comments to suppress known false positives
+- **Security Documentation** — Instant best-practice guides for Express, Next.js, FastAPI, React, and more
+- **8 Languages** — JavaScript, TypeScript, Python, Go, Java, PHP, Ruby, and more
+- **OWASP Top 10:2025** — All rules mapped to the latest OWASP standards
+- **Zero-Config Setup** — `npx guardvibe init claude` sets up everything automatically
+
+## Quick Start
+
+### Auto Setup (Recommended)
+
+```bash
+# Set up for your AI coding assistant
+npx guardvibe init claude    # Claude Code
+npx guardvibe init gemini    # Gemini CLI
+npx guardvibe init cursor    # Cursor / VS Code
+npx guardvibe init all       # All platforms
+```
+
+### Manual Setup
+
+**Claude Code:**
+```bash
+claude mcp add guardvibe -- npx guardvibe
+```
+
+**Gemini CLI** — add to `~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "guardvibe": {
+      "command": "npx",
+      "args": ["-y", "guardvibe"]
+    }
+  }
+}
+```
+
+**Cursor / VS Code** — add to MCP settings:
+```json
+{
+  "mcpServers": {
+    "guardvibe": {
+      "command": "npx",
+      "args": ["-y", "guardvibe"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `check_code`
+Analyze a single code snippet for security vulnerabilities.
+
+```
+Input: { code: string, language: "javascript"|"typescript"|"python"|"go"|"java"|"php"|"ruby"|..., framework?: string }
+Output: Security report with findings, severity, OWASP mapping, and fix suggestions
+```
+
+### `check_project`
+Scan multiple files and generate a project-wide security report with a score (A-F).
+
+```
+Input: { files: [{ path: "src/app.ts", content: "..." }, ...] }
+Output: Project security report with score, summary table, and per-file findings
+```
+
+### `get_security_docs`
+Get security best practices for a topic or framework.
+
+```
+Input: { topic: "express authentication" | "sql injection" | "nextjs csrf" | ... }
+Output: Markdown guide with code examples
+```
+
+### `scan_directory`
+Scan an entire project directory directly from the filesystem. No need to pass file contents.
+
+```
+Input: { path: "./src", recursive?: true, exclude?: ["vendor"] }
+Output: Project security report with A-F score, summary, and per-file findings
+```
+
+### `scan_dependencies`
+Parse a lockfile/manifest and check all dependencies for CVEs in one batch query.
+
+```
+Input: { manifest_path: "package.json" }
+Supported: package.json, package-lock.json, requirements.txt, go.mod, Gemfile.lock, Cargo.lock
+Output: Vulnerability report with normalized severity and fix versions
+```
+
+### `scan_secrets`
+Detect leaked secrets, API keys, and tokens in code and config files.
+
+```
+Input: { path: ".", recursive?: true }
+Output: Secret scan report with provider identification, .gitignore coverage check, entropy-based detection
+```
+
+### `check_dependencies`
+Check individual packages for known CVEs via Google OSV.
+
+```
+Input: { packages: [{ name: "lodash", version: "4.17.20", ecosystem: "npm" }] }
+Output: Vulnerability report with CVE IDs, severity, and fix versions
+```
+
+## Supported Topics
+
+| Topic | Coverage |
+|-------|----------|
+| OWASP Top 10 | Full 2025 reference |
+| Express.js | Helmet, CORS, rate limiting, sessions, input validation |
+| Next.js | Server Components, Server Actions, CSRF, CSP, env vars |
+| FastAPI | Pydantic, CORS, rate limiting, SQLAlchemy, auth |
+| React | XSS prevention, secure API calls, state management |
+| SQL Injection | Parameterized queries, ORMs (Prisma, Drizzle, SQLAlchemy) |
+| XSS | DOM sanitization, CSP, React escaping |
+| Authentication | bcrypt, JWT, OAuth, session security |
+| Environment Variables | .env management, Vercel, secret rotation |
+
+## Security Rules (45+ patterns)
+
+### Core Rules (All supported languages)
+
+| ID | Rule | Severity | Languages |
+|----|------|----------|-----------|
+| VG001 | Hardcoded credentials | Critical | All |
+| VG003 | Cloud provider API keys (AWS, GitHub, OpenAI, Stripe) | Critical | All |
+| VG010 | SQL injection | Critical | All |
+| VG011 | Command injection | Critical | All |
+| VG014 | Dynamic code execution (eval) | Critical | JS/TS/Python/PHP/Ruby |
+| VG060 | Weak password hashing (MD5/SHA-1) | Critical | All |
+| VG040 | CORS wildcard | High | All |
+| VG030 | Missing rate limiting | Medium | All |
+
+### Language-Specific Rules
+
+| ID Range | Language | Rules |
+|----------|----------|-------|
+| VG002, VG012-VG015 | JavaScript/TypeScript | Missing auth, XSS, NoSQL injection, JWT |
+| VG005 | Python | Missing auth (FastAPI/Flask) |
+| VG110-VG115 | Go | SQL injection (fmt.Sprintf), os/exec, template.HTML, handler auth, weak hash, CORS |
+| VG120-VG125 | Java | SQL concat, Runtime.exec, JSP XSS, Spring auth, MessageDigest, @CrossOrigin |
+| VG130-VG134 | PHP | $_GET/$_POST SQL injection, shell_exec, echo XSS, md5/sha1, eval |
+| VG140-VG144 | Ruby | String interpolation SQL, backtick injection, html_safe XSS, route auth, Digest |
+
+## Suppressing False Positives
+
+Add `guardvibe-ignore` comments to suppress specific findings:
+
+```javascript
+// Suppress a specific rule on this line
+const password = process.env.DB_PASSWORD; // guardvibe-ignore VG001
+
+// Suppress a rule on the next line
+// guardvibe-ignore-next-line VG002
+app.get('/api/health', (req, res) => res.json({ ok: true }));
+
+// Suppress all rules on this line
+const x = something; // guardvibe-ignore
+```
+
+Supports `//`, `#`, and `<!-- -->` comment styles.
+
+## How It Works
+
+GuardVibe runs as a local MCP server (stdio transport). When your AI assistant needs security guidance, it calls GuardVibe's tools:
+
+1. **Writing code?** → `check_code` scans for vulnerability patterns
+2. **Reviewing a project?** → `scan_directory` scans your entire codebase
+3. **Adding a package?** → `scan_dependencies` checks your lockfile for CVEs
+4. **Worried about leaks?** → `scan_secrets` detects API keys and tokens
+5. **Need guidance?** → `get_security_docs` returns best practices
+
+No API keys needed. No cloud dependency. Runs entirely on your machine.
+
+## Development
+
+```bash
+git clone https://github.com/goklab/guardvibe.git
+cd guardvibe
+npm install
+npm run dev    # watch mode
+npm run build  # compile
+npm test       # run tests
+npm start      # run server
+```
+
+## License
+
+MIT

package/build/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/build/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+const GUARDVIBE_MCP_CONFIG = {
+    command: "npx",
+    args: ["-y", "guardvibe"],
+};
+const platforms = {
+    claude: {
+        path: join(process.cwd(), ".claude.json"),
+        description: "Claude Code (.claude.json)",
+    },
+    gemini: {
+        path: join(homedir(), ".gemini", "settings.json"),
+        description: "Gemini CLI (~/.gemini/settings.json)",
+    },
+    cursor: {
+        path: join(process.cwd(), ".cursor", "mcp.json"),
+        description: "Cursor (.cursor/mcp.json)",
+    },
+};
+function readJsonFile(filePath) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonFile(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function setupPlatform(name) {
+    const platform = platforms[name];
+    if (!platform)
+        return false;
+    const existing = readJsonFile(platform.path);
+    if (existing) {
+        // Merge - don't overwrite existing MCP servers
+        if (!existing.mcpServers) {
+            existing.mcpServers = {};
+        }
+        if (existing.mcpServers["guardvibe"]) {
+            console.log(`  [OK] GuardVibe already configured in ${platform.description}`);
+            return true;
+        }
+        existing.mcpServers["guardvibe"] = GUARDVIBE_MCP_CONFIG;
+        writeJsonFile(platform.path, existing);
+    }
+    else {
+        // Create new config
+        writeJsonFile(platform.path, {
+            mcpServers: {
+                vibeguard: GUARDVIBE_MCP_CONFIG,
+            },
+        });
+    }
+    console.log(`  [OK] Added MCP server to ${platform.description}`);
+    return true;
+}
+function printUsage() {
+    console.log(`
+  GuardVibe Security - Setup CLI
+
+  Usage:
+    npx guardvibe init <platform>
+
+  Platforms:
+    claude    Configure for Claude Code (.claude.json)
+    gemini    Configure for Gemini CLI (~/.gemini/settings.json)
+    cursor    Configure for Cursor (.cursor/mcp.json)
+    all       Configure all platforms
+
+  Examples:
+    npx guardvibe init claude
+    npx guardvibe init all
+`);
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printUsage();
+        process.exit(0);
+    }
+    if (args[0] !== "init") {
+        console.error(`  Unknown command: ${args[0]}`);
+        printUsage();
+        process.exit(1);
+    }
+    const platform = args[1]?.toLowerCase();
+    if (!platform) {
+        console.error("  Please specify a platform: claude, gemini, cursor, or all");
+        process.exit(1);
+    }
+    console.log(`\n  GuardVibe Security Setup\n`);
+    if (platform === "all") {
+        for (const name of Object.keys(platforms)) {
+            setupPlatform(name);
+        }
+    }
+    else if (platforms[platform]) {
+        setupPlatform(platform);
+    }
+    else {
+        console.error(`  Unknown platform: ${platform}`);
+        console.error(`  Available: claude, gemini, cursor, all`);
+        process.exit(1);
+    }
+    console.log(`\n  [OK] Ready! Start coding securely.\n`);
+}
+main();
+//# sourceMappingURL=cli.js.map

package/build/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/build/data/framework-guides.d.ts

@@ -0,0 +1,8 @@
+export interface SecurityGuide {
+    topic: string;
+    keywords: string[];
+    title: string;
+    content: string;
+}
+export declare const frameworkGuides: SecurityGuide[];
+//# sourceMappingURL=framework-guides.d.ts.map

package/build/data/framework-guides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-guides.d.ts","sourceRoot":"","sources":["../../src/data/framework-guides.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,eAAO,MAAM,eAAe,EAAE,aAAa,EAwf1C,CAAC"}