Attack Surface Mcp Server
by cyanheadscommunityv0.1.1
1
Passive attack-surface mapping server that discovers subdomains from Certificate Transparency logs, resolves DNS, inspects TLS and HTTP posture, performs RDAP/WHOIS lookups, and optionally enriches IPs with Shodan. It exposes these capabilities as MCP tools and a resource for mapping a domain's external surface.
From the registry: Passive external attack-surface mapping: CT subdomains, DNS, TLS, HTTP posture, RDAP/WHOIS, Shodan.
Install & configure
Prerequisites
- optionalInstall Node.js or BunInstall Bun v1.3.11+ or Node.js v24+ to run the server. Prefer Node.js if using the npx install path.https://bun.sh/
- optionalOptional Shodan API keyRequired only to enable the attacksurface_lookup_host tool. Without it, the rest of the server works and that tool returns source_unavailable.https://account.shodan.io/
- optionalOptional Certspotter API keyRaises Certspotter rate limits for the CT-log subdomain fallback. The server remains functional without it.https://sslmate.com/certspotter/api/
Install in your client
Paste into the AI you're chatting with — it will figure out the rest
Please install the `attack-surface-mcp-server` MCP server into my current AI client (that's you).
Optional prerequisites:
- Install Node.js or Bun — Install Bun v1.3.11+ or Node.js v24+ to run the server. Prefer Node.js if using the npx install path. (https://bun.sh/)
- Optional Shodan API key — Required only to enable the attacksurface_lookup_host tool. Without it, the rest of the server works and that tool returns source_unavailable. (https://account.shodan.io/)
- Optional Certspotter API key — Raises Certspotter rate limits for the CT-log subdomain fallback. The server remains functional without it. (https://sslmate.com/certspotter/api/)
Canonical MCP server config (stdio transport):
- command: `npx`
- args: ["-y","@cyanheads/attack-surface-mcp-server@latest"]
- optional environment variables:
- `MCP_TRANSPORT_TYPE`: Transport mode. Set to stdio for MCP client stdio usage. (example: `stdio`)
- `MCP_LOG_LEVEL`: Log level (RFC 5424). (example: `info`)
- `SHODAN_API_KEY`: Enables attacksurface_lookup_host. Without it, only that tool is unavailable. (example: `<your-shodan-api-key>`)
- `CERTSPOTTER_API_KEY`: Raises Certspotter API rate limits for CT fallback. (example: `<your-certspotter-api-key>`)
- `ATTACKSURFACE_DEFAULT_RESOLVERS`: Comma-separated default DNS resolver IPs for attacksurface_resolve_dns. (example: `<resolver-ip-1>,<resolver-ip-2>,<resolver-ip-3>`)
- `ATTACKSURFACE_HTTP_USER_AGENT`: Default User-Agent for attacksurface_probe_http. (example: `<your-user-agent>`)
- `ATTACKSURFACE_MAX_SUBDOMAINS`: Cap on subdomains resolved during a map_domain run. (example: `<max-subdomains>`)
- `ATTACKSURFACE_RDAP_BOOTSTRAP_URL`: RDAP bootstrap base URL override. (example: `<your-rdap-bootstrap-url>`)
- `ATTACKSURFACE_ALLOW_PRIVATE_TARGETS`: Set true to disable the SSRF guard for internal-network assessment. (example: `<true-or-false>`)
- `MCP_HTTP_PORT`: Port for HTTP transport mode. (example: `<port>`)
- `MCP_AUTH_MODE`: Auth mode: none, jwt, or oauth. (example: `<none-or-jwt-or-oauth>`)
- `OTEL_ENABLED`: Enable OpenTelemetry instrumentation. (example: `<true-or-false>`)
Note: README also documents Streamable HTTP support. For HTTP mode, start the server with MCP_TRANSPORT_TYPE=http; it listens on /mcp, with MCP_HTTP_PORT defaulting to 3010. Canonical stdio config chosen because it is the simplest portable client configuration path.
Add this MCP server to my current client's config in the correct format for you. If you need secrets or credentials I haven't provided, ASK me — do not invent values or leave raw placeholders. After adding it, tell me how to verify the server is connected.Note: README also documents Streamable HTTP support. For HTTP mode, start the server with MCP_TRANSPORT_TYPE=http; it listens on /mcp, with MCP_HTTP_PORT defaulting to 3010. Canonical stdio config chosen because it is the simplest portable client configuration path.
Tools (8)
attacksurface_map_domain
Maps a domain end to end: CT-log subdomain discovery, DNS liveness, DNS records, TLS posture, HTTP posture, optional RDAP/WHOIS, and optional Shodan enrichment.
attacksurface_enumerate_subdomains
Discovers subdomains passively from Certificate Transparency logs and marks which names resolve live.
attacksurface_resolve_dns
Resolves A, AAAA, CNAME, MX, NS, TXT, and CAA records across public resolvers, with optional PTR lookups.
attacksurface_inspect_tls
Performs a read-only TLS handshake to report protocol, cipher, certificate chain, SANs, expiry, issuer, and validation status.
attacksurface_probe_http
Makes one passive HTTP(S) GET to report status, redirects, headers, security headers, and evidence-bound technology fingerprints.
attacksurface_lookup_registration
Looks up domain or IP registration/ownership data via RDAP, with WHOIS fallback when needed.
attacksurface_lookup_host
Queries Shodan for single-IP infrastructure intelligence or internet-wide search results.
attacksurface_recon_guidance
Synthesizes gathered findings into a prioritized defensive review plan and suggested follow-up calls without making network requests.
Environment variables
SHODAN_API_KEYrequiredRequired for the Shodan-based host lookup tool.Prerequisites
- • Node.js v24+
Packages
@cyanheads/attack-surface-mcp-server
npmv0.1.1transport: stdio
@cyanheads/attack-surface-mcp-server
npmv0.1.1transport: streamable-http
Details
- Language
- TypeScript
- License
- Apache-2.0
- Released
- Jun 14, 2026
- Last commit
- Jun 14, 2026
- Registry name
- io.github.cyanheads/attack-surface-mcp-server