keyuraghao/SubHunter

## 演示 ``` ____ _ _ _ _ / ___| _ _| |__ | | | |_ _ _ __ | |_ ___ _ __ \___ \| | | | '_ \| |_| | | | | '_ \| __/ _ \ '__| ___) | |_| | |_) | _ | |_| | | | | || __/ | |____/ \__,_|_.__/|_| |_|\__,_|_| |_|\__\___|_| [*] Loaded 3 domain(s). Source Status ───────────────────────── VirusTotal ENABLED crt.sh ENABLED GitHub ENABLED Sublist3r ENABLED Shodan DISABLED [*] Starting parallel subdomain enumeration... Enumerating ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:18 [+] Discovered 247 unique subdomains. [*] Resolving 247 subdomains via C++ DNS resolver... [+] DNS resolution complete: 193 alive / 54 dead. Hostname IP Address Alive Latency ───────────────────────────────────────────────────────────── api.example.com 1.2.3.4 YES 8 ms dev.example.com 1.2.3.5 YES 11 ms staging.example.com - NO - ... [+] Nuclei scan completed. [+] HTML report written to: Reports/report.html ╭─────────────────── Scan Complete ──────────────────────╮ │ Total subdomains: 247 │ │ Alive (DNS): 193 │ │ Nuclei findings: 12 │ │ HTML report: Reports/report.html │ ╰──────────────────────────────────────────────────────────╯ ``` ## 架构 SubHunter 有意 **拆分为 Python + C++**，以便在各自擅长的领域使用它们： ``` ┌─────────────────────────────────────────────────────────┐ │ subhunter.py (entry point) │ └───────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────▼─────────────────────────────────┐ │ subhunter/cli.py │ │ (argument parsing + pipeline orchestration) │ └──┬────────────┬──────────────┬──────────────┬───────────┘ │ │ │ │ ▼ ▼ ▼ ▼ Enumerators Resolvers Output AI (Python) (C++ / Py) (Python) (Python) │ │ │ │ │ ┌──────┴───────┐ ┌───┴────────┐ │ │ │ C++ binary │ │ terminal │ │ │ │ dns_resolver │ │ html_report│ │ │ └──────────────┘ └────────────┘ │ │ │ ▼ ▼ 5 OSINT sources Claude / GPT-4o VT · crt.sh · GitHub via official SDKs Sublist3r · Shodan ``` | 层 | 语言 | 原因 | |---|---|---| | OSINT 查询 | Python | 丰富的 HTTP / 解析生态系统 | | DNS 解析 | **C++17** | `getaddrinfo` + `std::thread` - 数秒内处理数千个主机 | | Nuclei 包装器 | Python | `subprocess` + CSV 解析 | | HTML / AI 输出 | Python | 模板生成，AI SDK 调用 | | CLI 编排 | Python | `argparse`, `concurrent.futures`, `rich` | ## 目录结构 ``` SubHunter/ ├── subhunter.py ← entry-point shim ├── pyproject.toml ← packaging + tool config (ruff, mypy, pytest) ├── requirements.txt ← pinned runtime deps ├── Makefile ← make build / test / lint / clean ├── build.sh ← one-command C++ build ├── LICENSE ├── CHANGELOG.md ├── CONTRIBUTING.md ├── SECURITY.md │ ├── resolver/ ← C++ DNS resolver │ ├── dns_resolver.cpp ← multi-threaded resolver source │ └── Makefile │ ├── subhunter/ ← Python package │ ├── __init__.py │ ├── __main__.py ← enables `python -m subhunter` │ ├── py.typed ← PEP 561 marker │ ├── cli.py ← pipeline orchestration + all CLI flags │ ├── enumerators/ ← one file = one OSINT source │ │ ├── virustotal.py │ │ ├── crtsh.py │ │ ├── github.py │ │ ├── sublister.py │ │ └── shodan.py │ ├── resolvers/ │ │ └── dns_resolver.py ← wraps C++ binary; auto-builds; Python fallback │ ├── scanners/ │ │ └── nuclei.py ← runner + CSV parser │ ├── output/ │ │ ├── terminal.py ← Rich tables, panels, progress │ │ └── html_report.py ← standalone HTML report generator │ ├── ai/ │ │ └── analyzer.py ← Claude + OpenAI integrations │ └── utils/ │ └── helpers.py ← shared I/O + normalisation │ ├── tests/ ← pytest suite (42 tests, no network required) │ ├── conftest.py │ ├── test_helpers.py │ ├── test_nuclei_parser.py │ ├── test_resolver.py │ └── test_html_report.py │ └── .github/ ├── workflows/ci.yml ← CI: C++ build (Linux+macOS), Python 3.9–3.13, lint ├── ISSUE_TEMPLATE/ └── PULL_REQUEST_TEMPLATE.md ``` ## 安装 ### 前置条件 | 工具 | 必需 | 说明 | |---|---|---| | Python ≥ 3.9 | 是 | `python3 --version` | | g++ (C++17) | 是 | 在 Debian/Kali 上执行 `sudo apt install g++ make` | | Nuclei | 可选 | 用于漏洞扫描 | | Sublist3r | 可选 | 用于额外枚举 | ### 快速开始 ``` # 1. Clone git clone https://github.com/Keyur-Aghao/SubHunter.git cd SubHunter # 2. 安装 Python deps pip install -r requirements.txt # 3. 构建 C++ DNS resolver bash build.sh # 4. （可选）作为 package 安装，并使用 `subhunter` CLI 命令 pip install -e . ``` ### 开发安装（包含测试、Linting、类型检查） ``` make dev-install # pip install -e ".[all]" + build.sh ``` ### 外部工具 ``` pip install sublist3r # Sublist3r go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Nuclei ``` ## 配置 SubHunter 从文件或环境变量读取 API 凭证。**切勿提交密钥。** ### VirusTotal - `vt_keys.csv` ``` APIKEY,Remaining YOUR_VT_KEY_HERE,500 ``` ### GitHub - `.tokens` ``` ghp_xxxxxxxxxxxxxxxxxxxx ghp_yyyyyyyyyyyyyyyyyy ``` 或者：`export GITHUB_TOKEN=ghp_xxxxx`（令牌在达到速率限制时自动轮换） ### Shodan ``` export SHODAN_API_KEY=your_key # 或：--shodan-key YOUR_KEY ``` ### AI 提供商 ``` export ANTHROPIC_API_KEY=sk-ant-xxxxx # Claude (default) export OPENAI_API_KEY=sk-xxxxx # OpenAI (alternative) ``` ## 用法 ### 基础 - 枚举子域名 ``` python subhunter.py -i domain_list.txt ``` ### DNS 解析 + HTML 报告 ``` python subhunter.py -i domain_list.txt --html -o Reports/ ``` ### 完整流水线 ``` python subhunter.py \ -i domain_list.txt \ --html \ --nuclei \ --ai \ --ai-provider claude \ -o Reports/scan_$(date +%F) ``` ### 仅 crt.sh（无需 API 密钥） ``` python subhunter.py -i domains.txt \ --disable-vt --disable-github --disable-sublister --disable-shodan ``` ### JSON 输出 ``` python subhunter.py -i domains.txt --format json | jq '.subdomains[]' ``` ### OpenAI 分析（覆盖模型） ``` python subhunter.py -i domains.txt --ai --ai-provider openai --ai-model gpt-4o-mini ``` ### 通过已安装的包运行 ``` subhunter -i domains.txt --html --ai python -m subhunter -i domains.txt --html --ai ``` ## CLI 参考 ### 输入 / 输出 | 标志 | 默认值 | 描述 | |---|---|---| | `-i`, `--input-domains` | `domain_list.txt` | 根域文件（每行一个） | | `-o`, `--output-dir` | `Outputs` | 所有输出文件存放目录 | | `--format` | `terminal` | `terminal` \| `json` \| `both` | | `--html` | 关闭 | 生成独立 HTML 报告 | ### API 凭证 | 标志 | 默认值 | 描述 | |---|---|---| | `--vt-keys` | `vt_keys.csv` | VirusTotal 密钥 CSV | | `--github-tokens-file` | `.tokens` | GitHub 令牌（每行一个） | | `--shodan-key` | 环境变量 | Shodan API 密钥 | ### 枚举来源 | 标志 | 描述 | |---|---| | `--disable-vt` | 禁用 VirusTotal | | `--disable-crtsh` | 禁用 crt.sh | | `--disable-github` | 禁用 GitHub 代码搜索 | | `--disable-sublister` | 禁用 Sublist3r | | `--disable-shodan` | 禁用 Shodan | ### DNS 解析（C++ 解析器） | 标志 | 默认值 | 描述 | |---|---|---| | `--no-resolve` | 关闭 | 跳过 DNS 解析 | | `--resolve-threads` | `100` | C++ 二进制文件中的并行线程数 | | `--resolve-timeout` | `3` | 每个主机名的超时时间（秒） | ### Nuclei | 标志 | 默认值 | 描述 | |---|---|---| | `--nuclei` | 关闭 | 枚举后运行 Nuclei | | `--nuclei-templates` | 内置 | 自定义模板路径 | | `--no-nuclei-csv` | 关闭 | 跳过 CSV 解析 | ### AI 分析 | 标志 | 默认值 | 描述 | |---|---|---| | `--ai` | 关闭 | 运行 AI 安全分析 | | `--ai-provider` | `claude` | `claude` 或 `openai` | | `--ai-key` | 环境变量 | API 密钥覆盖 | | `--ai-model` | 提供商默认 | 例如 `claude-opus-4-6`, `gpt-4o` | ### 性能 | 标志 | 默认值 | 描述 | |---|---|---| | `-w`, `--workers` | `8` | 枚举工作线程数 | | `--timeout` | `15` | HTTP 超时时间（秒） | | `-v`, `--verbose` | 关闭 | 调试日志 | ## 输出文件 所有文件都写入 `--output-dir`（默认为 `Outputs/`）： | 文件 | 内容 | |---|---| | `subdomains.txt` | 所有发现的子域名的排序列表 | | `dns_results.json` | DNS 解析结果（主机名、IP、存活状态、延迟） | | `nuclei_raw.txt` | 原始 Nuclei 输出 | | `nuclei_parsed.csv` | 按严重程度排序的 Nuclei 发现 | | `ai_analysis.md` | Markdown 格式的 AI 分析 | | `report.html` | 自包含的 HTML 安全报告 | ## C++ DNS 解析器 位于 [resolver/dns_resolver.cpp](resolver/dns_resolver.cpp) 的解析器使用： - **POSIX `getaddrinfo`** 进行 DNS 解析（IPv4 + IPv6） - **`std::thread`** 实现并行（最多 500 个线程） - **JSON 输出** 到 stdout - 由 Python 包装器使用 位于 [subhunter/resolvers/dns_resolver.py](subhunter/resolvers/dns_resolver.py) 的 Python 包装器： 1. 检查二进制文件是否存在 2. 如果未找到，则通过 `make` 自动构建 3. 如果编译失败，则回退到 Python 的 `socket.getaddrinfo` ``` # 直接使用 echo -e "google.com\nexample.com" | ./resolver/dns_resolver -t 50 -timeout 3 ``` ``` [ {"hostname":"example.com","ip":"93.184.216.34","alive":true,"latency_ms":12.4}, {"hostname":"google.com","ip":"142.250.185.78","alive":true,"latency_ms":8.1} ] ``` ## AI 分析 AI 模块（[subhunter/ai/analyzer.py](subhunter/ai/analyzer.py）向所选模型发送结构化的安全提示词，涵盖所有发现的子域名、DNS 结果和 Nuclei 发现。 AI 返回包含六个部分的 Markdown 报告： 1. **攻击面摘要** - 子域名数量、命名模式、基础设施推断 2. **高优先级目标** - 最有趣的存活主机及其原因 3. **漏洞分析** - 每个发现的风险、影响和 CVSS 背景 4. **攻击链** - 多步利用路径 5. **建议的后续步骤** - 优先级排序的修复清单 6. **OSINT 备注** - 技术栈和运营推断 | 提供商 | 默认模型 | 环境变量 | |---|---|---| | `claude` (默认) | `claude-opus-4-6` | `ANTHROPIC_API_KEY` | | `openai` | `gpt-4o` | `OPENAI_API_KEY` | ## 测试 ``` make test # full suite with coverage make test-fast # stop on first failure ``` 该套件（42 个测试）**不需要网络访问**，也**不需要 API 密钥** —— 所有外部调用均已模拟。 ``` tests/test_helpers.py 12 tests - normalize, write_list tests/test_nuclei_parser.py 12 tests - parser, severity sorting, CSV output tests/test_resolver.py 7 tests - Python DNS fallback (mocked socket) tests/test_html_report.py 11 tests - HTML generation, content, no-CDN guarantee ``` ## 添加新来源 1. 创建 `subhunter/enumerators/mysource.py`，包含单个 `enumerate(domain, ...) -> Set[str]` 函数 2. 在 `cli.py` 中连接 `--disable-mysource` 标志和 `flags["mysource"]` 3. 在 `tests/test_enumerators.py` 中编写测试 完整指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 法律声明 SubHunter **专供** 授权的安全测试、Bug Bounty 计划、CTF 竞赛和教育用途使用。仅扫描您拥有或拥有 **明确书面许可** 进行测试的域名。未经授权的扫描可能违反您所在司法管辖区的计算机欺诈法律。

标签：AI安全分析, Ask搜索, C++, Claude, Cli工具, CVE检测, DNS解析, ESC4, Github, GitHub, Google, GPT-4o, HTML报告, Nuclei, OSINT, Petitpotam, Python, VirusTotal, 企业级安全, 域名安全, 子域名接管, 子域名枚举, 安全测试, 密码管理, 开源情报收集, 开源项目, 插件系统, 攻击性安全, 数据擦除, 数据统计, 无后门, 端口扫描, 系统安全, 自动化渗透测试, 逆向工具