attack-surface-mcp-server

<div align="center">
  <h1>@cyanheads/attack-surface-mcp-server</h1>
  <p><b>Passive external attack-surface mapping: CT subdomains, DNS, TLS, HTTP posture, RDAP/WHOIS, Shodan via MCP. STDIO or Streamable HTTP.</b>
  <div>8 Tools • 1 Resource</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/attack-surface-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Fattack-surface-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/attack-surface-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/attack-surface-mcp-server/releases/latest/download/attack-surface-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=attack-surface-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYXR0YWNrLXN1cmZhY2UtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22attack-surface-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fattack-surface-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

> [!IMPORTANT]
> **Authorized, defensive use only.** Point this server only at assets you own or are explicitly authorized to assess. It performs **passive, non-intrusive** reconnaissance — it reads public records (Certificate Transparency logs, DNS, RDAP/WHOIS) and each target's *own* published surface (one TLS handshake and one HTTP GET per host). It does **not** port-scan, exploit, brute-force, fuzz, or probe for vulnerabilities; that capability is excluded from the surface by design, not gated behind a flag. Output is descriptive — what exists and what the security posture is — never an exploitation plan. Every outbound connection passes an SSRF guard that refuses private, loopback, link-local, and cloud-metadata targets.

---

## Tools

Eight tools organized around the recon workflow — `attacksurface_map_domain` orchestrates the full flow end to end, the per-aspect tools back it for targeted follow-up, and `attacksurface_recon_guidance` synthesizes findings into a defensive review plan. Seven are keyless; one (`attacksurface_lookup_host`) needs a Shodan key and degrades gracefully without it.

| Tool | Description |
|:---|:---|
| `attacksurface_map_domain` | Flagship workflow. Maps a domain's external surface end to end: CT-log subdomain discovery → DNS liveness → (standard+) DNS records, TLS posture, HTTP headers/tech → optional RDAP/WHOIS → (thorough + key) per-IP Shodan enrichment. Returns a structured surface map and a defensive assessment of observable facts. |
| `attacksurface_enumerate_subdomains` | Passive subdomain discovery from Certificate Transparency logs (crt.sh → Certspotter → TLS-SAN fallback chain), with DNS resolution to mark which names are live. Per-source provenance; no DNS brute-forcing. |
| `attacksurface_resolve_dns` | Resolve and enumerate DNS records (A/AAAA/CNAME/MX/NS/TXT/CAA) for one or more hosts across multiple public resolvers, with optional reverse DNS (PTR). Per-resolver values surface propagation gaps. |
| `attacksurface_inspect_tls` | Inspect TLS/SSL posture via a real read-only handshake: protocol, cipher, full certificate chain, SANs, validity window, days-to-expiry, issuer, validation status. Reports invalid/expired/self-signed certs instead of failing. |
| `attacksurface_probe_http` | Passive HTTP(S) probe: one GET following redirects. Returns status, redirect chain, headers, a security-header audit (HSTS/CSP/X-Frame-Options/cookie flags/CORS reflection), and an evidence-bound technology fingerprint. |
| `attacksurface_lookup_registration` | Registration and ownership lookup via RDAP (JSON; WHOIS fallback). A domain returns registrar, status, lifecycle events, nameservers, DNSSEC; an IP/CIDR returns netblock, allocation CIDRs, origin ASN, country. |
| `attacksurface_lookup_host` | Infrastructure intelligence for a single IP (open ports, banners, software versions, ASN, geo) or a faceted internet-wide search, via Shodan. **Requires `SHODAN_API_KEY`** — returns a typed `source_unavailable` error when unset; the rest of the server is unaffected. |
| `attacksurface_recon_guidance` | Offline synthesis over findings gathered so far. Returns a prioritized **defensive** review plan plus pre-filled follow-up calls (which certs to renew, which hosts to inspect, which software versions to check for CVEs against an external NVD/OSV server). No external calls. |

### `attacksurface_map_domain`

The spine of most engagements — one call maps a domain end to end.

- `depth` control: `quick` = subdomains + liveness only; `standard` = + DNS records, TLS, and HTTP posture; `thorough` = + Shodan enrichment (when a key is present, otherwise skipped with a note)
- `includeRegistration` adds an RDAP/WHOIS lookup for the apex at standard+ depth
- All per-host fan-out uses `Promise.allSettled` — one failed source or unreachable host degrades to a note, never tanks the call
- Subdomain resolution is capped (`ATTACKSURFACE_MAX_SUBDOMAINS`, default 200) with the cap disclosed when hit
- The `assessment` block synthesizes only observable facts — expiring certs, missing HSTS/CSP, weak TLS versions, failed chain validation — never an exploitation path

---

### `attacksurface_enumerate_subdomains`

Passive subdomain discovery from public Certificate Transparency logs.

- Three sources with a fallback chain: crt.sh (primary), Certspotter (fallback — crt.sh is frequently overloaded), and the apex's own TLS certificate SAN list (always available)
- Every discovered name carries its source provenance
- DNS resolution marks which names are live; `includeUnresolved: false` returns only live hosts
- Reads public logs — it does not brute-force or probe the target's resolvers

---

### `attacksurface_resolve_dns`

Multi-resolver DNS enumeration with propagation visibility.

- Queries A, AAAA, CNAME, MX, NS, TXT, and CAA across multiple public resolvers (default `8.8.8.8`, `1.1.1.1`, `9.9.9.9`)
- Reports per-resolver answers so propagation gaps and split-horizon DNS are visible
- Optional reverse DNS (PTR) on resolved addresses
- Each host passes the SSRF guard; private/loopback resolver IPs are rejected; one failing host degrades to a per-host error

---

### `attacksurface_inspect_tls`

Read-only TLS posture inspection — surfacing problems is the point.

- A real handshake per host reports negotiated protocol and cipher, the full certificate chain, SANs, validity window, days-to-expiry, issuer, and chain-validation status
- Invalid, expired, and self-signed certificates are inspected and reported rather than throwing
- Posture findings flag short expiry windows, deprecated protocols, and self-signed chains
- One handshake per host; no application data is sent; SSRF-guarded

---

### `attacksurface_probe_http`

A single passive HTTP(S) GET with a security read-out.

- Follows redirects and reports the final status plus the full redirect chain
- Security-header audit: HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, cookie Secure/HttpOnly/SameSite flags, and CORS origin-reflection
- Evidence-bound technology fingerprint (server, framework, CDN, WAF, CMS) — every detection names the header or body marker that triggered it
- Strictly one request per host — no path traversal, parameter injection, or multi-method probing; every redirect hop is re-checked against the SSRF guard

---

### `attacksurface_lookup_registration`

Registration and ownership from public registries.

- RDAP first (structured JSON, 302-follow with a 5s deadline), WHOIS port-43 fallback for TLDs without RDAP or when RDAP is unresponsive
- Domain lookups return registrar, EPP status codes, registration/expiry/updated events, nameservers, and DNSSEC
- IP/CIDR lookups return the netblock name, allocation CIDRs, origin ASN, and country
- Registry data is frequently redacted or sparse — absent fields are reported as unknown, never inferred

---

### `attacksurface_lookup_host`

Shodan infrastructure intelligence — the one optional-key path.

- `mode: "host"` (default) — a free single-IP lookup: open ports, service banners, software versions, hostnames, ASN, geo
- `mode: "search"` — a faceted internet-wide query that consumes paid Shodan query credits
- Requires `SHODAN_API_KEY`; without it the tool returns a typed `source_unavailable` error and every other tool keeps working
- Shodan data reflects Shodan's last scan, not a live port state — the server itself never scans ports

---

### `attacksurface_recon_guidance`

State-aware synthesis — no network calls, just reasoning over what you've found.

- Takes the findings gathered so far (live hosts, TLS/cert state, missing headers, software versions, open ports) and returns a prioritized defensive review plan as