## 工具 围绕侦察工作流组织的八个工具 —— `attacksurface_map_domain` 负责端到端编排整个流程，针对特定方面的工具为其提供有针对性的后续支持，而 `attacksurface_recon_guidance` 将发现结果综合为防御性审查计划。其中七个无需密钥；一个 (`attacksurface_lookup_host`) 需要 Shodan 密钥，但在没有密钥时会优雅降级。 | 工具 | 描述 | |:---|:---| | `attacksurface_map_domain` | 旗舰工作流。端到端映射域名的外部表面：CT-log 子域名发现 → DNS 存活检测 → (标准+) DNS 记录、TLS 状态、HTTP headers/技术 → 可选的 RDAP/WHOIS → (全面 + 密钥) 每个 IP 的 Shodan 富化。返回结构化的表面映射和可观察事实的防御性评估。 | | `attacksurface_enumerate_subdomains` | 从 Certificate Transparency 日志（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 状态：协议、密码套件、完整证书链、SANs、有效期窗口、距过期天数、颁发者、验证状态。报告无效/过期/自签名证书而不是直接失败。 | | `attacksurface_probe_http` | 被动 HTTP(S) 探测：一个遵循重定向的 GET 请求。返回状态、重定向链、headers、安全 headers 审计（HSTS/CSP/X-Frame-Options/cookie 标志/CORS 反射），以及有证据支持的技术指纹。 | | `attacksurface_lookup_registration` | 通过 RDAP（JSON；以 WHOIS 作为回退）进行注册和所有权查询。域名查询返回注册商、状态、生命周期事件、nameservers、DNSSEC；IP/CIDR 查询返回网络块、分配的 CIDRs、原始 ASN、国家。 | | `attacksurface_lookup_host` | 通过 Shodan 获取单个 IP 的基础设施情报（开放端口、banners、软件版本、ASN、地理位置）或多维度的全网搜索。**需要 `SHODAN_API_KEY`** —— 未设置时返回类型化的 `source_unavailable` 错误；服务器的其他部分不受影响。 | | `attacksurface_recon_guidance` | 对目前收集到的发现进行离线综合。返回优先级的**防御性**审查计划以及预填充的后续调用（哪些证书需要续期，哪些主机需要检查，哪些软件版本需要针对外部 NVD/OSV 服务器检查 CVE）。无外部调用。 | ### attacksurface_map_domain 大多数测试任务的核心 —— 一次调用即可端到端映射域名。 - `depth` 控制：`quick` = 仅子域名 + 存活检测；`standard` = + DNS 记录、TLS 和 HTTP 状态；`thorough` = + Shodan 富化（当存在密钥时，否则跳过并附带说明） - `includeRegistration` 在 standard+ 深度下为 apex 添加 RDAP/WHOIS 查询 - 所有基于主机的扇出都使用 `Promise.allSettled` —— 一个失败的来源或不可达的主机会降级为说明，绝不会导致调用崩溃 - 子域名解析有上限（`ATTACKSURFACE_MAX_SUBDOMAINS`，默认为 200），并在达到上限时进行披露 - `assessment` 块仅综合可观察的事实 —— 过期的证书、缺失的 HSTS/CSP、弱 TLS 版本、失败的链条验证 —— 绝不是利用路径 ### attacksurface_enumerate_subdomains 从公开的 Certificate Transparency 日志进行的被动子域名发现。 - 具有回退链的三个来源：crt.sh（主要）、Certspotter（回退 —— crt.sh 经常过载），以及 apex 自身的 TLS 证书 SAN 列表（始终可用） - 每个发现的名称都带有其来源信息 - DNS 解析标记哪些名称处于存活状态；`includeUnresolved: false` 仅返回存活的主机 - 读取公开日志 —— 它不会暴力破解或探测目标的解析器 ### attacksurface_resolve_dns 具有传播可见性的多解析器 DNS 枚举。 - 跨多个公共解析器（默认为 `8.8.8.8`、`1.1.1.1`、`9.9.9.9`）查询 A、AAAA、CNAME、MX、NS、TXT 和 CAA - 报告每个解析器的答案，以便传播差异和水平分割 DNS 可见 - 对解析出的地址进行可选的反向 DNS (PTR) - 每个主机都通过 SSRF 防护检查；拒绝私有/环回解析器 IP；一个失败的主机会降级为按主机的错误 ### attacksurface_inspect_tls 只读 TLS 状态检查 —— 呈现问题是其目的。 - 每个主机的真实握手报告协商的协议和密码套件、完整证书链、SANs、有效期窗口、距过期天数、颁发者和链条验证状态 - 检查并报告无效、过期和自签名证书，而不是抛出异常 - 状态发现会标记较短的过期窗口、已弃用的协议和自签名链 - 每个主机一次握手；不发送应用程序数据；受 SSRF 防护 ### attacksurface_probe_http 带有安全读数的单个被动 HTTP(S) GET 请求。 - 遵循重定向并报告最终状态以及完整的重定向链 - 安全 headers 审计：HSTS、CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、cookie Secure/HttpOnly/SameSite 标志，以及 CORS 源反射 - 有证据支持的技术指纹（服务器、框架、CDN、WAF、CMS）—— 每次检测都注明触发它的 header 或 body 标记 - 严格每个主机一个请求 —— 无路径遍历、参数注入或多方法探测；每个重定向跳转都会根据 SSRF 防护重新检查 ### attacksurface_lookupregistration 来自公共注册管理机构的注册和所有权信息。 - 首选 RDAP（结构化 JSON，302 跟随，截止时间为 5 秒），对于没有 RDAP 的 TLD 或 RDAP 无响应时，回退到 WHOIS port-43 - 域名查询返回注册商、EPP 状态码、注册/过期/更新事件、nameservers 和 DNSSEC - IP/CIDR 查询返回网络块名称、分配的 CIDRs、原始 ASN 和国家 - 注册管理机构数据经常被编辑或稀疏 —— 缺失的字段被报告为未知，从不进行推断 ### attacksurface_lookup_host Shodan 基础设施情报 —— 唯一的可选密钥路径。 - `mode: "host"`（默认）—— 免费的单 IP 查询：开放端口、服务 banners、软件版本、主机名、ASN、地理位置 - `mode: "search"` —— 消耗付费 Shodan 查询额度的多维度全网查询 - 需要 `SHODAN_API_KEY`；没有它，工具会返回类型化的 `source_unavailable` 错误，其他所有工具继续工作 - Shodan 数据反映的是 Shodan 上次扫描的结果，而不是实时的端口状态 —— 服务器本身从不扫描端口 ### attacksurface_recon_guidance 状态感知综合 —— 没有网络调用，仅根据您发现的内容进行推理。 - 获取目前收集的发现（存活主机、TLS/证书状态、缺失的 headers、软件版本、开放端口），并返回优先级的防御性审查计划（作为 markdown 和结构化的优先级条目） - 预填充具体的后续调用 —— 重新检查缺乏状态数据的主机，并将披露的软件版本链接到外部 NVD（`nist-nvd-mcp-server`）或 OSV（`osv-advisory-mcp-server`）服务器以获取 CVE 上下文 - 输出是补救/可见性计划，绝不是利用手册 ## 资源 | 类型 | 名称 | 描述 | |:---|:---|:---| | 资源 | `attacksurface://surface/{domain}` | 域名映射表面（子域名、存活主机、每个主机的 TLS/HTTP 状态摘要）的一次性读取快照，等同于标准深度的 `attacksurface_map_domain` 调用。 | 所有资源数据也可以通过工具访问 —— 仅使用工具的客户端不会丢失任何内容，因为 `attacksurface_map_domain` 涵盖了相同的领域。大型映射会披露截断计数，而不是返回不受限制的主机详细信息。服务器不暴露任何提示；`attacksurface_recon_guidance` 提供了唯一的“构建后续步骤”模式，作为一种状态感知工具，而不是静态模板。 ## 功能 基于 [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)： - 声明式工具和资源定义 —— 每个基元对应一个文件，框架负责处理注册和验证 - 统一错误处理 —— 处理程序抛出异常，框架捕获、分类和格式化 - 可插拔的认证：`none`、`jwt`、`oauth` - 可替换的存储后端：`in-memory`、`filesystem`、`Supabase`、`Cloudflare KV/R2/D1` - 结构化日志记录，支持可选的 OpenTelemetry 追踪 - STDIO 和 Streamable HTTP 传输 攻击面特定功能： - 被动且非侵入式 —— 公开记录加上每个目标自身发布的单一响应；主动扫描、利用和暴力破解被排除在外，而不是通过标志进行切换 - 无需密钥的核心 —— 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`），请将 `SHODAN_API_KEY` 添加到 `env` 块中。 对于 Streamable HTTP，设置传输方式并启动服务器： ``` MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http # 服务器监听于 http://localhost:3010/mcp ``` 这里的“您的 MCP 客户端配置文件”是泛指的 —— 不同的客户端使用不同的配置路径，并且此服务器并不特定于某个客户端。 ### 前置条件 - [Bun v1.3.11](https://bun.sh/) 或更高版本（或 Node.js v24+）。 - 核心工具不需要 API 密钥。可选：用于 `attacksurface_lookup_host` 的 [Shodan API key](https://account.shodan.io/)，以及用于提高 CT 回退速率限制的 [Certspotter API key](https://sslmate.com/certspotter/api/)。 ### 安装说明 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 # 仅当您需要 Shodan、Certspotter key 或非默认行为时才编辑 .env ``` ## 配置 所有变量都是可选的 —— 服务器在空环境下启动并提供其无需密钥的核心功能。 | 变量 | 描述 | 默认值 | |:---------|:------------|:--------| | `SHODAN_API_KEY` | 启用 `attacksurface_lookup_host`。缺失 → 该工具返回 `source_unavailable`；其他所有工具继续工作。 | — | | `CERTSPOTTER_API_KEY` | 提高 CT-log 子域名回退的 Certspotter 速率限制。缺失 → 免费的未认证层级（受速率限制但可用）。 | — | | `ATTACKSURFACE_DEFAULT_RESOLVERS` | 用于 `attacksurface_resolve_dns` 的逗号分隔的默认 DNS 解析器 IP。 | `8.8.8.8,1.1.1.1,9.9.9.9` | | `ATTACKSURFACE_HTTP_USER_AGENT` | 用于 `attacksurface_probe_http` 的默认 User-Agent（可在每次调用时覆盖）。 | 如实标识服务器 | | `ATTACKSURFACE_MAX_SUBDOMAINS` | 在 `map_domain` 运行期间解析的子域名的上限 —— 限制扇出成本。 | `200` | | `ATTACKSURFACE_RDAP_BOOTSTRAP_URL` | RDAP bootstrap 基础 URL；为私有/镜像 RDAP 覆盖此设置。 | `https://rdap.org` | | `ATTACKSURFACE_ALLOW_PRIVATE_TARGETS` | 设置为 `true` 可在内部网络评估中禁用 SSRF 防护。**在任何公共部署中保持为 `false`** —— 它是防止服务器被指向内部基础设施的安全边界。 | `false` | | `MCP_TRANSPORT_TYPE` | 传输方式：`stdio` 或 `http`。 | `stdio` | | `MCP_HTTP_PORT` | HTTP 服务器的端口。 | `3010` | | `MCP_AUTH_MODE` | 认证模式：`none`、`jwt` 或 `oauth`。 | `none` | | `MCP_LOG_LEVEL` | 日志级别（RFC 5424）。 | `info` | | `OTEL_ENABLED` | 启用 [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 | `false` | 有关可选覆盖的完整列表，请参见 [`.env.example`](./.env.example)。 ## 运行服务器 ### 本地开发 - **构建并运行：** # 一次性构建 bun run rebuild # 运行构建的服务器 bun run start:stdio # 或 bun run start:http - **运行检查和测试：** bun run devcheck # Lint、格式化、类型检查、安全性检查 bun run test # Vitest 测试套件 bun run lint:mcp # 根据规范验证 MCP 定义 ### 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`](./CLAUDE.md)。简短版本如下： - 处理程序抛出异常，框架捕获 —— 工具逻辑中没有 `try/catch` - 使用 `ctx.log` 进行请求范围的日志记录，使用 `ctx.state` 进行租户范围的存储 - 通过 `src/mcp-server/*/definitions/index.ts` 中的 barrels 注册新工具和资源 - 每个连接到用户提供的目标的出站连接在连接前必须通过 SSRF 防护（`assertSafeDomain` / `assertSafeUrl` / `assertSafeResolverIp`） - 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出 schema；绝不捏造缺失的字段 ## 贡献 欢迎提交 Issues 和 pull requests。提交前请运行检查和测试： ``` bun run devcheck bun run test ``` ## 许可证 Apache-2.0 —— 详见 [LICENSE](LICENSE)。

标签：Bun, GitHub, MCP协议, TypeScript, 安全插件, 实时处理, 密码管理, 暗色界面, 用户代理, 自动化攻击, 请求拦截