attack-surface-mcp-server

Overview

Passive external attack-surface mapping (EASM) over Certificate Transparency logs, DNS, TLS, HTTP, and RDAP/WHOIS registries, with optional Shodan host intelligence. Discover subdomains, resolve DNS records, and inspect TLS and HTTP security posture across a domain's live hosts.

The attack-surface guide covers assessment coverage and evidence-preserving triage. It ships with plugin, npm, MCPB and Docker distributions and is served through the MCP Skills extension for supporting clients.

Tools

Resources

All resource data is also reachable via tools — tool-only clients lose nothing, since attacksurface_map_domain covers the same ground.

Related MCP server: External Reconnaissance MCP Server

Capability reference

attacksurface_map_domain tool

• depth: quick discovers subdomains and liveness; standard adds DNS records, TLS, and HTTP posture; thorough adds per-IP Shodan data when a key is present, otherwise a note.

• Returns a structured surface map and a defensive assessment of observable facts. Failed sources and unreachable hosts become notes, and subdomain resolution is capped by ATTACKSURFACE_MAX_SUBDOMAINS (default 200), with truncation disclosed.

• includeRegistration adds RDAP/WHOIS data for the apex at standard or thorough depth. Standard and thorough also return DNS records from the first configured resolver plus propagation mismatches for live hosts; null posture at quick depth means the work was skipped.

• coverage lists what was left unexamined or without host detail (unexamined, detailOmitted), and retrieval gives up to three ready-to-run follow-up calls (DNS/TLS batches of at most 50 hosts, one HTTP URL). nextToolSuggestions prefills an attacksurface_recon_guidance call for up to 50 hosts, with guidanceCoverage naming any omitted.

attacksurface_enumerate_subdomains tool

• Discovers names through crt.sh → Certspotter → the apex TLS certificate SANs, then resolves DNS liveness. includeUnresolved: false keeps only live hosts; filteredAddressErrors retains DNS failures for excluded names.

• Returns each name's source provenance and per-source status. complete, pagesFetched, and incompleteReason disclose partial coverage, and addressError separates DNS failures from ENODATA/ENOTFOUND absence.

• offset and limit (default 50, larger requests clamped) page through candidates, bounded by min(50, ATTACKSURFACE_MAX_SUBDOMAINS). Use nextOffset or the prefilled continuation for the next page, and remainingCount to see what is left. CT logs are re-read per page, so changes can shift offsets.

attacksurface_resolve_dns tool

• Accepts 1–1000 hosts and processes the first 50 in input order; processedCount and remainingHosts show what to resubmit. Queries A, AAAA, CNAME, MX, NS, TXT, and CAA across public resolvers (default 8.8.8.8, 1.1.1.1, 9.9.9.9); reverse DNS (PTR) is optional.

• Returns per-resolver answers to expose propagation gaps, with canonical records from the first configured resolver. Resolver failures (including SERVFAIL) appear in queryError and hostError next to any successful records.

• Private or loopback resolver IPs produce blocked_resolver; an individual host failure becomes a per-host error.

attacksurface_inspect_tls tool

• Accepts 1–1000 hosts and processes the first 50 in input order; processedCount and remainingHosts show what to resubmit. Port defaults to 443 and handshake timeout to 8000ms (1000–30000ms).

• Returns negotiated protocol, cipher, leaf certificate and chain depth, SANs, issuer, validity window, days to expiry, and validation status. Invalid, expired, and self-signed certificates are reported; one host failure becomes a per-host error.

• Chain trust (validationAuthorized/validationError) and hostname match (identityAuthorized/identityError) are separate checks. daysUntilExpiry is null only when the expiry date cannot be parsed.

attacksurface_probe_http tool

• Accepts one HTTP(S) URL; timeout defaults to 10000ms (1000–30000ms) and covers the whole probe. Follows up to ten redirects with an SSRF check at every hop; a refused target produces blocked_target, and exceeding the redirect limit returns finalStatus: 0 and a transportError.

• Returns status, redirect chain, raw headers, security-header findings (HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, cookie flags, CORS reflection), and technology detections with their triggering evidence. CSP analysis covers frame-ancestors only.

• bodyInspection reports complete, limited (64,000-byte prefix cap), failed, or not_read; a body failure keeps the status and headers.

attacksurface_lookup_registration tool

• Accepts a domain, IP, or CIDR (prefix IPv4 0–32, IPv6 0–128); type (auto / domain / ip) controls interpretation. Uses RDAP first, then WHOIS when needed.

• Domain results include registrar, EPP statuses, lifecycle events, nameservers, and DNSSEC; IP/CIDR results include netblock, allocation CIDRs, ASN, and country. Sparse or redacted fields stay unknown, and the raw WHOIS response is kept in rawWhois.

• An explicit WHOIS no-match returns no_match; a failed referral or an empty or unrecognized WHOIS response returns source_unavailable.

attacksurface_lookup_host tool

• mode: "host" (default) looks up one bare IPv4/IPv6 address and returns invalid_target for anything else; mode: "search" takes an internet-wide query with optional facets and may consume Shodan query credits. Requires SHODAN_API_KEY.

• Search returns one 100-match page per call (page defaults to 1, ignored in host mode), with hasMore, nextPage, and a prefilled continuation. Later pages are opt-in and may consume credits.

• Returns ports, banners, software versions, hostnames, ASN, and geography from Shodan's last scan. Missing credentials produce source_unavailable; no host data produces no_data. The server performs no port scans.

attacksurface_recon_guidance tool

• Takes prior findings (hosts, certificates, missing headers, software versions, ports). Topic triage covers all findings ordered by urgency, posture covers TLS/header hardening, and coverage covers inspection and version gaps. Open ports are inventory evidence, never proof of a vulnerability.

• Returns priorities plus suggestions as {toolName, reason, args} that target local tools only; no external calls or active scans are emitted.

• priorityOffset and suggestionOffset page independently with limit (default 50, max 50). Resubmit the original findings and topic with the next offsets.

attacksurface://surface/{domain} resource

• Takes a domain and returns an application/json posture snapshot; use attacksurface_map_domain for registration and a guidance handoff.

• Includes subdomain and live-host counts plus per-host DNS/TLS/HTTP posture and errors. Resolution uses the same cap as mapping, and posture detail covers at most 50 live hosts; coverage lists what was omitted with follow-up calls.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Attack-surface-specific:

• Passive and non-intrusive by mandate — public records plus each target's own single published response; active scanning, exploitation, and brute-forcing are excluded from the surface, not toggled by a flag

• Keyless core — CT subdomain enumeration, DNS, TLS, HTTP/tech, and RDAP/WHOIS all work with zero API keys; Shodan is strictly additive depth

• SSRF guard on every outbound connection — rejects private, loopback, link-local, cloud-metadata, and reserved IPv4/IPv6 ranges before connecting (opt out for trusted internal assessment via ATTACKSURFACE_ALLOW_PRIVATE_TARGETS)

• Multi-source aggregation with fallback chains — CT discovery falls through crt.sh → Certspotter → TLS-SAN; registration falls through RDAP → WHOIS

Agent-friendly output:

• Provenance on every result — source labels (source: crt.sh | certspotter | tls-san, source: rdap | whois) and per-source status so agents can assess completeness and trust

• Graceful partial failure — multi-target and multi-source tools return per-item/per-source error fields and operational notes instead of failing the whole call; only malformed input throws

• Discriminated, typed contracts — typed error reasons (source_unavailable, blocked_target, all_sources_failed) and union output (kind: domain | ip) let callers branch on data, not string parsing

• No fabricated signal — technology detections carry their triggering evidence; absent CT/DNS/RDAP fields are reported as unknown, never inferred

Getting started

Add it to Claude Code:

claude mcp add attack-surface-mcp-server -- npx -y @cyanheads/attack-surface-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/attack-surface-mcp-server"]
    }
  }
}

Every tool except attacksurface_lookup_host works without an API key. To enable Shodan host intelligence, set SHODAN_API_KEY; an optional CERTSPOTTER_API_KEY raises CT-fallback rate limits. For Docker or a source build, see Running the server.

Configuration

All variables are optional — the server boots and delivers its keyless core with an empty environment.

See .env.example for the full list of optional overrides.

Running the server

Requires Bun v1.4.0 or higher (or Node.js v24+).

Clone and install:

git clone https://github.com/cyanheads/attack-surface-mcp-server.git
cd attack-surface-mcp-server && bun install
cp .env.example .env

All configuration is optional; edit .env for Shodan, a Certspotter key, or non-default behavior.

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/attack-surface-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/attack-surface-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/attack-surface-mcp-server:latest"]. To build locally, docker build -t attack-surface-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts

• Every outbound connection to a user-supplied target must pass the SSRF guard (assertSafeDomain / assertSafeUrl / assertSafeResolverIp) before connecting

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.