SkyzFallin/subharvest
GitHub: SkyzFallin/subharvest
一款以纯被动方式从公开来源聚合目标子域名的枚举工具，默认不向目标发送流量，适合隐蔽的信息收集场景。
Stars: 0 | Forks: 0
从公共来源被动枚举子域名。可选主动探测，默认不启用。
作者：SkyzFallin
## 功能介绍
`subharvest` 通过查询证书透明度日志、被动 DNS 提供商、Web 档案以及目标自身的区域记录，来聚合目标顶点域名的子域名。它会对发现的结果进行去重，按需验证，并输出带有**来源信息**的结构化结果 —— 每个子域名都会附带返回该子域名的来源列表。
除非显式设置了 `--active`，否则目标不会收到来自操作者的任何流量。仅使用被动来源时，你是在向第三方 API 查询有关目标的信息，而不是直接查询目标本身。
## 快速入门
`subharvest` 尚未发布到 PyPI —— 请直接从 GitHub 安装：
```
# 推荐：通过 pipx 隔离安装
pipx install git+https://github.com/SkyzFallin/subharvest.git
# 或者从本地克隆安装
git clone https://github.com/SkyzFallin/subharvest.git
cd subharvest
pipx install .
# 或者用于开发（editable install）
pipx install -e .
```
然后：
```
# 默认：查询所有无需 key 的 passive sources，输出 JSON 至 stdout
subharvest example.com
# Plaintext 列表 — 管道传递至 httpx、nuclei 等
subharvest example.com --format txt
# 解析所有发现，生成 Markdown 报告
subharvest example.com --resolve -o report.md --format md
# 仅使用单一 source，附带逐个 source 的详细 trace
subharvest example.com --only crtsh -v
# 查看可用内容
subharvest --list-sources
```
## 数据来源 (v0.1)
| 来源 | 类型 | 是否需要密钥 |
|---|---|---|
| `crtsh` | 证书透明度 | 否 |
| `otx` | AlienVault OTX 被动 DNS | 否 |
| `urlscan` | urlscan.io 搜索索引 | 否 |
| `wayback` | Wayback Machine CDX | 否 |
| `dns_records` | 目标自身的 SOA/NS/MX/SPF/DMARC | 否 |
需要 API 密钥的来源（`securitytrails`、`virustotal`、`censys`、`google_ct`）已规划于 v0.2 版本。主动来源（`bruteforce`、`permutation`、`axfr`）已规划于 v0.3 版本。
## 输出格式
| 格式 | 标志 | 用途 |
|---|---|---|
| JSON | `--format json`（默认） | 结构化，包含完整来源信息及各来源的遥测数据 |
| 纯文本 | `--format txt` | 每行一个子域名，已排序且已去重 |
| CSV | `--format csv` | 电子表格处理流程 |
| Markdown | `--format md` | 人类可读的评估报告 |
## 使用选项
```
subharvest [flags]
Sources:
--active Enable active discovery (brute force, permutation, AXFR)
--skip Skip a specific source (repeatable)
--only Only use this source (repeatable)
--list-sources Print all available sources and exit
Active mode (v0.3):
--wordlist Custom DNS brute force wordlist
--permutations Custom permutation list
--no-permute Disable permutation even in active mode
--threads Brute force concurrency (default: 50)
Validation:
--resolve Resolve each subdomain after collection
--resolver Custom DNS resolver IP
--doh Use DNS-over-HTTPS
Output:
--format Output format (default: json)
-o, --output Write to file
--quiet Suppress progress output
-v, --verbose Show per-source query trace
Config:
--config Custom config file (default: ~/.subharvest/config.toml)
--no-color Disable ANSI color
--version Print version and exit
```
## 自动保存的文件
无论 `--format` 或 `-o` 设置为何值，每次运行都会自动将子域名的纯文本列表写入当前工作目录下的 `./output/-.txt` 文件中。这样一来，即使通过管道将 JSON 输出传递给其他工具，你仍然可以获得一个可用的文件。
```
$ subharvest example.com
... output ...
artifact: output/example.com-20260509-091530.txt
```
使用 `--no-auto-output` 可禁用此功能。使用 `--output-dir ` 可更改保存目录。
## 注意事项
- **泛解析处理。** 在进行解析之前，`subharvest` 会使用随机的无意义子域名对顶点域名进行探测。如果它们能够被解析，工具会捕获泛解析指纹（IP、CNAME），并在 JSON 输出中将匹配到的结果标记为 `filtered_wildcard: true`。被过滤的条目不会被静默丢弃 —— 操作者可以审查被过滤的内容。
- **SaaS CNAME 标记。** 当设置了 `--resolve` 时，如果发现结果的 CNAME 指向已知的 SaaS 提供商（`*.cloudfront.net`、`*.github.io`、`*.azurewebsites.net` 等），将通过 `saas_cname` 对其进行标记。v0.4 版本将添加实时的接管候选项检测。
- **API 密钥。** 从 `~/.subharvest/config.toml` 或 `SUBHARVEST__API_KEY` 环境变量中读取。没有配置密钥的来源将被跳过并给出提示 —— 该工具无需任何密钥也可运行。
- **在跳板机上运行。** 被动来源会查询记录请求者 IP 的第三方 API。为了避免将你的家庭/办公 IP 泄露到提供商的遥测数据中，请在测试环境中的跳板机上运行此工具。
- **速率限制。** 每个来源都设置了保守的默认值。本地缓存（v0.2）将避免在一小时内针对同一域名重复请求来源。
## 仅限授权使用
本工具专为经授权的、您已获准进行的测试任务而构建。被动来源查询的是关于目标的第三方 API —— 而不是目标本身 —— 但操作者仍需对范围和授权负责，尤其是在启用 `--active` 模式时。请勿将此工具指向您未获得书面授权进行评估的基础设施。
## 更新日志
- **v0.1.0** — MVP 版本。包含 crt.sh, OTX, URLScan, Wayback, DNS records 来源。支持泛解析检测。提供 JSON/TXT/CSV/MD 输出。支持带有 SaaS CNAME 标记的 `--resolve` 标志。
## 路线图
- **v0.2** — SecurityTrails, VirusTotal, Censys, Google CT。支持带 TTL 的本地缓存。TOML 配置模式。
- **v0.3** — 主动模式：DNS 暴力破解、排列引擎、AXFR 尝试。线程与速率限制控制。
- **v0.4** — 批量模式（`-f domains.txt`）。接管候选项标记。差异模式（与上次运行的增量对比）。
- **v0.5** — ASN 相邻域名发现。与 phishprint 集成。兼容 httpx/nuclei 管道的适配器。
### 先前作品
`subharvest` 属于一个成熟度很高的工具类别。以下这些工具塑造了被动子域名枚举的现状，值得了解：
- [subfinder](https://github.com/projectdiscovery/subfinder) — ProjectDiscovery 出品，Go 语言编写。
- [amass](https://github.com/owasp-amass/amass) — OWASP 出品，Go 语言编写。深度的主动枚举。
- [assetfinder](https://github.com/tomnomnom/assetfinder) — tomnomnom 出品，Go 语言编写。极简主义。
- [findomain](https://github.com/findomain/findomain) — Findomain 出品，Rust 语言编写。
- [sublist3r](https://github.com/aboul3la/Sublist3r) — Python 语言编写，虽已不再积极维护，但确立了许多规范。
`subharvest` 是独立编写的代码（非 fork，非复制） —— 但这个工具品类之所以存在，离不开上述工具的贡献。
### 数据提供商
被动来源会查询第三方服务。没有它们，本工具将无从聚合数据：
- [crt.sh](https://crt.sh) 由 Sectigo 提供 — 证书透明度搜索。
- [AlienVault OTX](https://otx.alienvault.com) — 被动 DNS。
- [urlscan.io](https://urlscan.io) — URL 扫描索引。
- [Internet Archive Wayback Machine](https://web.archive.org) — CDX 索引。
### 依赖库
构建于：
- [`httpx`](https://www.python-httpx.org/) — 异步 HTTP 客户端。
- [`dnspython`](https://www.dnspython.org/) — 异步 DNS 解析器。
- [`typer`](https://typer.tiangolo.com/) + [`rich`](https://rich.readthedocs.io/) — CLI 及终端输出。
- [`respx`](https://lundberg.github.io/respx/) + [`pytest`](https://docs.pytest.org/) — 模拟 HTTP 的测试套件。
## 项目规范
- Python 3.11+，异步优先（`httpx`、`dnspython.asyncresolver`）。
- 来源接口定义在 `subharvest/sources/base.py` 中 —— 添加新来源只需实现一个包含单个 `async def fetch(domain) -> list[Finding]` 方法的类。
- 测试使用 `tests/fixtures/` 中的固定数据。测试套件中不包含真实的 API 调用。
- 使用 `pytest -q` 运行测试。
## AUDIT.md
有关代码质量、安全性和功能积压的备注，请参见 [AUDIT.md](AUDIT.md)。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
标签：crtsh, DNS解析, ESC4, GitHub, Linux安全, OSINT, Python, Web安全, 域名探测, 威胁情报, 子域名挖掘机, 子域名收集, 子域名枚举, 安全工具库, 开发者工具, 开源项目, 数据展示, 无后门, 系统安全, 红队, 网络安全, 蓝队分析, 被动DNS, 被动侦察, 证书透明度日志, 运行时操纵, 进程管理, 逆向工具, 隐私保护