botchx86/subspy

# subspy - 高级子域名扫描器 ``` _____ __ __ ____ _____ ____ __ __ / ___// / / // __ )/ ___/ / __ \\ \ / / \__ \/ / / // __ |\__ \ / /_/ / \ \_/ / ___/ / /_/ // /_/ /___/ / / ____/ \ / /____/\____//_____//____(_)/_/ |_| ``` subspy 是一款高性能的 Python 工，旨在通过基于字典的枚举发现给定域名的活动子域名。 **当前版本：1.1** ## 功能 ### 核心扫描 - **DNS 优先解析：** 在发送 HTTP 请求前先检查 DNS，可提升 5-10 倍的速度 - **DNS 缓存：** 共享且缓存的解析器会重用查询记录并遵循 `--timeout` 设置 - **多线程并发：** 具备可配置线程数的多线程扫描（默认：10 个线程），每个线程均会重用持久的 HTTP 连接 - **进度条：** 使用 tqdm 显示实时进度指示 - **泛解析检测与过滤：** 自动检测泛解析 DNS，并自动排除那些仅仅匹配到泛解析 IP 的结果 - **智能协议检测：** 优先尝试 HTTPS，若 HTTPS 成功则跳过 HTTP - **准确的状态码：** 不自动跟随重定向，因此报告的状态码直接反映子域名本身，而非其重定向的最终目标 - **IPv4 + IPv6：** 同时检查 A 和 AAAA 记录，因此也能发现仅支持 IPv6 的子域名 ### 高级功能 - **恢复支持：** 保存进度并恢复中断的扫描，包括中断前已经找到的结果 - **多种输出格式：** 将结果导出为 TXT、JSON 或 CSV 格式 - **可配置状态码：** 指定将哪些 HTTP 状态码视为“已找到” - **纯 DNS 模式：** 无需 HTTP 请求的快速 DNS 枚举 - **速率限制：** 可配置的请求间延迟 - **自动重试：** 对于临时性错误（429/500/502/503/504），在将其计为未命中之前，会自动进行带退避机制的重试 - **增强的错误处理：** 专门针对超时、连接错误和 DNS 故障进行处理 ### 用户体验 - **详细模式：** 输出详细信息，用于调试和监控 - **静默模式：** 仅输出发现的子域名的最简输出 - **彩色输出：** 易读的终端彩色输出，并提供 `--no-color` 选项 - **统计摘要：** 详细的扫描统计数据，包括速度和成功率 - **User-Agent 标头：** 使用浏览器的 User-Agent 以获得更好的兼容性 - **超时控制：** 可配置的请求超时时间 - **防止重复：** 自动防止出现重复结果 ## 选项 ### 必选参数 ``` -u URL, --url URL Specify the domain to scan for subdomains -w WORDLIST, --wordlist Path to wordlist file ``` ### 可选参数 ``` -h, --help Show this help message and exit -v, --verbose Enable verbose output -q, --quiet Quiet mode - only output found subdomains -t TIMEOUT, --timeout Request timeout in seconds (Default: 5) -o OUTPUT, --output Output file path -d DELAY, --delay Delay between requests in seconds (Default: 0) --threads THREADS Number of concurrent threads (Default: 10) --status-codes CODES Comma-separated status codes to consider found (Default: 200,301,302,403) --dns-only Only perform DNS resolution, skip HTTP requests --resume Resume a previously interrupted scan --format {txt,json,csv} Output format (Default: txt) --no-color Disable colored output --version Show version and exit ``` ## 环境要求 - Python 3.8 或更高版本 - `requests` - 用于发送请求的 HTTP 库 - `dnspython` - DNS 解析工具包 - `tqdm` - 进度条库 - `colorama` - 跨平台彩色终端输出 - `urllib3` - 为临时性 HTTP 错误提供重试/退避支持 ## 安装说明 1. 克隆此仓库： git clone https://github.com/botchx86/subspy.git cd subspy 2. 安装依赖项： pip install -r requirements.txt 或者将其作为包安装（会在您的 PATH 中添加 `subspy` 命令）： pip install . subspy -u example.com -w wordlist.txt ## 快速开始 ``` # 基础扫描 python subs.py -u example.com -w wordlist.txt # 使用 20 个线程的快速并发扫描 python subs.py -u example.com -w wordlist.txt --threads 20 # 仅 DNS 枚举（最快） python subs.py -u example.com -w wordlist.txt --dns-only --threads 50 ``` ## 用法 ### 基础扫描 ``` python subs.py -u example.com -w wordlist.txt ``` ### 快速纯 DNS 扫描 ``` python subs.py -u example.com -w wordlist.txt --dns-only ``` ### 高速并发扫描 ``` python subs.py -u example.com -w wordlist.txt --threads 50 ``` ### 以 JSON 格式保存结果 ``` python subs.py -u example.com -w wordlist.txt -o results.json --format json ``` ### 自定义状态码 ``` python subs.py -u example.com -w wordlist.txt --status-codes 200,201,301,302,401,403 ``` ### 恢复中断的扫描 ``` python subs.py -u example.com -w wordlist.txt --resume ``` ### 带有进度条的详细输出 ``` python subs.py -u example.com -w wordlist.txt -v ``` ### 用于管道操作的静默模式 ``` python subs.py -u example.com -w wordlist.txt --quiet -o results.txt ``` ### 禁用彩色输出 ``` python subs.py -u example.com -w wordlist.txt --no-color ``` ## 性能提示 - **使用纯 DNS 模式** (`--dns-only`) 进行初步侦察 - 速度提升 10 倍 - **增加线程数** (`--threads 50`) 以便在良好的网络连接下实现更快扫描 - **减少延迟** (`--delay 0`) 在扫描您自己的基础架构时使用 - **使用恢复功能** (`--resume`) 处理可能需要耗费数小时的大型字典 - **从小型字典开始** 在使用大型列表前先测试配置 ## 输出格式 ### 文本（默认） ``` https://api.example.com (status code: 200) https://www.example.com (status code: 200) ``` ### JSON ``` [ { "subdomain": "api.example.com", "scheme": "https", "status_code": 200, "ip_addresses": ["93.184.216.34"], "url": "https://api.example.com" } ] ``` ### CSV ``` subdomain,scheme,status_code,ip_addresses,url api.example.com,https,200,"['93.184.216.34']",https://api.example.com ``` ## 高级特性 ### 泛解析检测 该工具会自动检测将所有子域名都解析到同一地址的泛解析 DNS 配置，并过滤掉那些仅仅解析到泛解析 IP 的结果： ``` [WARNING] Wildcard DNS detected on example.com. Matching results will be filtered. ``` ### 恢复功能 当使用 `--resume` 时，进度会每扫描 50 个子域名自动保存一次： ``` [*] Resuming scan - 450 subdomains already checked ``` ### 线程安全操作 所有扫描操作都是线程安全的，允许在高并发情况下不出现数据损坏。 ## 故障排除 **问题：** 扫描速度慢 **解决方案：** 增加线程数 (`--threads 50`) 或使用纯 DNS 模式 **问题：** 被目标封禁 **解决方案：** 减少线程数，增加延迟 (`--delay 1`) **问题：** 误报过多 **解决方案：** 检查是否存在泛解析 DNS 警告，调整状态码 **问题：** 扫描中断 **解决方案：** 使用 `--resume` 标志从上次中断的地方继续 **问题：** 安装后出现导入错误 **解决方案：** 确保您使用的是 Python 3.7+ 并重新安装：`pip install -r requirements.txt --force-reinstall` **问题：** DNS 解析失败 **解决方案：** 检查您的网络/DNS 设置，尝试使用其他 DNS 服务器 ## 最佳实践 ### 针对侦察 1. 从纯 DNS 模式开始，以快速识别现有的子域名 2. 搭配高线程数使用大型字典（1万-10万条记录） 3. 将结果导出为 JSON 以便进一步处理 ### 针对 Web 应用测试 1. 使用带有自定义状态码的完整 HTTP 扫描 2. 保持适中的线程数 (10-20) 以避免触发速率限制 3. 启用详细模式以调试特定的子域名 4. 对于非常庞大的字典使用恢复功能 ### 针对生产环境 1. 使用最小的延迟 (`--delay 0.1`) 进行常规合规的扫描 2. 导出为 CSV 用于生成报告 3. 为长时间运行的扫描启用恢复功能 4. 注意监控泛解析警告 ## 与其他工具的对比 | 功能 | subspy | subfinder | amass | sublist3r | |---------|--------|-----------|-------|-----------| | DNS 优先解析 | ✅ | ✅ | ✅ | ❌ | | 多线程并发 | ✅ | ✅ | ✅ | ❌ | | 进度条 | ✅ | ❌ | ❌ | ❌ | | 泛解析检测 | ✅ | ✅ | ✅ | ❌ | | 恢复功能 | ✅ | ❌ | ❌ | ❌ | | 多种输出格式 | ✅ | ✅ | ✅ | ❌ | | 自定义状态码 | ✅ | ❌ | ❌ | ❌ | | 纯 DNS 模式 | ✅ | ✅ | ❌ | ❌ | ## 开发说明 安装开发依赖并运行测试套件： ``` pip install -r requirements-dev.txt pytest ``` 每次提交代码和 PR 时，CI 都会通过 GitHub Actions 在 Python 3.9、3.11 和 3.12 上运行相同的测试套件。 ### 发布到 PyPI 发布 GitHub release 会触发 `.github/workflows/release.yml`，该工作流会通过 PyPI 的可信发布机制 (OIDC) 构建并上传包 — 无需存储 API token。这需要在 PyPI 上进行一次性设置：将此仓库添加为 `subspy` 项目的可信发布者，使用工作流名称 `release.yml` 和环境 `pypi`。 ## 安全 有关如何报告 subspy 本身的漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 本项目基于 MIT 许可证授权 - 详情请参阅 LICENSE 文件。 ## 更新日志 ### 1.1 - 不再自动跟随重定向，因此 `--status-codes` (如 301/302) 现在反映的是子域名的实际响应，而不是最终的重定向目标 - 泛解析 DNS 结果现在会被过滤掉，而不仅仅是触发警告 - `--timeout` 现在也适用于 DNS 查询，而不仅仅是 HTTP 请求 - DNS 解析会被缓存，且 HTTP 连接会按线程重用，从而加快扫描速度 - 域名输入会根据主机名模式进行验证，而不是草率的“包含点”检查 - 输出文件会以明确的 UTF-8 编码写入 - 添加了 `--version` 标志，并对 `--threads`、`--timeout`、`--delay` 进行了输入验证 - 在 `requirements.txt` 中锁定了最低依赖版本 - `--resume` 现在也会恢复在中断前找到的结果，而不仅仅是跳过已扫描的条目 - 带有下划线的字典条目（例如 `_dmarc`）不再被作为无效条目而静默丢弃 - 为临时性 HTTP 错误 (429/500/502/503/504) 添加了带退避机制的重试 - 在 A 记录之外，增加了 AAAA (IPv6) 查询 - 增加了打包配置 (`pyproject.toml`)，以便通过 `pip install .` 安装并提供 `subspy` 命令行工具 - 增加了 pytest 测试套件（包括模拟的扫描逻辑测试）和 GitHub Actions CI - 增加了 PyPI 发布工作流和 SECURITY.md 文件 - 修复了未使用的 `delay=0.5` 默认值，该值以前从未与 CLI 实际的默认值 `0` 匹配 ## 免责声明 本工具仅用于教育和授权的安全测试目的。用户需自行遵守适用的法律法规。在对您不拥有或未获得明确测试权限的系统进行扫描之前，请务必获得适当的授权。 ## 作者 **botchx86** 如有任何问题、疑问或功能请求，请在 GitHub 上提交 issue。

标签：DNS解析, Python, 域名侦查, 子域名扫描, 开源项目, 无后门, 逆向工具