komal-pr/subrecon
GitHub: komal-pr/subrecon
一款聚合多种 OSINT 数据源与主动枚举方式的子域名发现工具，可执行 DNS 解析、HTTP 探测、技术指纹识别并生成报告。
Stars: 0 | Forks: 0
# subrecon 🔍
**多源子域名枚举 + 健康检查**
一款综合性的子域名发现工具，可聚合来自多个 OSINT 来源的数据，执行 DNS 解析和泛域名检测，通过技术指纹探测 HTTP endpoint，并生成美观的 HTML/JSON 报告。
```
$ python3 subrecon.py example.com
```
## ✨ 功能
### 被动侦察（隐蔽 — 无直接流量）
| 来源 | 类型 | 是否需要 API Key |
|--------|------|----------------|
| **crt.sh** | 证书透明度日志 | ❌ 免费 |
| **Wayback Machine** | 历史 URL 存档 | ❌ 免费 |
| **AlienVault OTX** | 威胁情报源 | 可选（免费额度即可） |
| **URLScan.io** | 网站扫描结果 | 可选（免费额度即可） |
| **VirusTotal** | 被动 DNS 数据 | ✅ 推荐 |
### 主动枚举
| 技术 | 描述 |
|-----------|-------------|
| **DNS 爆破** | 800+ 常见子域名字典（内置） |
| **排列组合** | 自动生成已发现子域名的变体（dev-api、api-v2 等） |
### 扩展与验证
| 功能 | 描述 |
|---------|-------------|
| **DNS 解析** | A 记录、CNAME、泛域名检测 |
| **ASN/IP 扩展信息** | ISP、组织、国家、城市（通过 ip-api.com） |
| **HTTP/HTTPS 探测** | 状态码、重定向、响应时间 |
| **技术指纹** | 40+ 技术特征（Cloudflare、AWS、nginx、React、WordPress 等） |
| **标题提取** | HTML `` 标签提取 |
### 报告
| 格式 | 描述 |
|--------|-------------|
| **📊 HTML 报告** | 美观的深色主题交互式报告，包含统计数据、表格和技术徽章 |
| **📄 JSON 报告** | 机器可读的输出，便于集成到 pipeline 中 |
| **🖥️ 终端 TUI** | 丰富的进度条、实时更新和汇总表 |
## 🌐 Web 界面（Portal）
subrecon 内置了一个基于 Flask 的 Web portal（`web/` + `run_web.py`）—— 这是一个支持点击操作的 UI，具有扫描历史记录和完整的结果展示页。
```
pip install flask gunicorn
python3 run_web.py # → http://127.0.0.1:5000
```
有关生产环境（在你自己的服务器/域名上部署 Nginx + Gunicorn + HTTPS），请参阅
[deploy/DEPLOY.md](deploy/DEPLOY.md)。
## 🚀 快速开始
```
# 基础扫描（使用免费来源 — 无需 API keys）
python3 subrecon.py example.com
# 使用自定义输出目录进行扫描
python3 subrecon.py example.com -o ./reports/example
# 仅特定来源
python3 subrecon.py example.com -s crtsh,wayback,dns_bruteforce
# 跳过 HTTP probing（仅 DNS）
python3 subrecon.py example.com --no-http
# 详细输出
python3 subrecon.py example.com -v
# 列出可用来源
python3 subrecon.py --list-sources
# 交互式 API key 设置
python3 subrecon.py --setup
```
## 📦 安装说明
```
# subrecon 开箱即用 — 无需安装！
# 仅需 dependencies：
pip install httpx dnspython rich
# 直接运行：
python3 subrecon.py example.com
```
### 依赖项
| 包名 | 是否必需 | 用途 |
|---------|----------|---------|
| `httpx` | 是 | 异步 HTTP 客户端 |
| `dnspython` | 是 | DNS 解析 |
| `rich` | 否（推荐） | 美观的终端 UI |
这三个包很可能已经预装在你的系统中了。
## 🔐 API Key（可选）
大多数数据源无需 API Key 即可工作，但配置后你会获得更好的结果：
```
# 交互式设置
python3 subrecon.py --setup
# 或者设置 environment variables：
export VT_API_KEY=your_virustotal_key
export URLSCAN_API_KEY=your_urlscan_key
export OTX_API_KEY=your_alienvault_key
# 或者创建 subrecon_config.json：
python3 subrecon.py --setup
```
| 来源 | 获取 API Key |
|--------|-------------|
| VirusTotal | https://www.virustotal.com/gui/home/upload |
| URLScan.io | https://urlscan.io/user/api/ |
| AlienVault OTX | https://otx.alienvault.com/ |
## 📂 输出
```
output/
└── example.com/
├── example.com_report.html # Interactive HTML report
└── example.com_report.json # Machine-readable JSON
```
### HTML 报告预览
HTML 报告包含：
- **统计卡片**：子域名总数、已解析数量、HTTP 存活数、来源数量、技术数量
- **来源明细**：每个来源贡献了多少个子域名
- **完整的子域名表格**：主机名、IP、状态码、使用的技术、页面标题
- **响应式设计**：在桌面端和移动端均可正常使用
- **深色主题**：护眼美观
## 🏗️ 项目结构
```
subrecon/
├── subrecon.py # Entry point
├── subrecon/
│ ├── __init__.py # Package version
│ ├── config.py # API key management
│ ├── cli.py # CLI parser + pipeline orchestrator
│ ├── sources/
│ │ ├── __init__.py # Source registry
│ │ ├── crtsh.py # Certificate transparency
│ │ ├── wayback.py # Wayback Machine CDX
│ │ ├── bruteforce.py # DNS brute-force + permutations
│ │ ├── alienvault.py # AlienVault OTX
│ │ └── urlscan.py # URLScan.io
│ ├── resolver.py # DNS resolution + wildcard detection
│ ├── httpprobe.py # HTTP probing + tech fingerprinting
│ └── report.py # HTML/JSON report generation
├── wordlists/
│ └── common.txt # 800+ common subdomains
├── output/ # Generated reports
├── requirements.txt
└── README.md
```
## 🧠 设计原则
- **核心功能无需任何外部 API Key** — 仅需 `httpx` 和 `dnspython` 即可运行
- **全程异步** — 采用 `asyncio` + `httpx` 实现高性能并发请求
- **优雅降级** — 每个数据源相互独立；单一数据源失败不会影响其他数据源
- **丰富的终端 UI** — 进度条、彩色输出、汇总表（并支持降级为纯文本）
- **Pipeline 架构** — 每个阶段的输出都将作为下一阶段的输入（枚举 → 解析 → 探测 → 报告）
## ⚠️ 法律免责声明
本工具仅供**授权的安全测试**使用。请仅对你拥有或已获得明确测试许可的域名使用。未经授权的扫描可能会违反法律法规及平台服务条款。
## 📝 许可证
MIT — 随意使用、学习并基于它进行构建。</div><div><strong>标签：</strong>DNS解析, Flask, GitHub, Snort++, 侦察工具, 子域名枚举, 实时处理, 密码管理, 开源项目, 系统安全, 被动扫描, 计算机取证, 运行时操纵, 逆向工具</div></article></div>
<!-- 人机验证 -->
<script>
(function () {
var base = (document.querySelector('base') && document.querySelector('base').getAttribute('href')) || '';
var path = base.replace(/\/?$/, '') + '/cap-wasm/cap_wasm.min.js';
window.CAP_CUSTOM_WASM_URL = new URL(path, window.location.href).href;
})();
</script>
</body>
</html>