🛡️ VibeDefender

Security Knowledge MCP Server for AI Coding Agents

Guide your AI agents through professional security assessments with methodology, documentation, and step-by-step workflows covering OWASP Top 10 and beyond.

Installation • Features • Quick Start • Configuration • Documentation

🌟 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)

npx github:yunusj/VibeDefender-MCP

This automatically clones, installs dependencies, builds, and runs the MCP server.

Global Installation

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):

{
  "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:

{
  "mcpServers": {
    "vibedefender": {
      "command": "npx",
      "args": ["github:yunusj/VibeDefender-MCP"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vibedefender": {
      "command": "npx",
      "args": ["github:yunusj/VibeDefender-MCP"]
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings → Features → MCP):

{
  "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:

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:

# Clone the Metasploit MCP repository
git clone https://github.com/your-org/MetasploitMCP ~/MetasploitMCP

2. Set environment variable (add to ~/.bashrc or ~/.zshrc):

export METASPLOIT_MCP_PATH="$HOME/MetasploitMCP/start_mcp.sh"

3. Verify installation:

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:

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:

   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:

# 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

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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE for details

⭐ Show Your Support

If VibeDefender helps secure your code, please star this repository!

Made with 🛡️ by security professionals, for developers