<div align="center">

# 🛡️ VibeDefender

**Security Knowledge MCP Server for AI Coding Agents**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
[![GitHub Stars](https://img.shields.io/github/stars/yunusj/VibeDefender-MCP?style=social)](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**!

[![GitHub Stars](https://img.shields.io/github/stars/yunusj/VibeDefender-MCP?style=social)](https://github.com/yunusj/VibeDefender-MCP/stargazers)

**Made with 🛡️ by security professionals, for developers**

</div>