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)

Tool	Description	Permission
`vanguard_subdomain_enum`	Enumerate subdomains via crt.sh and DNS bruteforce	DANGEROUS
`vanguard_port_scan`	Port scanning with nmap or TCP connect fallback	DANGEROUS
`vanguard_whois`	WHOIS lookup for domains and IPs	SAFE
`vanguard_dns_records`	Query DNS records (A, AAAA, MX, NS, TXT, etc.)	SAFE

Web Security (10 tools)

Tool	Description	Permission
`vanguard_ffuf`	Web fuzzing with ffuf (FUZZ keyword)	DANGEROUS
`vanguard_nuclei_scan`	Vulnerability scanning with nuclei templates	DANGEROUS
`vanguard_param_miner`	Discover hidden HTTP parameters	DANGEROUS
`vanguard_headers_check`	Analyze security headers (HSTS, CSP, X-Frame-Options)	SAFE
`vanguard_tech_detect`	Technology fingerprinting (CMS, frameworks, CDN)	SAFE
`vanguard_wayback`	Wayback Machine URL history	SAFE
`vanguard_ssl_check`	SSL/TLS certificate and configuration analysis	SAFE
`vanguard_cors_check`	CORS misconfiguration detection	SAFE
`vanguard_robots_sitemap`	Parse robots.txt and sitemap.xml	SAFE
`vanguard_js_endpoints`	Extract endpoints and secrets from JavaScript	SAFE

Network & Infrastructure (15 tools)

Tool	Description	Permission
`vanguard_traceroute`	Trace network path to target	DANGEROUS
`vanguard_ping_sweep`	Discover live hosts in a network range	DANGEROUS
`vanguard_service_detect`	Detect services/versions with nmap -sV	DANGEROUS
`vanguard_os_detect`	OS fingerprinting with nmap	DANGEROUS
`vanguard_banner_grab`	Grab service banners via TCP	DANGEROUS
`vanguard_snmp_enum`	Enumerate SNMP data (WSL)	DANGEROUS
`vanguard_smb_enum`	Enumerate SMB shares and users (WSL)	DANGEROUS
`vanguard_ldap_enum`	Enumerate LDAP directory (WSL)	DANGEROUS
`vanguard_dns_zone_transfer`	Attempt DNS zone transfer (AXFR)	DANGEROUS
`vanguard_arp_scan`	ARP discovery on local network (WSL)	DANGEROUS
`vanguard_ftp_check`	Check FTP for anonymous access	SAFE
`vanguard_ssh_audit`	Audit SSH algorithms and configuration	SAFE
`vanguard_reverse_dns`	Reverse DNS (PTR) lookup	SAFE
`vanguard_network_cidr`	CIDR calculator and subnet operations	SAFE
`vanguard_http_methods`	Test allowed HTTP methods on a URL	SAFE

OSINT (15 tools)

Tool	Description	Permission
`vanguard_github_dorks`	Generate GitHub dork queries for sensitive data	DANGEROUS
`vanguard_cert_search`	Certificate transparency log search	SAFE
`vanguard_cve_lookup`	CVE database search (NVD)	SAFE
`vanguard_email_hunter`	Find email addresses for a domain	SAFE
`vanguard_social_media`	Check username across social platforms	SAFE
`vanguard_domain_reputation`	Domain/IP reputation check	SAFE
`vanguard_ip_geolocation`	IP geolocation (country, city, ISP, ASN)	SAFE
`vanguard_asn_lookup`	ASN lookup by number, IP, or organization	SAFE
`vanguard_google_dorks`	Generate Google dork queries for a target	SAFE
`vanguard_shodan_search`	Search Shodan for exposed services (API key required)	SAFE
`vanguard_breach_check`	Check email/domain in known data breaches	SAFE
`vanguard_metadata_extract`	Extract metadata from web pages	SAFE
`vanguard_dns_history`	Historical DNS record lookup	SAFE
`vanguard_favicon_hash`	Favicon hash for Shodan fingerprinting	SAFE
`vanguard_web_archive_diff`	Wayback Machine snapshot analysis	SAFE

Exploitation (10 tools)

Tool	Description	Permission
`vanguard_exploit_search`	Search exploits by product/CVE (searchsploit + APIs)	DANGEROUS
`vanguard_reverse_shell_gen`	Generate reverse shell payloads (bash, python, php, etc.)	DANGEROUS
`vanguard_sqli_test`	SQL injection testing (error, boolean, time, union)	DANGEROUS
`vanguard_xss_test`	Reflected XSS testing with multiple payloads	DANGEROUS
`vanguard_ssrf_test`	SSRF testing (localhost, cloud metadata, file://)	DANGEROUS
`vanguard_lfi_test`	Local File Inclusion (path traversal, PHP wrappers)	DANGEROUS
`vanguard_command_inject_test`	OS command injection testing	DANGEROUS
`vanguard_open_redirect_test`	Open redirect with bypass techniques	DANGEROUS
`vanguard_crlf_inject_test`	CRLF / HTTP header injection testing	DANGEROUS
`vanguard_deserialization_check`	Insecure deserialization detection (Java, PHP, .NET, Python)	DANGEROUS

Password & Crypto (8 tools)

Tool	Description	Permission
`vanguard_hash_crack`	Crack hashes with John the Ripper (WSL)	DANGEROUS
`vanguard_jwt_attack`	JWT vulnerabilities: none alg, weak secrets, alg confusion	DANGEROUS
`vanguard_password_gen`	Secure random passwords or CeWL-based wordlists	DANGEROUS
`vanguard_hash_identify`	Identify hash type (MD5, SHA, bcrypt, NTLM, etc.)	SAFE
`vanguard_password_policy`	Password strength analysis with entropy and crack time	SAFE
`vanguard_jwt_decode`	Decode JWT tokens with security checks	SAFE
`vanguard_crypto_audit`	HTTPS/TLS security headers and cookie audit	SAFE
`vanguard_base_decode`	Multi-format encode/decode (Base64, hex, URL, HTML, Unicode)	SAFE

Cloud Security (8 tools)

Tool	Description	Permission
`vanguard_cloud_metadata`	SSRF test for cloud metadata endpoints (AWS, GCP, Azure)	DANGEROUS
`vanguard_subdomain_takeover`	Dangling CNAME subdomain takeover detection	DANGEROUS
`vanguard_exposed_env_check`	Check for exposed .env, .git, config files	DANGEROUS
`vanguard_s3_bucket_check`	AWS S3 bucket public access check	SAFE
`vanguard_azure_blob_check`	Azure Blob Storage access check	SAFE
`vanguard_gcp_bucket_check`	Google Cloud Storage access check	SAFE
`vanguard_firebase_check`	Firebase project exposure check	SAFE
`vanguard_cloud_enum`	Enumerate cloud resources by keyword permutations	SAFE

Container Security (5 tools)

Tool	Description	Permission
`vanguard_docker_socket`	Check for exposed Docker daemon (TCP 2375/2376)	DANGEROUS
`vanguard_k8s_api`	Kubernetes API/Kubelet unauthenticated access check	DANGEROUS
`vanguard_container_escape`	Container escape vector detection (socket, caps, mounts)	DANGEROUS
`vanguard_registry_enum`	Docker Registry v2 repository/tag enumeration	DANGEROUS
`vanguard_helm_audit`	Helm chart security audit (privileged, capabilities, secrets)	SAFE

Analysis & Reporting (9 tools)

Tool	Description	Permission
`vanguard_vuln_correlate`	Cross-tool finding correlation and attack chain detection	SAFE
`vanguard_attack_surface`	Attack surface mapping from ports, techs, and subdomains	SAFE
`vanguard_risk_score`	Risk scoring with context multipliers	SAFE
`vanguard_remediation_plan`	Prioritized remediation plan generation	SAFE
`vanguard_encoding_detect`	Multi-layer encoding detection and decoding	SAFE
`vanguard_diff_report`	Before/after scan comparison (new, fixed, upgraded)	SAFE
`vanguard_timeline`	Pentest event timeline with phase analysis	SAFE
`vanguard_scope_manager`	Target scope management (set, add, remove, check)	SAFE
`vanguard_report_gen`	Security assessment reports in Markdown or JSON	SAFE

Utilities (5 tools)

Tool	Description	Permission
`vanguard_set_scope`	Define authorized target scope	SAFE
`vanguard_check_scope`	Verify if target is in scope	SAFE
`vanguard_generate_report`	Generate markdown security report	SAFE
`vanguard_export_html`	Convert report to styled HTML	SAFE
`vanguard_audit_stats`	View audit log and security events	SAFE

Summary

Category	Tools	SAFE	DANGEROUS
Reconnaissance	4	2	2
Web Security	10	7	3
Network	15	5	10
OSINT	15	14	1
Exploitation	10	0	10
Crypto	8	5	3
Cloud	8	5	3
Container	5	1	4
Analysis	9	9	0
Utilities	5	5	0
Total	89	53	36

Permission Tiers

Tier	Description	Example
SAFE	Passive operations, no direct target interaction	DNS lookups, hash identification, report generation
DANGEROUS	Active scanning, requires target authorization	Port scans, injection testing, fuzzing
BLOCKED	Unregistered/unknown tools (rejected automatically)	—

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 178 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

Requirement	Version
Node.js	18+
TypeScript	5.0+ (dev)

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.

Author

@skyvanguard

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/workflows		.github/workflows
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

mcp-vanguard

Features

Quick Start

Configuration

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

2. Passive Reconnaissance

3. Security Analysis

4. Active Scanning (requires authorization)

5. Cloud & Container Checks

6. Analysis & Reporting

Development

Security Features

Input Sanitization

Command Execution Safety

Audit Logging

Safe Error Handling

Architecture

Requirements

Legal Disclaimer

License

Author

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages