# dns-eye — DNS 之眼 MCP Server

面向 AI Agent 的 **CDN 溯源 + IP 情报 + C 段资产发现 + Host 碰撞** 侦察工具集。
基于 [Model Context Protocol](https://modelcontextprotocol.io)，以 stdio 方式接入任意 MCP 客户端（Claude Desktop / CodeBuddy / Cursor 等），由大模型直接调用完成域名资产侦察。

> 设计原则：只读优先、无 shell 注入、输入严格校验、结果以 JSON 结构化返回，便于 Agent 解析与编排。

---

## 功能特性

- **多地 DNS 解析**：12 个国内外公共 DNS 节点并行解析，通过 IP 离散度判断目标是否位于 CDN 之后，并标出疑似源站 IP。
- **CNAME 链路追踪**：递归追踪 CNAME 链，结合云厂商 CNAME 关键词库识别 CDN 提供商。
- **crt.sh 证书关联**：查询证书透明度日志，挖掘同证书关联域名与内联 IPv4。
- **IP 云厂商判定**：离线云厂商 IP 段 + CDN 特征库，判定 IP 类型（云 / 托管 / 自建），无需联网查询。
- **C 段高速扫描**：raw socket + asyncio 非阻塞并发（2000 并发），默认扫描 135 个常用 Web 端口；`fast` 模式仅扫 20 个高频端口秒出。
- **Web 指纹探测**：aiohttp 主引擎（~60ms）获取标题 / Server / 技术栈；可选 httpx 备选引擎做 tech-detect。
- **Host 碰撞**：自定义 Host 头请求，对比 baseline 响应差异，发现隐藏在 CDN / 反代后的真实服务。
- **一站式侦察**：`full_recon` 将上述步骤编排为 7 步流水线，一键输出完整侦察结论。

---

## 9 个工具速查

| 工具 | 用途 | 输入 | 典型场景 |
|------|------|------|---------|
| `dns_resolve_multi` | 12 节点多地 DNS 解析 + CDN 判定 | `domain` | 判断目标是否在 CDN 后 |
| `cname_trace` | CNAME 链路追踪 + CDN 厂商识别 | `domain` | 确认 CDN 厂商 |
| `crtsh_query` | crt.sh SSL 证书关联子域名 | `domain` | 发现同证书其他域名 |
| `ip_classify` | IP 云厂商判定（云/托管/自建） | `ips[]`（≤200） | 判断 IP 类型 |
| `c_scan` | C 段端口扫描（默认 135 Web 端口；fast=20） | `ip`/`domain`、`ports?`、`fast?` | 发现同网段服务 |
| `c_scan_status` | 查询历史扫描任务（保留兼容） | `task_id` | 查询历史任务 |
| `web_probe` | Web 指纹探测（aiohttp 主引擎） | `targets[]` | 获取存活服务标题/Server |
| `full_recon` | 一站式侦察流水线（7 步） | `domain` + 多项开关 | 一键域名全量侦察 |
| `host_collision` | Host 碰撞（域名 × IP 交叉爆破） | `domains[]`、`ips[]` | 发现 CDN 隐藏真实服务 |

完整参数与返回结构见文末「工具详细参考」。

---

## 安装

要求 **Python >= 3.11**。

```bash
# 方式一：直接安装运行依赖（推荐，最简）
pip install mcp aiohttp

# 方式二：可编辑安装（便于从任意目录 import 包）
pip install -e .
```

`bin/httpx.exe` 已随仓库通过 Git LFS 分发，用于 `web_probe` 的可选 httpx 备选引擎，**主引擎 aiohttp 不需要它**。

---

## MCP 客户端配置

在 MCP 客户端的配置文件中加入（stdio 传输，无需端口 / 鉴权管理）：

```json
{
  "mcpServers": {
    "dns-eye": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "<dns-eye 所在目录>"
    }
  }
}
```

如需启用 httpx 备选引擎（tech-detect 场景），追加 `env`：

```json
{
  "mcpServers": {
    "dns-eye": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "<dns-eye 所在目录>",
      "env": {
        "HTTPX_BIN": "<dns-eye 所在目录>/bin/httpx.exe"
      }
    }
  }
}
```

> MCP 配置不依赖任何本机绝对路径硬编码，克隆到任意目录后只需把 `cwd` 指向项目根即可。

---

## 快速验证

在 AI 会话中直接调用工具：

```python
dns_resolve_multi(domain="example.com")
cname_trace(domain="example.com")
crtsh_query(domain="example.com")

# C 段扫描：默认 135 个常用 Web 端口（同 iptest v3.0）
c_scan(ip="1.2.3.4")
# 自定义端口
c_scan(ip="1.2.3.4", ports=[80, 443, 8080])
# 快速模式：20 个最高频端口，秒出结果
c_scan(ip="1.2.3.4", fast=True)
# 也支持传域名（自动 DNS 解析取首个 IP）
c_scan(domain="mail.example.com")

c_scan_status(task_id="xxx")
web_probe(targets=["1.2.3.4:443", "https://1.2.3.5:8080"])
host_collision(domains=["target.com"], ips=["1.2.3.4"])
full_recon(domain="example.com", allow_clouds=["all"])
```

---

## 项目结构

```
dns-eye/
├── README.md            # 使用说明（本文件）
├── DESIGN.md            # 设计文档（流程 / 工具 / 架构 / 设计决策）
├── server.py            # MCP Server 主入口（stdio transport）
├── pyproject.toml       # 项目配置 / 依赖
├── LICENSE              # MIT 许可证
├── core/
│   ├── dns_resolver.py      # 多地 DNS 解析 + CNAME 追踪
│   ├── crtsh_client.py      # crt.sh API 客户端
│   ├── ip_classifier.py     # IP 云厂商判定
│   ├── c_scanner.py         # C 段端口扫描（raw socket + asyncio）
│   ├── web_prober.py        # aiohttp Web 探测（备选 httpx）
│   ├── collision.py         # Host 碰撞
│   └── __init__.py
├── data/
│   ├── cloud_ips.json       # 云厂商 IP 段 + CDN CNAME 特征（离线判定用）
│   └── ports.json           # Web 端口字典（135 个常用 Web 端口）
└── bin/
    └── httpx.exe            # 外部工具（可选备选引擎，Git LFS 分发）
```

### 数据文件

- **`data/cloud_ips.json`**：云厂商 IP 段与 CDN CNAME 关键词库，`ip_classify` 离线匹配，无需联网。
- **`data/ports.json`**：C 段扫描默认端口字典，当前 **135 个**常用 Web 端口（与 iptest v3.0 一致）。修改此文件即可调整默认扫描端口。

---

## 工具详细参考

### 1. `dns_resolve_multi`
12 节点（阿里 / 腾讯 / 114 / 360 / Google / Cloudflare / Quad9 / OpenDNS / Level3 / Verisign / Comodo / Norton）并行解析，手工构建 DNS A 记录 UDP 查询包。
- 输出：多地解析结果、IP 分布、共识度、C 段聚合、`cdn_likely` 判定、疑似源站 `suspect_origin_ips`。
- IP 分散 → CDN；同 /24 集中 → 负载均衡 / GeoDNS；海外 DNS 独有 IP → 疑似源站。

### 2. `cname_trace`
递归追踪 CNAME 链（Windows 用 `nslookup -type=CNAME` 中英文兼容，Linux 用 `dns.resolver`），与 `cloud_ips.json` 中 CDN CNAME 关键词模糊匹配。
- 输出：`cname_chain`、`cdn_detected`、`cdn_matches`。

### 3. `crtsh_query`
`GET https://crt.sh/?q=%.{domain}&output=json`，从证书关联子域名提取 IPv4。
- 输出：`total_entries`、`related_domains`、`extracted_ips`。

### 4. `ip_classify`
策略：IP 段 CIDR 匹配（高置信）→ PTR 反查（中）→ 默认 unknown。
- 输入：`ips[]`，最多 **200** 个。
- 输出：`type`（cloud / hosting / self_built / unknown）、`confidence`、`cloud_matches`、`ptr_info`。

### 5. `c_scan`
raw socket + asyncio 非阻塞连接，2000 并发（同 iptest v3.0）。
- 输入：`ip`（C 段内任意 IP）或 `domain`（二选一，自动解析取首个 IP）；`ports?` 自定义；`fast?` 快速模式（仅 20 高频端口）。
- 默认扫描 **135** 个常用 Web 端口（仅 Web 端口，不做全端口扫描）。
- 输出：`subnet`、`scanned_ips`(254)、`scanned_ports`、`open_count`、`open_services[{ip,port}]`、`elapsed_ms`。

### 6. `c_scan_status`
查询历史扫描任务状态（保留兼容旧版异步任务）。输入 `task_id`。

### 7. `web_probe`
- 主引擎：aiohttp（~60ms，远快于 httpx 的 ~23s Go 启动）。
- 需要 tech_stack 时调用 `bin/httpx.exe` 备选引擎（需 `HTTPX_BIN`）。
- 单请求超时 8s，最大并发 100。
- 输出：`total_targets`、`responded`、`results[{url,status_code,title,server,content_type,content_length,location}]`。

### 8. `full_recon`
7 步编排：DNS → CNAME → crt.sh（仅 CDN 命中时）→ IP 分类 → C 段扫描 → Web 探测 → Host 碰撞。
- 开关：`allow_clouds`（云 IP 白名单，`["all"]` 放行全部）、`custom_ports`、`no_scan`、`no_probe`、`no_collision`。
- 云 IP 默认跳过 C 段扫描；同类 /24 子网去重（每网段只扫一次）。
- 输出：各步骤结果 + `summary`（cdn_detected / scan_targets / total_open_ports / host_collision_hits / status）。

### 9. `host_collision`
对 `domains[]` × `ips[]` × `ports[]`（默认 `[80,443]`）发送自定义 Host 头请求，对比 baseline 响应差异（状态码变化 / 长度偏差 >30% / 标题变化 / Server 头差异）。
- 输入：`domains[]`（≤100）、`ips[]`（≤50）、`timeout?`(5)、`auto_variants?`(true，自动扩展 admin/api/www 等前缀，上限 30)。
- 碰撞组合保护：最多 **2000** 个请求。
- 输出：`hits_count`、`hits[{ip,port,protocol,domain,status_code,title,server,hit_reason}]`。

---

## 安全与合规

- **输入校验**：域名工具统一经 `validate_domain` 校验，拦截命令注入 / URL 注入；IP 经 `validate_ip` 校验；端口范围 1–65535。
- **无 shell**：所有外部调用（含 httpx）均以参数数组方式执行，不使用 shell，杜绝命令注入。
- **限额保护**：`ip_classify` ≤200 IP、`host_collision` ≤100 域名 / ≤50 IP / ≤2000 请求组合，防止资源滥用。
- **仅被动侦察**：工具仅做 DNS 解析、端口连接探测、Web 请求与证书查询，不发起漏洞利用。
- ⚠️ **授权使用**：本工具仅用于你拥有合法授权的目标。未经授权对第三方资产进行扫描可能违反法律与服务条款。

---

## 依赖

- Python >= 3.11
- `mcp >= 1.0.0`
- `aiohttp >= 3.9.0`
- （可选）`bin/httpx.exe` — httpx 备选引擎，用于 tech-detect。

---

## 许可证

[MIT](LICENSE) © bae