vishnujchandran/subscope

# subscope `subscope` 是一个用于被动子域名枚举的 Python CLI。 它封装了常见的外部工具，合并它们的输出，对结果进行标准化，并生成清晰的报告。 ## 快速开始 ``` python -m venv .venv source .venv/bin/activate python -m pip install -e .[dev] python -m subscope --domain example.com --out ./output --json ``` ## 功能 - 接受目标域名和输出目录 - 封装已安装的被动工具： - `subfinder` - `assetfinder` - `amass`（被动模式） - 优雅地跳过缺失的工具并发出警告 - 标准化输出（去除 `*.` 前缀，转换为小写） - 验证发现的域名 - 对结果进行去重和排序 - 生成： - `subdomains.txt` - `stats.md` - 通过 `--json` 可选生成的 `stats.json` - 结构化日志，每次运行包含专属的 correlation ID（`run_id`） - 通过 `--workers` 并发执行工具 - 原子化输出写入，避免产生不完整的文件 - 解析每个工具的绝对二进制路径，以提供更清晰的执行来源 - 限制 subprocess 输出捕获，以避免内存无限增长 - Dashboard 绑定安全防护（远程绑定需要显式同意） ## 安装说明 ### 1) 克隆仓库 ``` git clone git@github.com:vishnujchandran/subscope.git cd subscope ``` ### 2) 创建并激活虚拟环境（推荐） ``` python -m venv .venv source .venv/bin/activate ``` ### 3) 安装包和开发依赖 ``` python -m pip install --upgrade pip setuptools wheel python -m pip install -e .[dev] ``` ### 4) 外部工具前置条件（可选但推荐） 安装以下一个或多个工具： - `subfinder` - `assetfinder` - `amass` 如果某个工具未安装，`subscope` 将自动跳过它。 #### Kali/Linux 快速安装 ``` sudo apt update sudo apt install -y golang-go amass go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest go install github.com/tomnomnom/assetfinder@latest ``` #### 将 Go 工具添加到 PATH（重要） 使用当前 shell 的配置文件： ``` # bash 用户 echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc source ~/.bashrc # zsh 用户 echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.zshrc source ~/.zshrc ``` ## 命令 ``` # 运行测试 pytest # Lint / type / security 检查 ruff check . mypy subscope bandit -q -r subscope pip-audit # 作为 module 运行 python -m subscope --domain example.com --out ./output # 运行已安装的 script subscope --domain example.com --out ./output ``` ## 用法 ### 模块执行 ``` python -m subscope --domain example.com --out ./output ``` ### 脚本入口点 ``` subscope --domain example.com --out ./output ``` ### 额外示例 ``` # 仅使用选定的工具 python -m subscope --domain example.com --tools subfinder,assetfinder # 将每个工具的 timeout 提高到 180s python -m subscope --domain example.com --timeout 180 # 同时输出 JSON stats python -m subscope --domain example.com --json # 并行运行工具（默认 workers=3） python -m subscope --domain example.com --workers 3 # 运行后通过 HTTP 提供本地 dashboard python -m subscope --domain example.com --json --serve-dashboard --host 127.0.0.1 --port 8000 # Remote dashboard 绑定（明确 opt-in） python -m subscope --domain example.com --serve-dashboard --host 0.0.0.0 --allow-remote-dashboard # Debug logging python -m subscope --domain example.com --debug ``` ## 输出格式 使用 `--out ./output` 时，文件将写入按域名和每次运行划分的目录中： - `./output///subdomains.txt` — 排序且去重的域名 - `./output///stats.md` — Markdown 摘要（包含 run ID、状态、工具明细） - `./output///stats.json` — 可选的机器可读统计信息（包含 `run_id` 和运行 `status`） - `./output//latest/*` — 最近一次运行的快照，便于快速访问 - `./output//runs.jsonl` — 仅追加的运行历史记录，用于分析 - `./output//dashboard.html` — 根据运行历史自动生成的本地 Dashboard 如果启用了 `--serve-dashboard`，可通过以下地址浏览 Dashboard： - `http://127.0.0.1:8000//dashboard.html` 运行状态： - `success`：所有选定的工具均执行成功 - `partial`：至少有一个选定的工具执行成功 - `failure`：没有选定的工具执行成功 每次执行都会生成一个新的 `run_id`，因此之前的运行输出不会被覆盖。 ## 故障排除 ### 未返回任何结果 - 检查目标域名是否正确。 - 确认至少安装并正常运行了一个受支持的工具。 - 尝试使用 `--debug` 来检查工具的命令执行行为。 ### 工具未找到警告 如果工具未安装，这是预期行为。警告示例： - `tool=subfinder status=skipped reason=not_installed` 请安装缺失的二进制文件并重试。 验证工具路径： ``` which subfinder which assetfinder which amass ``` 如果已安装但仍未找到，请确保 `$HOME/go/bin` 位于正确的 shell 配置文件中（bash 对应 `~/.bashrc`，zsh 对应 `~/.zshrc`），然后运行： ``` hash -r ``` ### 写入输出时出现权限错误 请使用 `--out` 指定一个可写路径，例如 `--out ./output`。 ### 拒绝远程 Dashboard 绑定 默认情况下，`--serve-dashboard` 仅允许本地绑定目标（`127.0.0.1`、`localhost`、`::1`）。 如果您确实需要远程访问，请传入 `--allow-remote-dashboard`。 ### 事件处理 在 `docs/runbook.md` 中提供了一个基础的操作手册。 发布说明位于 `docs/release.md`。 ## 路线图 - 基于解析器的可选主动验证模式 - 输出格式插件（CSV/NDJSON） - 工具适配器接口，便于扩展 - 针对不稳定工具执行的重试/退避策略 ## 法律免责声明 ## 许可证 MIT

标签：GitHub, Python, 任务编排, 子域名枚举, 实时处理, 文档结构分析, 无后门, 系统安全, 逆向工具