attack-surface-mcp-server

---

重要

仅限经授权的防御性用途。 本服务仅可用于扫描你拥有或明确获准评估的资产。它执行的是被动、非侵入式侦察——读取公开记录（证书透明度日志、DNS、RDAP/WHOIS），并检查每个目标自身发布的表面（每台主机执行一次 TLS 握手和一次 HTTP GET）。它不会进行端口扫描、漏洞利用、暴力破解、模糊测试或漏洞探测；此类能力是从设计上排除的，而非通过标志控制。输出仅描述现状——已存在的内容及安全态势，绝不提供漏洞利用方案。每个出站连接都会经过 SSRF 防护，拒绝访问私有、环回、链路本地及云元数据目标。

---

概述

通过证书透明度日志、DNS、TLS、HTTP 和 RDAP/WHOIS 注册信息进行被动式外部攻击面映射（EASM），并可选用 Shodan 主机情报。发现子域名、解析 DNS 记录，并检查域名下在线主机的 TLS 和 HTTP 安全态势。

工具

工具	说明
attacksurface_map_domain	旗舰工作流。端到端映射域名的外部攻击面：通过 CT 日志发现子域名 → 检查 DNS 是否存活 →（standard+）DNS 记录、TLS 安全态势、HTTP 标头/技术 → 可选的 RDAP/WHOIS →（thorough + key）按 IP 进行 Shodan 信息补充。返回结构化的攻击面映射，以及基于可观测事实的防御性评估。
attacksurface_enumerate_subdomains	从证书透明度日志被动发现子域名（crt.sh → Certspotter → TLS-SAN 回退链），并通过 DNS 解析标记哪些名称处于存活状态。提供各来源的溯源信息；不进行 DNS 暴力枚举。
attacksurface_resolve_dns	通过多个公共解析器解析并枚举一个或多个主机的 DNS 记录（A/AAAA/CNAME/MX/NS/TXT/CAA），并可选进行反向 DNS（PTR）查询。各解析器的值可显示传播差异。
attacksurface_inspect_tls	通过真实的只读握手检查 TLS/SSL 安全态势：协议、密码套件、叶证书和证书链深度、SAN、有效期、距到期天数、颁发者、验证状态。遇到无效、过期或自签名证书时会报告，而不会失败。
attacksurface_probe_http	被动 HTTP(S) 探测：发送一次遵循重定向的 GET 请求。返回状态、重定向链、标头、安全标头审计（HSTS/CSP/X-Frame-Options/ Cookie 标志/CORS 反射），以及基于证据的技术指纹。
attacksurface_lookup_registration	通过 RDAP（JSON；回退至 WHOIS）查询注册和所有权信息。对于域名，返回注册商、状态、生命周期事件、名称服务器、DNSSEC；对于 IP/CIDR，返回网段、分配 CIDR、源 ASN、国家/地区。
attacksurface_lookup_host	通过 Shodan 查询单个 IP 的基础设施情报（开放端口、横幅、软件版本、ASN、地理位置），或进行带条件筛选的全网搜索。需要 SHODAN_API_KEY——未设置时会返回类型化的 source_unavailable 错误；不影响服务器的其他功能。
attacksurface_recon_guidance	离线防御性审查，支持选择主题、分页显示有限数量的优先事项/建议、本地后续调用，以及产品/版本公告检查指引。不进行外部调用。

资源

资源	说明
attacksurface://surface/{domain}	域名外部攻击面的一次性快照（子域名、存活主机、各主机的 DNS/TLS/HTTP 安全态势摘要），并分别提供候选项覆盖范围和最多 50 个主机的详细信息覆盖范围。

所有资源数据也可通过工具获取——仅支持工具的客户端不会缺少任何内容，因为 attacksurface_map_domain 涵盖了相同的信息。

功能参考

attacksurface_map_domain _工具

• depth：quick 用于发现子域名并检查其存活状态；standard 会增加 DNS 记录、TLS 和 HTTP 安全态势；如果存在密钥，thorough 会增加按 IP 获取的 Shodan 数据，否则会返回说明。
• 返回结构化的攻击面映射，以及基于可观测事实的防御性 assessment。来源故障和无法访问的主机会作为说明列出；子域名解析数量上限由 ATTACKSURFACE_MAX_SUBDOMAINS 控制（默认值为 200），超出部分会明确说明。
• includeRegistration 会在 standard 或 thorough 深度下为顶级域名添加 RDAP/WHOIS 数据。standard 和 thorough 还会返回来自首个已配置解析器的 DNS 记录，以及存活主机的传播不匹配情况；quick 深度下的 null 安全态势表示已跳过相关工作。
• coverage 列出尚未检查或缺少主机详细信息的内容（unexamined、detailOmitted）；retrieval 最多提供三个可直接运行的后续调用（最多 50 个主机的 DNS/TLS 批次、一个 HTTP URL）。nextToolSuggestions 会预填针对最多 50 个主机的 attacksurface_recon_guidance 调用；如有省略项，guidanceCoverage 会列出。

attacksurface_enumerate_subdomains _工具

• 依次通过 crt.sh、Certspotter 和顶级域 TLS 证书中的 SAN 发现名称，然后检查 DNS 是否可解析。includeUnresolved: false 仅保留存活主机；filteredAddressErrors 会保留被排除名称的 DNS 错误。
• 返回每个名称的来源和各来源状态。complete、pagesFetched 和 incompleteReason 用于说明覆盖是否完整；addressError 则将 DNS 错误与 ENODATA/ENOTFOUND 表示的不存在情况区分开来。
• offset 和 limit（默认值为 50，较大的请求会被限制）用于对候选项分页，范围受 min(50, ATTACKSURFACE_MAX_SUBDOMAINS) 限制。使用 nextOffset 或预填充的 continuation 获取下一页，并通过 remainingCount 查看剩余数量。每页都会重新读取 CT 日志，因此变更可能导致偏移量发生变化。

---

attacksurface_resolve_dns _工具

• 接受 1–1000 个主机，并按输入顺序处理前 50 个；processedCount 和 remainingHosts 会显示需要重新提交的内容。通过公共解析器查询 A、AAAA、CNAME、MX、NS、TXT 和 CAA 记录（默认解析器为 8.8.8.8、1.1.1.1、9.9.9.9）；反向 DNS（PTR）查询为可选项。
• 返回各解析器的回答，以便查看传播差异；规范记录来自第一个已配置的解析器。解析器错误（包括 SERVFAIL）会与任何成功记录一起显示在 queryError 和 hostError 中。
• 私有或环回解析器 IP 会产生 blocked_resolver；单个主机查询失败时会返回该主机的错误。

---

attacksurface_inspect_tls _工具

• 接受 1–1000 个主机，并按输入顺序处理前 50 个；processedCount 和 remainingHosts 会显示需要重新提交的内容。端口默认为 443，握手超时默认为 8000ms（1000–30000ms）。
• 返回协商的协议、密码套件、叶证书和证书链深度、SAN、颁发者、有效期、距过期天数和验证状态。会报告无效、过期和自签名证书；单个主机检查失败时会返回该主机的错误。
• 证书链信任（validationAuthorized/validationError）和主机名匹配（identityAuthorized/identityError）是分开的检查。只有无法解析过期日期时，daysUntilExpiry 才为 null。

---

attacksurface_probe_http _工具

• 接受一个 HTTP(S) URL；超时默认为 10000ms（1000–30000ms），涵盖整个探测过程。最多跟随十次重定向，并在每一跳进行 SSRF 检查；目标被拒绝时会返回 blocked_target，超过重定向上限时会返回 finalStatus: 0 和 transportError。
• 返回状态码、重定向链、原始标头、安全标头检查结果（HSTS、CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、Cookie 标志、CORS 反射）以及包含触发证据的技术检测结果。CSP 分析仅涵盖 frame-ancestors。
• bodyInspection 会报告 complete、limited（前缀上限为 64,000 字节）、failed 或 not_read；即使正文读取失败，状态码和标头仍会保留。

---

attacksurface_lookup_registration _工具

• 接受域名、IP 或 CIDR（IPv4 前缀 0–32，IPv6 前缀 0–128）；type（auto / domain / ip）用于控制如何解释输入。优先使用 RDAP，必要时再使用 WHOIS。
• 域名结果包含注册商、EPP 状态、生命周期事件、名称服务器和 DNSSEC；IP/CIDR 结果包含网段、分配 CIDR、ASN 和国家。稀少或已脱敏的字段会保持未知，原始 WHOIS 响应保存在 rawWhois 中。
• 明确的 WHOIS 无匹配结果会返回 no_match；转介失败，或 WHOIS 响应为空或无法识别时，会返回 source_unavailable。

---

attacksurface_lookup_host _工具

• mode: "host"（默认）会查询单个纯 IPv4/IPv6 地址，其他输入均返回 invalid_target；mode: "search" 接受全网搜索查询，可选提供 facets，并可能消耗 Shodan 查询额度。需要 SHODAN_API_KEY。
• 每次搜索调用返回一页 100 条匹配结果（page 默认为 1，在 host 模式下会被忽略），并包含 hasMore、nextPage 和预填的 continuation。后续页面需选择获取，且可能消耗额度。
• 返回 Shodan 最近一次扫描中的端口、横幅、软件版本、主机名、ASN 和地理信息。缺少凭据时返回 source_unavailable；没有主机数据时返回 no_data。该服务不会执行端口扫描。

---

attacksurface_recon_guidance _工具

• 接收先前的发现结果（主机、证书、缺失的标头、软件版本、端口）。主题 triage 会按紧急程度排序并涵盖所有发现结果，posture 涵盖 TLS/标头强化，coverage 涵盖检查和版本缺口。开放端口只是资产清单证据，绝不能作为漏洞的证明。
• 返回 priorities 和格式为 {toolName, reason, args} 的建议，这些建议仅针对本地工具；不会发起外部调用或主动扫描。
• priorityOffset 和 suggestionOffset 分别通过 limit 分页（默认为 50，最大为 50）。请使用下一个偏移量重新提交原始发现结果和主题。

---

attacksurface://surface/{domain} _资源

• 接收一个域名，并返回 application/json 快照，其内容等同于标准深度的 attacksurface_map_domain 调用。
• 包含子域名和在线主机数量，以及每台主机的 DNS/TLS/HTTP 状况和错误。解析使用与映射相同的上限，状况详情最多覆盖 50 台在线主机；coverage 会列出省略的内容及后续调用。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），提供结构化日志，并可选择启用 OpenTelemetry 跟踪。

攻击面专属功能：

• 按要求被动且非侵入式——仅使用公开记录和每个目标自身发布的一次响应；攻击面范围不包括主动扫描、利用和暴力破解，且无法通过标志切换启用
• 核心功能无需密钥——CT 子域枚举、DNS、TLS、HTTP/技术检测和 RDAP/WHOIS 均可在不使用任何 API 密钥的情况下运行；Shodan 仅用于补充深度信息
• 对每个出站连接实施 SSRF 防护——连接前拒绝私有、环回、链路本地、云元数据及保留的 IPv4/IPv6 地址范围（可通过 ATTACKSURFACE_ALLOW_PRIVATE_TARGETS 选择退出，以便对可信内部目标进行评估）
• 多来源聚合并提供回退链——CT 发现按 crt.sh → Certspotter → TLS-SAN 的顺序回退；注册信息按 RDAP → WHOIS 的顺序回退

适合 Agent 的输出：

• 每项结果均标注来源——提供来源标签（source: crt.sh | certspotter | tls-san、source: rdap | whois）及每个来源的状态，方便 Agent 评估完整性和可信度
• 优雅处理部分失败——多目标和多来源工具会返回每项/每个来源的 error 字段和运行说明 notes，而不会导致整个调用失败；只有格式错误的输入会抛出异常
• 带类型判别的合约——提供带类型的错误原因（source_unavailable、blocked_target、all_sources_failed）和联合输出（kind: domain | ip），让调用方依据数据而非字符串解析进行分支处理
• 不编造信号——技术检测会附带触发检测的证据；缺失的 CT/DNS/RDAP 字段会报告为未知，绝不推断

入门

将以下内容添加到 MCP 客户端配置文件中。除 attacksurface_lookup_host 外，所有工具均无需配置——在空环境中即可启动不需要密钥的核心功能。

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/attack-surface-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可使用 npx（无需 Bun）：

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/attack-surface-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可使用 Docker：

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/attack-surface-mcp-server:latest"]
    }
  }
}

若要启用 Shodan 主机情报功能（attacksurface_lookup_host），请在 env 块中添加 SHODAN_API_KEY。

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 核心工具无需 API 密钥。可选：为 attacksurface_lookup_host 提供 Shodan API 密钥，并提供 Certspotter API 密钥以提高 CT 后备查询的速率限制。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/attack-surface-mcp-server.git

2. 进入目录：

cd attack-surface-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env only if you want Shodan, a Certspotter key, or non-default behavior

配置

所有变量均为可选项——即使环境为空，服务也会启动并提供无需密钥的核心功能。

变量	描述	默认值
SHODAN_API_KEY	启用 attacksurface_lookup_host。未设置时，该工具会返回 source_unavailable；其他所有工具仍可正常工作。	—
CERTSPOTTER_API_KEY	提高 CT 日志子域名后备查询的 Certspotter 速率限制。未设置时使用免费免认证套餐（受速率限制，但仍可正常使用）。	—
ATTACKSURFACE_DEFAULT_RESOLVERS	供 attacksurface_resolve_dns 以及 standard+ 地图/快照安全态势查询使用的公共 DNS 解析器 IP，以逗号分隔。	8.8.8.8,1.1.1.1,9.9.9.9
ATTACKSURFACE_HTTP_USER_AGENT	attacksurface_probe_http 的默认 User-Agent（可在每次调用时覆盖）。	attack-surface-mcp-server/passive-recon (+https://github.com/cyanheads/attack-surface-mcp-server)
ATTACKSURFACE_MAX_SUBDOMAINS	地图/快照解析上限；枚举时每页候选项也最多为 50 个。	200
ATTACKSURFACE_RDAP_BOOTSTRAP_URL	RDAP 引导基础 URL；可覆盖为私有/镜像 RDAP。	https://rdap.org
ATTACKSURFACE_ALLOW_PRIVATE_TARGETS	设置为 true 以允许对非公共目标范围进行可信的内部评估。任何公开部署都应保持为 false。	false
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。服务声明为 stateless；在此处设置的值会覆盖该声明。stdio 模式下忽略此项。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry 埋点。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

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

Docker

docker build -t attack-surface-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 attack-surface-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/attack-surface-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具/资源并初始化六个服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services	领域服务集成（ct、dns、tls、http、registration、shodan）。
src/utils	SSRF 防护和输入验证。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

有关开发指南和架构规则，请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 由处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总文件注册新工具和资源
• 连接用户提供的目标之前，所有出站连接都必须通过 SSRF 防护检查（assertSafeDomain / assertSafeUrl / assertSafeResolverIp）
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。