bidhata/SubGrab
GitHub: bidhata/SubGrab
一款集成 AI 与多源被动/主动技术的子域名枚举工具，提升发现效率与覆盖面。
Stars: 4 | Forks: 1
# 🔍 SubGrab
### 高级子域名枚举工具
[](https://python.org)
[](LICENSE.txt)
[](https://github.com/bidhata/SubGrab/releases)
[](https://github.com/bidhata/SubGrab/releases)
[](https://github.com/bidhata/SubGrab/stargazers)
多线程子域名枚举工具，整合 **9 种被动来源**、**主动侦察** 与 **AI 驱动的模式生成**，提供单一 CLI 与 GUI 工具 —— Windows 二进制文件无需 Python。
[**⬇️ 下载二进制文件**](https://github.com/bidhata/SubGrab/releases) · [**📖 快速开始**](#-quick-start) · [**🔌 插件指南**](#-plugin-system) · [**🖥️ GUI**](#-gui-interface)
## ✨ 功能一览
|
**🌐 被动发现**
- 证书透明度日志
- Web 归档（Wayback / CommonCrawl）
- 搜索引擎 dork
- C99 SubdomainFinder
- DNS 数据库
- 安全 API（Shodan、VT、Censys…）
- GitHub 代码搜索
|
**🎯 主动侦察**
- HTTP/HTTPS 探测 + 指纹识别
- 端口扫描（SSH、FTP、SMTP…）
- 子域名接管检测（50+ 服务）
- Shodan IP 增强
- 通配符 DNS 过滤
|
**🤖 AI 生成**
- Grok（xAI）—— 免费额度
- OpenRouter — Claude 4、GPT-4o、Gemini…
- 对发现的子域名进行模式分析
- 在传统来源完成后运行
|
## 📥 安装
### 选项 A — 预构建二进制文件（Windows，无需 Python）
```
1. Download SubGrab-vX.X.X-windows-x64.zip from Releases
2. Extract → double-click SubGrab.exe for GUI
or run SubGrab.exe example.com for CLI
```
### 选项 B — 从源码运行
**要求：** Python 3.8+
```
git clone https://github.com/bidhata/SubGrab.git
cd SubGrab
pip install -r requirements.txt
```
📦 依赖项
| 包 | 用途 |
|---------|---------|
| `requests` | HTTP 客户端 |
| `dnspython` | DNS 解析、区域传输、SRV |
| `colorama` | 彩色终端输出 |
| `beautifulsoup4` | HTML 解析（C99 页面） |
| `lxml` | 快速 HTML 解析器 |
| `tqdm` | 进度条 |
| `shodan` | Shodan API 客户端 |
## 🚀 快速开始
```
# 仅被动（无需 API 密钥）
python subgrab.py example.com
# 快速模式 — 跳过暴力破解和反 DNS
python subgrab.py example.com --fast --threads 100
# 隐身模式 — 请求间随机延迟
python subgrab.py example.com --stealth
# 由 Grok 提供支持（可用免费额度）
python subgrab.py example.com --grok-key xai-YOURKEY
# 全覆盖 — 双 AI + 所有 API
python subgrab.py example.com \
--grok-key xai-YOURKEY \
--openrouter-key sk-or-YOURKEY \
--shodan-key SHODANKEY \
--virustotal-key VTKEY \
--threads 100
# 启动 GUI
python subgrab_gui.py # source
# 或
SubGrab.exe # binary
```
## 📋 CLI 参考
```
subgrab.py domain [options]
```
### ⚙️ 通用选项
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `-t, --threads` | `50` | 工作线程数（1–200） |
| `--timeout` | `30` | 请求超时（秒） |
| `--fast` | 关闭 | 跳过暴力破解 + 反向 DNS |
| `--stealth` | 关闭 | 添加 0.5–2.0 秒随机延迟 |
| `--proxy-file FILE` | — | 换行分隔的代理列表 |
| `--wordlist FILE` | 内置 | 自定义 DNS 暴力破解词表 |
| `--nameservers NS...` | `8.8.8.8 8.8.4.4 1.1.1.1` | DNS 解析器 |
### 🔑 API 密钥标志
| 标志 | 服务 | 免费层级 |
|------|---------|-----------|
| `--shodan-key` | Shodan | 受限 |
| `--securitytrails-key` | SecurityTrails | 每月 50 次请求 |
| `--virustotal-key` | VirusTotal | 每分钟 4 次请求 |
| `--censys-id` + `--censys-secret` | Censys | 每月 250 次请求 |
| `--github-token` | GitHub | 每小时 5,000 次请求 |
| `--whoisxml-key` | WhoisXML | 500 积分 |
### 🤖 AI 标志
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--grok-key` | — | xAI Grok API 密钥 |
| `--grok-model` | `grok-3` | 模型 ID |
| `--openrouter-key` | — | OpenRouter API 密钥 |
| `--openrouter-model` | `anthropic/claude-sonnet-4-5` | 模型 ID |
## 🏗️ 架构
```
SubGrab/
├── main.py ← unified entry point (GUI or CLI)
├── subgrab.py ← CLI engine + SubdomainEnumerator
├── subgrab_gui.py ← dark GUI (Catppuccin Mocha theme)
├── SubGrab.spec ← PyInstaller build spec
├── requirements.txt
├── start_subgrab_gui.bat ← Windows one-click launcher
│
├── modules/ ← passive scanner plugins (drop .py to add)
│ ├── base.py ← BaseScanner ABC + load_modules()
│ ├── 01_certificate_transparency.py
│ ├── 02_web_archives.py
│ ├── 03_search_engines.py
│ ├── 04_dns_databases.py
│ ├── 05_whoisxml.py
│ ├── 06_security_apis.py
│ ├── 07_github_search.py
│ ├── 08_dns_bruteforce.py
│ └── 09_reverse_dns.py
│
└── ai_engine/ ← AI generation plugins
├── base.py ← BaseAIEngine + load_ai_engines()
├── config.ini ← API keys (not committed)
├── openrouter_ai.py
└── grok_ai.py
```
`run_passive_discovery()` 按字母顺序加载 `modules/` 中的每个 `BaseScanner` 子类。
`run_ai_engines()` 在被动发现完成后运行，以便 AI 能看到真实的发现模式。
## 🔌 被动扫描器模块
| # | 模块 | 来源 | 必需密钥 | 快速跳过 |
|---|--------|---------|:---:|:---:|
| 01 | 证书透明度 | crt.sh · CertSpotter · RapidDNS · urlscan.io | — | ✗ |
| 02 | Web 归档 | Wayback Machine CDX · CommonCrawl（最新索引） | — | ✗ |
| 03 | 搜索引擎 | Bing（分页）· DuckDuckGo · Yahoo · Google | — | ✗ |
| 04 | DNS 数据库 | C99 SubFinder · HackerTarget | — | ✗ |
| 05 | WhoisXML | 子域名查找 API | `whoisxml` | ✗ |
| 06 | 安全 API | VirusTotal · SecurityTrails · Censys · Shodan | 可选 | ✗ |
| 07 | GitHub 搜索 | REST API + HTML 回退 | 可选 | **✓** |
| 08 | DNS 暴力破解 | 词表 + 排列组合 + SRV + 区域传输 | — | ✗ |
| 09 | 反向 DNS | 对已发现地址进行 ±10 IP 扫描 | — | **✓** |
🧬 C99 解析 — 3 层回退
1. 解析 `class="sd"` 元素（主布局）
2. 尝试备用类名：`subdomain`、`host`、`domain`、`sub`、`name`
3. 对原始 HTML 进行正则扫描：`[\w][\w\-]*(?:\.[\w\-]+)*\.{domain}`
IP 地址和 Cloudflare 状态将保存至 `{domain}_c99_scan.json`。
🔤 DNS 暴力破解 — 排列扩展
对于每个词表条目，模块生成：
- 原始单词
- `{prefix}-{word}` / `{prefix}{word}`（用于：`dev test prod uat new old staging beta alpha`）
- `{word}-{suffix}` / `{word}{suffix}`（用于：`dev prod test api app web mobile`）
- `{word}1` 到 `{word}9`
所有排列组合会去重，并通过 `ThreadPoolExecutor` 并行解析。
## 🎯 主动侦察
被动发现完成后，每个发现的子域名将并行探测：
| 检查 | 功能 |
|-------|-------------|
| 🌐 HTTP/HTTPS | 状态码、重定向链、`Server` 头部、页面标题 |
| 🔌 端口扫描 | 检查端口 21、2、25、80、443 |
| 🖥️ 技术识别 | 服务器横幅 + 常见框架模式 |
| 🔍 Shodan 增强 | 开放端口、CVE、IP 所有者（需要密钥） |
| ⚠️ 接管检测 | CNAME 解析 + HTTP 正文匹配 vs 50+ 服务指纹 |
**接管覆盖范围：** AWS S3、Azure（Blob/应用/CDN/流量管理器）、GitHub Pages、Heroku、Netlify、Vercel、Fly.io、Render、Firebase、Fastly、CloudFront、Surge.sh、Zendesk、Ghost、Tumblr、WordPress.com，以及 35+ 更多。
## 🤖 AI 集成
AI 模块在所有传统来源完成后激活 —— 模型分析真实发现的模式，而非猜测。
```
Traditional sources → [api, api1, api2, dev-api, staging-api]
↓
AI pattern analysis
↓
[api3, api-v2, dev-api2, test-api, ...]
```
### Grok（xAI）— 推荐免费选项
```
python subgrab.py example.com --grok-key xai-YOURKEY
python subgrab.py example.com --grok-key xai-YOURKEY --grok-model grok-3-mini
```
| 模型 | 适用场景 | 成本 |
|-------|---------|------|
| `grok-3` | 通用用途 · **推荐** | $ |
| `grok-3-fast` | 更快响应 | $ |
| `grok-3-mini` | 预算 / 快速扫描 | ¢ |
| `grok-3-mini-fast` | 最高速度 | ¢ |
获取密钥 → [console.x.ai](https://console.x.ai)（新账户免费额度）
### OpenRouter — 通过单一 API 访问任意 LLM
```
python subgrab.py example.com \
--openrouter-key sk-or-YOURKEY \
--openrouter-model anthropic/claude-sonnet-4-5
```
| 模型 | 质量 | 成本 |
|-------|---------|------|
| `anthropic/claude-sonnet-4-5` | 优秀 · **推荐** | $$ |
| `anthropic/claude-opus-4` | 最佳整体 | $$$$ |
| `anthropic/claude-haiku-4-5` | 快速、经济 | $ |
| `openai/gpt-4o` | 高质量 | $$$ |
| `openai/o3-mini` | 推理 | $$ |
| `google/gemini-2.0-flash` | 快速 + 廉价 | ¢ |
| `deepseek/deepseek-r1` | 开源 | ¢ |
获取密钥 → [openrouter.ai](https://openrouter.ai)
### 应使用哪种 AI 策略？
| 场景 | 推荐 |
|-----------|---------------|
| 首次使用 / 无预算 | Grok（免费额度） |
| 常规漏洞赏金 | 仅使用 Grok |
| 渗透测试 | 双 AI — Grok + Claude |
| 快速侦察 | `--fast`，不使用 AI |
| 最大覆盖范围 | 双 AI + 所有 API 密钥 |
## 📁 输出
所有结果写入 **`{domain}_results/`**：
```
example.com_results/
├── 📄 all_subdomains.txt — full deduplicated list
├── ✅ active_subdomains.txt — HTTP/HTTPS responsive
├── ❌ inactive_subdomains.txt — non-responsive
├── 🔑 ssh_enabled.txt — port 22 open
├── ⚠️ takeover_candidates.txt — potential takeover targets
├── 📊 scan_results.json — full structured report
├── 📊 scan_results.csv — spreadsheet-compatible
├── 🌐 report.html — interactive dashboard with charts
└── 🗄️ {domain}_c99_scan.json — C99 IP + Cloudflare data
```
📄 JSON 报告模式
```
{
"domain": "example.com",
"scan_date": "2026-04-18T12:00:00",
"total_subdomains": 312,
"active_subdomains": 187,
"subdomains": {
"api.example.com": {
"ip": "93.184.216.34",
"active": true,
"status_code": 200,
"server": "nginx",
"title": "API Gateway",
"source": "c99"
}
}
}
```
## 🧩 插件系统
插件系统是 **完全自动** 的 —— 只需将 `.py` 文件放入 `modules/` 即可在下一轮扫描中运行。无需注册或配置变更。
| 操作 | 方法 |
|--------|-----|
| ➕ 添加扫描器 | 将 `.py` 文件放入 `modules/` |
| ➖ 移除扫描器 | 删除该文件 |
| ⏸️ 临时禁用 | 重命名为 `_file.py` |
| 🔢 控制顺序 | 使用数字前缀：`12_mysource.py` |
### 零导入模板
`BaseScanner` 和 `Fore` 已 **预注入** —— 无需导入：
```
# modules/12_my_source.py
class MySource(BaseScanner):
name = "My Source"
description = "One-line description"
requires_key = None # set to api_keys dict key to auto-skip if absent
fast_mode_skip = False # set True to skip with --fast
def run(self):
subdomains = set()
resp = self.get_session().get(
f"https://api.example.com/subdomains?q={self.domain}", timeout=10)
for entry in resp.json():
host = entry.get("hostname", "").strip().lower()
if host.endswith(f".{self.domain}") and self.is_valid(host):
subdomains.add(host)
return subdomains
```
📚 BaseScanner API 参考
| 成员 | 类型 | 描述 |
|--------|------|-------------|
| `self.domain` | `str` | 目标域名 |
| `self.api_keys` | `dict` | 所有配置的 API 密钥 |
| `self.subdomains` | `set` | 已发现的子域名集合 |
| `self.subdomain_info` | `dict` | 每个子域名的元数据 |
| `self.output_dir` | `str` | 结果目录路径 |
| `self.fast_mode` | `bool` | 当传递 `--fast` 时为真 |
| `self.threads` | `int` | 线程数 |
| `self.timeout` | `int` | 请求超时（秒） |
| `self.wordlist` | `str\|None` | 自定义 DNS 暴力破解词表路径 |
| `self.get_session()` | 方法 | 线程局部的 `requests.Session` |
| `self.get_resolver()` | 方法 | 线程局部的 DNS 解析器 |
| `self.resolve_domain(sub)` | 方法 | 解析子域名 → IP 或 `None` |
| `self.is_valid(sub)` | 方法 | 验证子域名格式 |
| `self.stealth_delay()` | 方法 | 在静默模式下休眠 0.5–2 秒 |
| `Fore.RED/GREEN/CYAN/YELLOW` | colorama | 预注入的颜色常量 |
💡 实际示例 — AlienVault OTX 15 行代码
```
# modules/12_alienvault.py
class AlienVault(BaseScanner):
name = "AlienVault OTX"
description = "Passive DNS from OTX"
def run(self):
subdomains = set()
try:
url = f"https://otx.alienvault.com/api/v1/indicators/domain/{self.domain}/passive_dns"
for record in self.get_session().get(url, timeout=15).json().get("passive_dns", []):
host = record.get("hostname", "").lower().strip()
if host.endswith(f".{self.domain}") and self.is_valid(host):
subdomains.add(host)
except Exception as e:
print(f"{Fore.RED}[!] {self.name}: {e}")
return subdomains
```
将其放入 `modules/` — 仅此而已。
## 🖥️ GUI 界面
```
python subgrab_gui.py # from source
start_subgrab_gui.bat # Windows one-click
SubGrab.exe # binary — double-click
```
| 功能 | 详情 |
|---------|--------|
| 🎨 主题 | 完整的 Catppuccin Mocha 深色主题 |
| 📐 布局 | 水平分割 — 配置侧边栏 + 实时终端 |
| 🔑 API 密钥标签页 | 显示/隐藏切换 · 直接“获取密钥”链接 · 退出时自动保存 |
| ⚙️ 高级标签页 | DNS 解析器 · 自定义词表 · 代理文件 |
| 📟 终端 | 去除 ANSI 颜色的输出 · 复制 · 清除 |
| 📊 状态栏 | 实时子域名计数 · 活动计数 · 计时器 |
| ✅ 验证 | 实时域名格式检查（绿色/红色边框） |
## 🛠️ 故障排除
CT 返回结果少于预期
crt.sh 对大量用户限流。该模块会重试 3 次并使用指数退避，并回退到 CertSpotter、RapidDNS 和 urlscan.io —— 无论 crt.sh 状态如何，这四个都会运行。
C99 无结果
C99 需要在过去 14 天内存在公开扫描。如果未找到，工具会自动回退到 HackerTarget。
Google / Yahoo 返回 0 结果
搜索引擎经常屏蔽自动化请求。其他来源不受影响 —— 工具会记录警告并继续执行。
DNS 暴力破解缓慢
使用更短的词表并减少线程数以避免触发 DNS 速率限制：
```
python subgrab.py example.com --wordlist small.txt --threads 20
```
AI 未返回子域名
两个 AI 引擎都需要 **至少 3 个已发现的子域名** 才能进入模式分析阶段。请检查 API 密钥有效性和信用额度（在对应控制台查看：[console.x.ai](https://console.x.ai) / [openrouter.ai](https://openrouter.ai)）。
401 未授权 / 429 请求过多
- **401** — API 密钥无效或已过期。请从提供商控制台重新生成。
- **429** — 达到速率限制。请添加 `--stealth` 延迟或等待后重试。
## 🤝 贡献
1. 叉取仓库
2. 创建功能分支：`git checkout -b feature/new-source`
3. 在 `modules/` 中添加你的器，遵循上述模板
4. 在你拥有或已获授权枚举的域名上测试
5. 提交包含清晰描述的拉取请求
错误报告 → [提交问题](https://github.com/bidhata/SubGrab/issues)
## 📄 许可证
[MIT 许可证](LICENSE.txt) — 可自由使用、修改和分发。
由 [Krishnendu Paul](https://www.linkedin.com/in/krishpaul/) 制作 · [@bidhata](https://github.com/bidhata)
⭐ 如果对你有帮助，请给此仓库加星
标签：50+ 服务, AI 辅助枚举, Ask搜索, C2日志可视化, CLI 工具, CommonCrawl, DNS 数据库, GitHub 代码搜索, Grok API, GUI 工具, HTTPS 探测, HTTP 探测, MIT 许可, OpenRouter API, Shodan IP 关联, SMTP, SSH, VirusTotal, Wayback Machine, Windows 二进制, 主动探测, 传统源完成后运行, 免费信用, 反汇编, 域名侦查, 多线程扫描, 子域名扫描, 子域名接管检测, 子域名枚举, 指纹识别, 搜索引擎, 数据统计, 模式分析, 漏洞挖掘, 端口扫描, 系统安全, 被动枚举, 证书透明度, 调试工具, 逆向工具, 通配符 DNS 过滤