VibeDefender MCP Server

<div align="center"> # 🛡️ VibeDefender **Security Knowledge MCP Server for AI Coding Agents** [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) [](https://github.com/yunusj/VibeDefender-MCP/stargazers) *Guide your AI agents through professional security assessments with methodology, documentation, and step-by-step workflows covering OWASP Top 10 and beyond.* [Installation](#-installation) • [Features](#-features) • [Quick Start](#-quick-start) • [Configuration](#-configuration) • [Documentation](#-available-resources) </div> --- ## 🌟 Why VibeDefender? Your AI coding agent (Claude Code, Cursor, etc.) already knows how to run commands. **VibeDefender teaches it WHEN, WHY, and HOW to run security tools like a professional pentester.** Instead of guessing which security tools to run, your AI gets: - 📚 **Step-by-step security methodology** - Professional assessment workflows - 🎯 **Plain English guidance** - No security expertise required - 🔧 **Tool installation guides** - Automated setup assistance - 📖 **Always-current documentation** - Live tool documentation proxy - ✅ **OWASP Top 10 coverage** - Industry-standard vulnerability detection > **⭐ If you find VibeDefender useful, please star this repo! It helps others discover professional security testing for AI agents.** ## 📦 Installation ### Direct from GitHub (Recommended) ```bash npx github:yunusj/VibeDefender-MCP ``` This automatically clones, installs dependencies, builds, and runs the MCP server. ### Global Installation ```bash npm install -g github:yunusj/VibeDefender-MCP vibedefender-mcp ``` ## ✨ Features ### 🎯 What Makes VibeDefender Different ✅ **Knowledge-First Approach** - Guides AI agents instead of executing tools directly ✅ **5 Pre-Built Security Workflows** - Setup, full scan, pre-push check, live testing, URL scanning ✅ **OWASP Top 10 Coverage** - Comprehensive vulnerability detection (injection, XSS, auth, etc.) ✅ **Mandatory Runtime Analysis** - Not just static analysis - tests your running application ✅ **Artifact Generation** - Saves all scan results as JSON + markdown reports ✅ **Zero Security Knowledge Required** - Plain English explanations for non-security developers ✅ **Tool Agnostic** - Works with any MCP-compatible AI editor (Claude Code, Cursor, etc.) ### 🔧 Integrated Security Tools - **Trivy** - CVE and dependency vulnerability scanning - **Semgrep** - Static code analysis with 2000+ security rules - **Nuclei** - Runtime security testing with template-based scanning - **Metasploit** - Optional integration for discovery and exploitation ### 🤖 Supported AI Editors | Editor | Status | Notes | |--------|--------|-------| | Claude Code | ✅ Fully Supported | Native MCP support | | Cursor | ✅ Fully Supported | MCP configuration required | | Claude Desktop | ✅ Fully Supported | Config in `claude_desktop_config.json` | | Google Antigravity | ✅ Fully Supported | Same config as Claude Desktop | ## 🧠 Philosophy **The MCP GUIDES, not executes.** Your AI agent (Claude Code, Cursor, etc.) already has the ability to run CLI commands. This MCP provides: - 📋 Step-by-step methodology for security assessments - 🔧 Installation guides for required tools - 💬 Plain English explanations for non-technical users - 📚 Documentation proxy for always-current tool docs ## ⚡ Quick Start 1. **Install and configure** (one-time setup): ```json { "mcpServers": { "vibedefender": { "command": "npx", "args": ["github:yunusj/VibeDefender-MCP"] } } } ``` 2. **Talk to your AI agent in plain English:** | What You Say | What Happens | |--------------|--------------| | 💬 *"Help me set up security scanning"* | 🔧 AI installs Trivy, Semgrep, Nuclei with guided steps | | 💬 *"Scan my code for security issues"* | 🔍 Full scan: dependencies + code + runtime + artifacts | | 💬 *"Check my code before I push"* | ⚡ Fast critical-only check (< 30 seconds) | | 💬 *"Test my app on localhost"* | 🌐 Starts dev server + runs live security tests | | 💬 *"Check this URL for vulnerabilities"* | 🎯 Tests specific URL with authorization check | 3. **Get professional security reports** with actionable fixes: ``` ✅ All scans saved to: security-scan-20241220-143022/ ├── trivy-results.json (Dependency vulnerabilities) ├── semgrep-results.json (Code security issues) ├── nuclei-results.json (Runtime vulnerabilities) └── REPORT.md (Human-readable summary) ``` ## ⚙️ Configuration ### Claude Code Add to your Claude Code MCP settings: ```json { "mcpServers": { "vibedefender": { "command": "npx", "args": ["github:yunusj/VibeDefender-MCP"] } } } ``` ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "vibedefender": { "command": "npx", "args": ["github:yunusj/VibeDefender-MCP"] } } } ``` ### Cursor Add to Cursor's MCP settings (Settings → Features → MCP): ```json { "mcpServers": { "vibedefender": { "command": "npx", "args": ["github:yunusj/VibeDefender-MCP"] } } } ``` ### Google Antigravity Same configuration as Claude Desktop. ## 🧪 Testing with MCP Inspector Test the server before configuring in your editor: ```bash npm install -g @modelcontextprotocol/inspector npx @modelcontextprotocol/inspector npx github:yunusj/VibeDefender-MCP ``` Expected: Web UI shows "Connected", lists all `security://` resources and 5 workflow prompts. ## 🎯 Available Workflows | Workflow | Trigger Phrase | What It Does | |----------|----------------|--------------| | 🔧 `setup` | "Help me set up security scanning" | Checks installed tools, guides installation | | 🔍 `scan` | "Scan my code for security issues" | **Full scan**: static + runtime + artifacts | | ⚡ `pre-push` | "Check my code before I push" | **Fast check**: critical issues only (< 30s) | | 🌐 `scan-live` | "Test my app on localhost" | Starts dev server + runs live tests | | 🎯 `scan-url` | "Check this URL for vulnerabilities" | Tests specific URL (requires authorization) | ## 🛠️ Required Tools The MCP guides you through installing these (just say *"help me set up"*): | Tool | Purpose | Install (macOS) | |------|---------|-----------------| | 🔍 Trivy | CVE/dependency scanning | `brew install aquasecurity/trivy/trivy` | | 📝 Semgrep | Static code analysis | `brew install semgrep` | | 🌐 Nuclei | Runtime testing (**mandatory**) | `brew install nuclei` | ## 🎖️ Metasploit Integration Metasploit Framework is integrated for both **discovery** (reconnaissance) and **exploitation** phases. ### Setup 1. **Install external Metasploit MCP server:** ```bash # Clone the Metasploit MCP repository git clone https://github.com/your-org/MetasploitMCP ~/MetasploitMCP ``` 2. **Set environment variable** (add to `~/.bashrc` or `~/.zshrc`): ```bash export METASPLOIT_MCP_PATH="$HOME/MetasploitMCP/start_mcp.sh" ``` 3. **Verify installation:** ```bash npm run mcp:metasploit # Should output: "Metasploit MCP Proxy running on stdio" ``` ### Usage **Discovery Phase (Automatic):** - Runs safe auxiliary modules for service detection - Port scanning and version detection - Correlates findings with CVE database - No exploitation attempts **Exploitation Phase (Requires Approval):** - Executes exploits against validated vulnerabilities - Requires explicit human approval - Full session management and post-exploitation - Evidence gathering only (read-only) ### Safety ⚠️ **CRITICAL: Authorization Required** - Only use on systems you **own** OR have **written permission** to test - Unauthorized access to computer systems is **illegal** - Discovery phase: Basic authorization sufficient - Exploitation phase: Explicit approval required ### 📖 Documentation - See `security://methodology/exploitation` for complete exploitation workflow - See `security://docs/metasploit` for detailed tool usage - Includes safety guidelines, workflow examples, and troubleshooting ## 📚 Available Resources ### 📋 Methodology Guides | Resource | Description | |----------|-------------| | `security://methodology/discovery` | 🔍 How to find attack surface | | `security://methodology/scanning` | 📊 What to scan, in what order | | `security://methodology/validation` | ✅ How to validate on live targets | | `security://methodology/reporting` | 📝 How to structure reports | ### 📖 Reference Documentation | Resource | Description | |----------|-------------| | `security://reference/severity` | 🚨 What CRITICAL/HIGH/MEDIUM/LOW mean | | `security://reference/cwe-top-25` | 🐛 Common weakness types | | `security://reference/owasp-top-10` | 🛡️ OWASP vulnerability categories | | `security://reference/browser-options` | 🌐 Browser automation choices | ### 🔧 Tool Documentation | Resource | Description | |----------|-------------| | `security://docs/overview` | 📚 Overview of all tools | | `security://docs/trivy` | 🔍 Trivy quick start | | `security://docs/semgrep` | 📝 Semgrep quick start | | `security://docs/nuclei` | 🌐 Nuclei quick start | | `security://docs/playwright` | 🎭 Playwright MCP info | | `security://docs/metasploit` | 🎖️ Metasploit basics | ## 💡 Example Workflows ### First Time Setup ``` You: Help me set up security scanning AI: I'll check what tools you have installed... [Runs version checks] You're missing Trivy and Semgrep. Let me help you install them. Trivy checks your dependencies for known vulnerabilities. Run this to install: brew install aquasecurity/trivy/trivy ... ``` ### Before Pushing Code ``` You: Check my code before I push AI: Running quick pre-push security check... [Runs trivy + semgrep for CRITICAL issues only] ✅ All clear! No critical security issues found. Safe to push. For a comprehensive scan including runtime testing, use the 'scan' workflow. ``` ### Full Security Scan ``` You: Scan my code for security issues AI: I see this is a Node.js project using Express. First, checking for known vulnerabilities in dependencies... [Runs trivy] Found 3 critical issues in your packages: 1. lodash < 4.17.21 - allows prototype pollution Fix: npm update lodash ... ``` ## 📁 Project Structure ``` src/ ├── index.ts # Main MCP server entry point ├── resources/ │ ├── static.ts # Bundled methodology & references │ └── dynamic.ts # Tool documentation with search guidance └── prompts/ └── workflows.ts # 5 user-friendly workflow prompts ``` ## 🎨 Design Decisions 1. **🚫 No execution tools** - AI agents already have CLI access. We provide knowledge. 2. **💬 Plain English** - Everything explained for non-technical users. 3. **📋 Step-by-step** - Prompts tell the AI exactly what to do at each step. 4. **📖 Documentation proxy** - Search patterns for always-current tool docs. 5. **📦 Minimal files** - 4 files total, easy to understand and maintain. 6. **🌐 GitHub-based distribution** - No npm publish, direct from source via npx. ## 🌐 Browser Automation Options For live testing that needs a browser: | Option | When to Use | |--------|-------------| | Playwright MCP | Claude Code, Cursor, most IDEs | | Browser Agent | Google Antigravity IDE (built-in) | | Puppeteer | If already in project | ## 🔧 Troubleshooting ### Build Errors If you see TypeScript compilation errors when installing from GitHub: ```bash npm cache clean --force npx github:yunusj/VibeDefender-MCP ``` ### MCP Server Not Connecting 1. Test with MCP Inspector first (see "Testing" section above) 2. Check Node.js version: `node --version` (requires >= 22.0.0) 3. Verify the server runs standalone: ```bash npx github:yunusj/VibeDefender-MCP # Should output: "Security Knowledge MCP server running on stdio" ``` 4. Check editor configuration file syntax (valid JSON) 5. Restart your AI editor after configuration changes ### Permission Errors If you get EACCES errors: ```bash # On Unix-like systems, the shebang should make it executable # If not, manually set permissions on global install: chmod +x $(which vibedefender-mcp) ``` ### Update to Latest Version ```bash npm cache clean --force npx github:yunusj/VibeDefender-MCP # Or for global install npm uninstall -g vibedefender-mcp npm install -g github:yunusj/VibeDefender-MCP ``` ## ⚠️ Security Notice - ✅ Only scan systems you are **authorized** to test - 🔒 Live validation (scan-url, scan-live) requires **explicit authorization** - 🤝 The AI will ask for confirmation before testing URLs - 📄 Always get **written permission** before security testing - 🛡️ Follow **responsible disclosure** practices --- <div align="center"> ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## 📄 License MIT License - see [LICENSE](LICENSE) for details ## ⭐ Show Your Support If VibeDefender helps secure your code, please **star this repository**! [](https://github.com/yunusj/VibeDefender-MCP/stargazers) **Made with 🛡️ by security professionals, for developers** </div>