lumiaurora/subscan
GitHub: lumiaurora/subscan
一款被动的子域名枚举 CLI，通过聚合公共数据源实现安全研究与 OSINT 场景下的资产发现。
Stars: 0 | Forks: 0
# subscan
[](https://github.com/lumiaurora/subscan/actions/workflows/ci.yml)
[](https://github.com/lumiaurora/subscan/releases)
[](LICENSE)
`subscan` 是一个用 Go 编写的被动子域名枚举命令行工具，适用于安全研究、OSINT 情报收集和学习。它从多个公共被动数据源收集子域名，清理结果，可选择解析 DNS，并以 JSON 或 TXT 格式导出发现。
## 为什么被动枚举很重要
被动枚举可以在不对目标发送主动探测流量的情况下，绘制组织的外部暴露面。它适用于：
- 安全侦察与资产发现
- OSINT 调查
- 实验室练习与项目作品集
- 从公共数据源验证已知基础设施
因为它依赖第三方公共数据集，所以比主动技术更安全、更安静，但仍需负责任地使用。
## 功能特性
- 无暴力破解或主动探测的纯被动 MVP
- 并发从多个公共来源收集
- 内置对 `crt.sh`、`AlienVault OTX`、`BufferOver`、`Cert Spotter`、`HackerTarget`、`Anubis`、`urlscan` 和 `RapidDNS` 的支持
- 通过 API 键可选启用 `VirusTotal` 和 `Shodan`
- 每次运行使用 `--source` 和 `--exclude-source` 选择来源
- 可配置的并发数、超时时间、重试次数和详细日志
- 支持配置文件以设置 API 键和默认运行时参数
- 来源健康状态报告：`enabled`、`disabled`、`degraded`、`auth-required`、`rate-limited`
- 为每个被动来源提供基于 fixture 的解析测试
- 标准化、通配符清理、域名过滤和去重
- 使用 `--resolve` 时启用并发 DNS 解析检查并进行通配符 DNS 过滤
- 丰富的 JSON 报告，包含时间戳、来源归属、来源耗时和 DNS 详情
- 支持导出为 JSON 或 TXT
- 清晰的终端输出，显示来源进度和统计计数
- 健壮的错误处理，单个来源失败不会中断运行
- 跨平台 Go CLI，支持 macOS、Linux 和 Windows
## 项目结构
```
subscan/
.goreleaser.yaml
CHANGELOG.md
LICENSE
config.example.json
main.go
go.mod
README.md
internal/
buildinfo/
buildinfo.go
config/
config.go
sources/
anubis.go
bufferover.go
certspotter.go
client.go
crtsh.go
hackertarget.go
otx.go
rapiddns.go
settings.go
shodan.go
urlscan.go
virustotal.go
resolver/
resolver.go
output/
output.go
utils/
clean.go
filter.go
```
## 安装
从 [GitHub Releases](https://github.com/lumiaurora/subscan/releases) 下载最新的发布包，并使用提供的 `checksums.txt` 文件验证。
从源码本地构建：
克隆仓库并本地构建：
```
git clone https://github.com/lumiaurora/subscan.git
cd subscan
go build -o subscan .
```
在 Windows 上：
```
go build -o subscan.exe .
```
## 构建说明
构建二进制文件：
```
go build .
```
构建所有包：
```
go build ./...
```
直接运行无需构建二进制：
```
go run . -d example.com
```
打印构建信息：
```
go run . --version
```
## 用法
```
subscan -d example.com [--resolve] [--json|--txt] [--output file] [--source list] [--exclude-source list]
subscan --version
```
`subscan` 支持三层配置：
- 每次运行的 CLI 标志
- 用于 API 键的环境变量
- 可选的 JSON 配置文件用于 API 键和默认设置
优先级规则：
- CLI 标志覆盖配置文件默认值
- 环境变量覆盖配置文件中的 API 键
### 标志
- `-d, --domain string`：目标域名
- `--resolve`：解析发现的域名并仅保留活跃结果
- `--json`：以 JSON 格式导出结果
- `--txt`：以 TXT 格式导出结果
- `--output string`：输出文件路径
- `--source string`：逗号分隔的来源 ID 列表（包含）
- `--exclude-source string`：逗号分隔的来源 ID 列表（排除）
- `--threads int`：最大并发来源请求和 DNS 工作线程数
- `--timeout int`：HTTP 和 DNS 超时时间（秒）
- `--retries int`：被动来源请求的重试次数
- `--verbose`：显示详细运行时信息
- `--version`：打印版本和构建元数据
- `--config string`：可选配置文件路径
- `--sources`：打印工具使用的被动来源列表
### 来源 ID
在 `--source` 和 `--exclude-source` 中使用以下值：
- `crtsh`
- `otx`
- `bufferover`
- `certspotter`
- `hackertarget`
- `anubis`
- `urlscan`
- `rapiddns`
- `virustotal`（可选，需要 API 键）
- `shodan`（可选，需要 API 键）
### API 键
- `OTX_API_KEY`：帮助减少来自 AlienVault OTX 的频率限制
- `VT_API_KEY`：启用 VirusTotal 子域名收集
- `SHODAN_API_KEY`：启用 Shodan DNS 子域名收集
### 默认来源行为
默认情况下，`subscan` 启用以下被动来源：
- `crt.sh`
- `AlienVault OTX`
- `BufferOver`
- `Cert Spotter`
- `HackerTarget`
- `Anubis`
- `urlscan`
- `RapidDNS`
`VirusTotal` 和 `Shodan` 是可选的，仅在配置了对应的 API 键时启用。
如果没有 API 键，`AlienVault OTX` 仍可运行，但公共访问可能会受到频率限制。设置 `OTX_API_KEY` 可提高可靠性。
你可以通过以下方式在运行时检查当前启用的来源集合：
```
subscan --sources
```
`--sources` 现在会打印来源健康信息，因此可选提供者在运行开始前会明确显示为 `enabled` 或 `disabled`。
在枚举过程中，失败的提供者会以明确的运行时健康状态报告，例如 `rate-limited`、`auth-required` 或 `degraded`，而不是通用的失败消息。
### 配置文件
默认配置文件路径：
- macOS 和 Linux：`~/.config/subscan/config.json`
- Windows：`%AppData%\subscan\config.json`
你也可以通过 `--config` 传递自定义路径。
示例文件包含在 `config.example.json` 中。
示例：
```
{
"otx_api_key": "",
"vt_api_key": "",
"shodan_api_key": "",
"defaults": {
"resolve": false,
"json": false,
"txt": false,
"output": "",
"threads": 20,
"timeout_seconds": 30,
"retries": 2,
"verbose": false,
"include_sources": ["crtsh", "certspotter", "rapiddns"],
"exclude_sources": ["bufferover"]
}
}
```
### API 键示例
macOS 和 Linux：
```
export OTX_API_KEY=your_otx_key
export VT_API_KEY=your_virustotal_key
export SHODAN_API_KEY=your_shodan_key
subscan --sources
```
Windows PowerShell：
```
$env:OTX_API_KEY="your_otx_key"
$env:VT_API_KEY="your_virustotal_key"
$env:SHODAN_API_KEY="your_shodan_key"
subscan.exe --sources
```
## 示例
基础被动枚举：
```
subscan -d example.com
```
仅使用特定来源集合：
```
subscan -d example.com --source crtsh,certspotter,urlscan
```
为一次运行排除不稳定来源：
```
subscan -d example.com --exclude-source bufferover
```
解析发现的域名：
```
subscan -d example.com --resolve
```
输出 JSON：
```
subscan -d example.com --resolve --json --output results.json
```
输出 TXT：
```
subscan -d example.com --txt --output results.txt
```
调整运行时行为：
```
subscan -d example.com --threads 10 --timeout 20 --retries 1 --verbose
```
使用自定义配置文件：
```
subscan --config ./config.example.json --sources
```
显示已配置的被动来源：
```
subscan --sources
subscan -d example.com --sources
```
打印版本/构建元数据：
```
subscan --version
```
## 示例输出
```
$ subscan -d example.com --resolve --json --output results.json
[+] Target: example.com
[+] Querying crt.sh...
[+] Querying AlienVault OTX...
[!] AlienVault OTX [rate-limited]: AlienVault OTX is rate limiting anonymous requests; set OTX_API_KEY to improve reliability
[+] Querying Cert Spotter...
[+] Querying RapidDNS...
[+] Querying urlscan...
[+] RapidDNS returned 23 candidate(s)
[+] Cert Spotter returned 27 candidate(s)
[+] urlscan returned 12 candidate(s)
[+] crt.sh returned 21 candidate(s)
[+] Raw results: 83
[+] Unique subdomains: 19
[+] Resolving discovered hosts...
[+] Wildcard-filtered subdomains: 2
[+] Live subdomains: 11
[+] Results written to results.json
api.example.com
cdn.example.com
dev.example.com
mail.example.com
vpn.example.com
```
## JSON 输出格式
```
{
"domain": "example.com",
"timestamp": "2026-04-20T10:15:04Z",
"total_found": 11,
"resolved_enabled": true,
"metadata": {
"started_at": "2026-04-20T10:15:01Z",
"completed_at": "2026-04-20T10:15:04Z",
"duration_ms": 2145,
"raw_results": 83,
"unique_subdomains": 19,
"final_subdomains": 11,
"wildcard_filtered": 2,
"enabled_sources": [
{
"id": "crtsh",
"name": "crt.sh"
},
{
"id": "certspotter",
"name": "Cert Spotter"
}
],
"failed_sources": [
{
"id": "otx",
"name": "AlienVault OTX",
"health": "rate-limited",
"error": "AlienVault OTX is rate limiting anonymous requests; set OTX_API_KEY to improve reliability",
"duration_ms": 801
}
],
"source_timings": [
{
"id": "crtsh",
"name": "crt.sh",
"status": "success",
"candidates": 21,
"duration_ms": 632
},
{
"id": "otx",
"name": "AlienVault OTX",
"status": "rate-limited",
"candidates": 0,
"duration_ms": 801
}
]
},
"subdomains": [
{
"name": "api.example.com",
"sources": [
"crt.sh",
"Cert Spotter"
],
"ips": [
"93.184.216.34"
],
"cnames": [
"edge.example.net"
]
},
{
"name": "cdn.example.com",
"sources": [
"RapidDNS",
"urlscan"
]
}
]
}
```
## 来源覆盖说明
`subscan` 使用的公共被动来源可能会随时间变化、受到频率限制、退役或返回不完整数据。该工具设计为在某个来源失败时继续运行，但枚举质量取决于这些公共数据集的可用性和新鲜度。
部分提供者仅为尽力而为。例如，公共 OTX 访问可能返回 `429 Too Many Requests`，而 BufferOver 在某些网络上可能间歇性不可用。`subscan` 将这些运行时失败归类为 `rate-limited`、`auth-required` 或 `degraded`，并且每个解析器都通过本地 fixture 测试覆盖，因此在开发过程中更容易捕获上游响应格式变化。
## 架构
- `main.go`：CLI 解析、配置加载、来源选择、编排和终端用户体验
- `internal/config`：JSON 配置文件加载和默认配置路径处理
- `internal/buildinfo`：内嵌版本、提交、构建日期和构建者元数据
- `internal/sources`：被动来源客户端、来源特定解析、健康分类、重试/退避、API 键处理和详细请求诊断
- `internal/utils`：标准化、通配符清理、过滤和去重
- `internal/resolver`：并发 DNS 解析，带可配置的 worker 和超时设置以及通配符 DNS 检测
- `internal/output`：TXT 和 JSON 导出器
##发布自动化
发布通过 Goreleaser 构建：
- 标记的发布会打包跨平台归档文件
- 每个发布都会附带 `checksums.txt`
- 二进制文件包含内嵌版本、提交、构建日期和构建者元数据
## 免责声明
`subscan` 仅用于被动枚举、授权的安全研究、OSINT 和学习目的。不要将其用于违反法律、服务条款或组织策略的行为。始终在需要时获得许可。
标签：Anubis, Ask搜索, BufferOver, Cert Spotter, C语言库, DNS解析, ESC4, ESC6, ETW劫持, EVTX分析, Go语言, HackerTarget, Homebrew安装, JSON报告, OSINT, PB级数据处理, RapidDNS, SEO, Transformers, urlscan, VirusTotal, 二进制发布, 侦察框架, 公开来源, 动态插桩, 去重, 域名发现, 子域名枚举, 子域名枚举工具, 安全工具库, 安全研究工具, 安全运维, 并发控制, 并发采集, 开源工具, 开源项目, 归一化, 恶意代码分析, 数据展示, 文本导出, 文档结构分析, 无侵入侦察, 日志审计, 日志记录, 测试夹具, 程序破解, 系统安全, 红队, 被动DNS, 被动侦察, 被动枚举, 证书透明, 通用签名格式, 通配符清理, 配置文件, 重试机制