mcp-vanguard
A security pentesting MCP Server with 89 tools across 10 categories for Claude integration. Features native Windows/WSL bridge for using Kali Linux tools from any terminal — zero new npm dependencies.
Features
- 89 Security Tools across 10 categories: recon, web, OSINT, network, exploit, crypto, cloud, container, analysis, and utilities
- Registry Architecture: Auto-discoverable tools with self-describing schemas, permissions, and execution modes
- WSL Bridge: Transparently execute Kali Linux tools (nmap, john, enum4linux, etc.) from Windows
- Hybrid Execution: Native Node.js, external APIs, WSL subprocesses, or automatic fallback
- Scope Management: Prevent scanning outside authorized targets
- Permission Tiers: SAFE (passive) / DANGEROUS (active, scope required) / BLOCKED (unknown)
- Report Generation: Markdown and JSON reports, diff comparisons, risk scoring
- Attack Chain Detection: Correlate findings across tools to identify multi-step attack paths
- Security Hardening: Input sanitization, command allowlists, audit logging, safe error handling
- Caching & Rate Limiting: Built-in controls for efficient and safe scanning
Quick Start
git clone https://github.com/skyvanguard/mcp-vanguard.git
cd mcp-vanguard
npm install
npm run build
npm test
Configuration
Add to your Claude MCP configuration:
Claude Desktop (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"vanguard": {
"command": "node",
"args": ["/path/to/mcp-vanguard/dist/index.js"]
}
}
}
Claude Code (.mcp.json in project root):
{
"mcpServers": {
"vanguard": {
"command": "node",
"args": ["C:/path/to/mcp-vanguard/dist/index.js"]
}
}
}
Tools (89 total)
Reconnaissance (4 tools)
Web Security (10 tools)
Network & Infrastructure (15 tools)
OSINT (15 tools)
Exploitation (10 tools)
Password & Crypto (8 tools)
Cloud Security (8 tools)
Container Security (5 tools)
Analysis & Reporting (9 tools)
Utilities (5 tools)
Summary
Permission Tiers
Usage Examples
1. Set Scope
vanguard_set_scope with targets: ["example.com", "*.example.com"]
2. Passive Reconnaissance
vanguard_dns_records for example.com
vanguard_cert_search for example.com
vanguard_wayback for example.com
vanguard_ssl_check for example.com
vanguard_tech_detect for https://example.com
vanguard_asn_lookup for example.com
vanguard_favicon_hash for https://example.com
3. Security Analysis
vanguard_headers_check for https://example.com
vanguard_cors_check for https://api.example.com
vanguard_js_endpoints for https://example.com with deep: true
vanguard_cve_lookup for "nginx 1.20"
vanguard_crypto_audit for https://example.com
4. Active Scanning (requires authorization)
vanguard_subdomain_enum for example.com
vanguard_port_scan for example.com ports 1-1000
vanguard_service_detect for example.com ports [80, 443, 8080]
vanguard_nuclei_scan for https://example.com with severity ["high","critical"]
vanguard_sqli_test for https://example.com/search?q=test
vanguard_xss_test for https://example.com/search?q=test
5. Cloud & Container Checks
vanguard_s3_bucket_check for "company-backup"
vanguard_firebase_check for "my-project"
vanguard_subdomain_takeover for ["app.example.com", "api.example.com"]
vanguard_docker_socket for 10.0.0.5
vanguard_k8s_api for https://10.0.0.5:6443
6. Analysis & Reporting
vanguard_vuln_correlate with findings from multiple scans
vanguard_risk_score with context (public, auth, sensitive data)
vanguard_remediation_plan from findings
vanguard_diff_report comparing before/after scans
vanguard_report_gen with title "Security Assessment" and findings
Development
npm install # Install dependencies
npm run build # Build TypeScript
npm run dev # Watch mode
npm test # Run 195 tests
npm run test:coverage # Coverage report
npm run format # Format code
Security Features
Input Sanitization
- Shell metacharacter filtering
- Path traversal prevention
- URL validation (no credentials, no private IPs)
- Domain/IP format validation
Command Execution Safety
- Command Allowlist: Only permitted commands can execute via WSL or Windows
- Argument Escaping: All arguments are properly escaped for shell execution
- Timeout Protection: Configurable timeouts per command
Audit Logging
- All tool calls are logged with timestamps and duration
- Security events (blocked commands, scope violations) are tracked
- Rate limit violations are recorded
- View logs via
vanguard_audit_stats
Safe Error Handling
- Error messages are sanitized to prevent info leakage
- Paths, IPs, and sensitive data are masked in error output
- Stack traces are removed from user-facing errors
Architecture
mcp-vanguard/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server + tool registration
│ ├── registry.ts # ToolRegistry (auto-discover, permissions)
│ ├── config.ts # Configuration + scope management
│ ├── types/
│ │ └── tool.ts # ToolDefinition interface
│ ├── executor/
│ │ ├── windows.ts # Windows executor (with allowlist)
│ │ └── wsl.ts # WSL bridge (with allowlist)
│ ├── tools/
│ │ ├── recon/ # 4 reconnaissance tools
│ │ ├── web/ # 10 web security tools
│ │ ├── network/ # 15 network/infrastructure tools
│ │ ├── osint/ # 15 OSINT tools
│ │ ├── exploit/ # 10 exploitation tools
│ │ ├── crypto/ # 8 password & crypto tools
│ │ ├── cloud/ # 8 cloud security tools
│ │ ├── container/ # 5 container security tools
│ │ ├── analysis/ # 9 analysis & reporting tools
│ │ └── utils/ # 5 utility tools
│ └── utils/
│ ├── cache.ts # Response caching
│ ├── rate-limiter.ts # Rate limiting
│ ├── sanitizer.ts # Input sanitization
│ ├── audit.ts # Audit logging
│ ├── safe-error.ts # Safe error handling
│ └── zod-to-json.ts # Zod schema → JSON Schema
├── tests/ # 178 Vitest tests
├── dist/ # Compiled output
└── package.json
Requirements
Optional (for active scanning via WSL):
- nmap, ffuf, nuclei, dig, john, enum4linux, smbclient, ldapsearch, ssh-audit, arp-scan, snmpwalk, cewl, searchsploit
Legal Disclaimer
WARNING: Unauthorized access to computer systems is illegal. This tool is for authorized security testing only. Always obtain proper written authorization before scanning any target. The authors accept no liability for misuse.
License
MIT License — see LICENSE for details.