bastian-red/osintrecon

# osintrecon 一款针对域名的轻量级、模块化 **OSINT 侦察工具**。它从多个来源收集公开信息，对结果进行去重和合并，并生成一份统一的 **HTML** 和 **JSON** 报告。 它展示了多 API 集成、并发自动化、优雅的错误处理以及报告生成功能。 ``` DNS ─┐ WHOIS─┤ crt.sh┼─► aggregator (concurrent, dedup, error isolation) ─► HTML + JSON report VT ─┤ Shodan─┘ ``` ## ⚠️ 使用范围与法律声明 本项目仅供**授权与教育用途**。请**仅对你拥有或已获得明确书面测试许可的域名**运行此工具。它收集的所有数据均为公开数据（DNS、WHOIS、证书透明度日志以及第三方 API 索引），但在你所在的司法管辖区内，对你无法控制的系统进行自动化侦察仍可能构成违法行为。你需对自己的使用方式负责。本项目不提供任何担保。 ## 功能 - **子域名枚举**：从证书透明度 和 VirusTotal 获取，合并并去重，同时保留各来源的归属信息。 - **DNS 记录**：A、AAAA、MX、NS、TXT、CNAME、SOA（通过 `dnspython`）。 - **WHOIS**：注册商、关键日期、域名服务器、邮箱、状态。 - **证书透明度**：来自 crt.sh 的证书元数据。 - **Shodan 主机数据**：开放端口、组织、OS、已知漏洞（可选，需提供 API key）。 - **可选的存活解析**（`--resolve`）：为每个发现的子域名解析 A 记录。 - **统一报告**：自包含的 HTML（无外部资源）+ 机器可读的 JSON。 - **设计健壮**：并发执行各数据源，且绝不会中止运行；失败或缺少 API key 的数据源会被记录为错误/跳过，其余部分将继续执行。 ## 架构 每个数据源对应一个模块，外加一个聚合器和一个报告生成器（如项目简介所建议）： ``` osintrecon/ cli.py # Typer + Rich command-line interface config.py # env / .env loading, API keys, source toggles models.py # dataclasses + JSON serialization aggregator.py # concurrent orchestration, merge + dedup sources/ base.py # Source contract; turns exceptions into SourceErrors dns_records.py # dnspython whois_lookup.py # python-whois (normalizes loose return shapes) crtsh.py # crt.sh certificate transparency JSON virustotal.py # VirusTotal API v3 subdomains (key-gated, paginated) shodan_host.py # Shodan host lookups (key-gated) subdomains.py # optional concurrent A-record liveness resolution report/ html_report.py # Jinja2 render + JSON writer templates/report.html.j2 tests/ # pytest suite, fully mocked (no network) ``` 每个数据源都实现相同的 `Source` 契约并返回一个 `SourceResult`。基类包装了 `collect()`，因此任何异常都会转换为 `SourceError`，而不会导致程序崩溃（优雅降级）。聚合器在线程池中运行各数据源，合并它们的部分结果，并对由多个数据源发现的子域名取 `sources` 集合的并集。 ## 安装说明 要求 Python 3.9+。 ``` python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 用于开发 / 运行测试： pip install -r requirements-dev.txt ``` 或者将其作为包安装（提供 `osintrecon` 控制台命令）： ``` pip install -e . ``` ## 配置 两个需要 API key 的数据源（VirusTotal 和 Shodan）是可选的。如果没有提供 key，它们将被干净地**跳过**（记录为 `skipped`，而不是错误）。要启用它们，请将 `.env.example` 复制为 `.env` 并填写： ``` VIRUSTOTAL_API_KEY=your_key_here SHODAN_API_KEY=your_key_here ``` API key 也可以作为普通环境变量传入。 ## 用法 ``` # Full run，将 HTML + JSON 输出到 ./out（默认） osintrecon recon example.com # 选择输出目录和格式；解析 subdomain IP osintrecon recon example.com -o ./reports -f html,json --resolve # 禁用特定来源 osintrecon recon example.com --no-shodan --no-vt --no-whois # 或者不安装 console script： python -m osintrecon recon example.com ``` 选项： | 选项 | 描述 | | ------------------- | --------------------------------------------------- | | `-o, --output DIR` | 报告文件的输出目录（默认为 `out`）。 | | `-f, --format LIST` | 以逗号分隔的格式列表：`html`、`json`。 | | `--resolve` | 为每个发现的子域名解析 A 记录。 | | `--no-vt` | 禁用 VirusTotal 数据源。 | | `--no-shodan` | 禁用 Shodan 数据源。 | | `--no-whois` | 禁用 WHOIS 数据源。 | | `--version` | 打印版本号并退出。 | ### 示例输出 程序会打印控制台摘要，并将报告写入磁盘。请参阅 [`samples/example.com.html`](samples/example.com.html) 和 [`samples/example.com.json`](samples/example.com.json) 查看针对 `example.com` 的实际运行情况（跳过了 VirusTotal/Shodan，未配置 API key）。 ``` Recon summary: example.com DNS A records 2 WHOIS registrar RESERVED-Internet Assigned ... Subdomains 6 Certificates 69 Shodan hosts 0 Errors 0 Skipped sources 2 ``` ## 开发 ``` pip install -r requirements-dev.txt pytest ``` 测试套件模拟了所有网络访问（HTTP 使用 `responses`，解析器/whois 使用 monkeypatch 替换），因此可以离线且确定性地运行。 ## 数据来源 | 来源 | 需要 API key | Endpoint / 库 | | ----------- | ------------ | ----------------------------------------------------- | | DNS | 否 | `dnspython` resolver | | WHOIS | 否 | `python-whois` | | crt.sh | 否 | `https://crt.sh/?q=%.&output=json` | | VirusTotal | 是 | VirusTotal API v3 `/domains//subdomains` | | Shodan | 是 | `shodan` 库 host lookups | ## 许可证 MIT。仅供教育用途；请参阅上述使用范围与法律声明。

标签：GitHub, Python, 子域名枚举, 安全规则引擎, 无后门, 系统安全, 进程管理, 逆向工具