0xCatmeat/osint-recon

# osint-recon 一款命令行 OSINT 工具，能够同时从多个数据源拉取目标证据，将所有内容归一化为统一的 schema，并为您生成整洁的报告。只需提供一个 domain、IP、URL、file hash 或 EVM address，它便会分发给 Shodan、VirusTotal、crt.sh、RDAP、urlscan 以及任何您拥有 API key 的服务，然后返回清晰易读的 Markdown 报告。 它专为那些日后可能需要重复执行或提供支持的调查工作而设计，因此每次运行都会保留原始的 provider JSON 数据、归一化后的结果、来源 URL、时间戳、cache 元数据以及任何错误信息。任何数据都不会被丢弃，您可以在事后无需再次查询任何 provider 的情况下重建报告。 其主要功能依赖于被动 API 查询。少数可选的 provider 会调用本地工具直接与目标进行交互。这些工具仅在您传入 `--active` 参数时才会运行，因此常规运行绝不会探测目标本身。 ## 目录 - [功能概述](#what-you-get) - [环境要求](#requirements) - [下载](#download) - [安装](#install) - [API key](#api-keys) - [快速开始](#quick-start) - [Provider](#providers) - [命令](#commands) - [Enrich 标志](#enrich-flags) - [目标类型](#target-types) - [输出](#output) - [Cache](#cache) - [主动探测与 scope gate](#active-probing-and-the-scope-gate) - [重建报告](#rebuilding-reports) - [开发](#development) - [故障排除](#when-something-is-off) ## 功能概述 - **单一目标，多源数据。** 自动检测您输入的是 domain、IP、URL、hash 还是 EVM address，并仅运行适合该目标的 provider。 - **保留所有数据。** 原始响应、归一化的结果、每条结果的来源 URL 以及发现时间，都会统一保存在同一个运行目录中。 - **易读的报告。** 生成一份按 artifact 和 provider 分组的 `summary.md`，以及一份 `sources.md`，方便任何人追溯结果的来源。 - **支持缓存且对速率限制友好。** 响应缓存在 SQLite 中，因此重复运行和独立的命令可以复用数据，而不会消耗 API 配额。 - **默认被动。** 少数本地工具会直接探测目标。除非您传入 `--active` 参数，否则这些工具不会运行，因此常规运行仅执行被动查询。 ## 环境要求 - Python 3.11 或更高版本 - [`uv`](https://docs.astral.sh/uv/) - 您想使用的已配置 API key 的 provider 的 key（均为可选） - 位于 `~/OSINT/bin/` 中的可选本地工具，用于支持依赖二进制程序的 provider 您无需任何 key 即可开始。没有 key 或二进制程序的 provider 会被跳过，因此即使是最基础的安装，您也能免费使用 RDAP 和证书透明度查询。 ## 下载 克隆仓库： ``` git clone https://github.com/0xCatmeat/osint-recon.git cd osint-recon ``` 或者获取 GitHub 归档： ## 安装 使用 `uv` 拉取依赖： ``` uv sync ``` 确保 CLI 可以正常运行： ``` uv run osint-recon --version ``` ## API key key 保存在一个 env 文件中。默认路径为： ``` ~/OSINT/config/apis.env ``` 如果您的 env 文件保存在其他位置，可以使用 `--env PATH` 指定。 ``` mkdir -p ~/OSINT/config cp apis.env.example ~/OSINT/config/apis.env $EDITOR ~/OSINT/config/apis.env chmod 600 ~/OSINT/config/apis.env ``` 它支持的 key 包括： ``` SHODAN_API_KEY=your_key NETLAS_API_KEY=your_key URLSCAN_API_KEY=your_key VIRUSTOTAL_API_KEY=your_key ABUSEIPDB_API_KEY=your_key ETHERSCAN_API_KEY=your_key ``` 只需填入您实际拥有的 key 即可。留空的项将被跳过。 ## 快速开始 查看哪些 provider 已就绪： ``` uv run osint-recon doctor ``` 添加 `--local` 以同时检查本地工具和文件： ``` uv run osint-recon doctor --local ``` 在实际执行前预览运行计划： ``` uv run osint-recon enrich example.com --dry-run ``` ``` uv run osint-recon enrich example.com --dry-run --no-pivots ``` 正式运行： ``` uv run osint-recon enrich example.com ``` 指定自定义的 env 文件： ``` uv run osint-recon --env ./apis.env enrich example.com ``` 针对 EVM address 运行： ``` uv run osint-recon enrich 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B ``` ## Provider | Provider | Key 或依赖 | 目标类型 | 备注 | |---|---|---|---| | Shodan | `SHODAN_API_KEY` | IP | 主机暴露和 CVE 数据。搜索功能为可选，因为会消耗额度。 | | Netlas | `NETLAS_API_KEY` | IP, domain | 主机、DNS、证书和 WHOIS 数据。 | | urlscan | `URLSCAN_API_KEY` | domain, URL | 现有的 urlscan 结果。 | | VirusTotal | `VIRUSTOTAL_API_KEY` | domain, IP, URL, hash | 信誉和分析统计数据。 | | AbuseIPDB | `ABUSEIPDB_API_KEY` | IP | 滥用置信度评分和报告计数。 | | Etherscan | `ETHERSCAN_API_KEY` | EVM address | Ethereum 主网余额和近期交易记录。 | | RDAP | 无 | domain, IP | 注册数据。 | | crt.sh | 无 | domain | 证书透明度名称。 | | subfinder | `~/OSINT/bin/subfinder` | domain | 通过本地二进制程序被动发现子域名。 | | dnsx | `~/OSINT/bin/dnsx` | domain | 通过本地二进制程序获取 DNS 记录。属于主动探测，需要 `--active`。 | | httpx | `~/OSINT/bin/httpx` | domain | 通过本地二进制程序进行 HTTP 探测。属于主动探测，需要 `--active`。 | | tlsx | `~/OSINT/bin/tlsx` | domain, IP | 通过本地二进制程序获取 TLS 证书数据。属于主动探测，需要 `--active`。 | | gau | `~/OSINT/bin/gau` | domain | 通过本地二进制程序获取历史 URL。 | `doctor --local` 还会对它在 `~/OSINT/bin/` 中发现的其他常见工具进行盘点，例如 `mapcidr`、`gitleaks`、`trufflehog`、`nuclei`、`katana` 和 `uncover`。 ## 命令 | 命令 | 功能 | |---|---| | `doctor` | 检查 API key 和 provider 健康状态。 | | `doctor --local` | 同时检查本地路径和二进制程序。 | | `enrich ` | 针对目标运行 provider 并生成报告目录。 | | `normalize ` | 从存储的原始响应重建 `normalized/findings.jsonl`。 | | `report ` | 重建 `summary.md` 和 `sources.md`。 | | `scope-gate` | 在运行主动工具前记录授权信息。 | ## Enrich 标志 | 标志 | 功能 | |---|---| | `--dry-run` | 显示计划的 artifact 和 provider，而不实际进行查询。Domain pivot 可能仍会解析 DNS。 | | `--json` | 输出机器可读格式。 | | `--out PATH` | 使用自定义的报告目录。 | | `--case-id ID` | 设置您自己的案件 ID。 | | `--no-pivots` | 关闭 domain 到 IP 的扩展。 | | `--max-pivots N` | 限制查询的已解析 IP 数量。默认值：`3`。 | | `--active` | 同时运行直接探测目标的本地工具（dnsx, httpx, tlsx）。默认关闭。 | | `--offline` | 仅使用 provider cache。与 `--no-pivots` 搭配使用可同时跳过 DNS。 | | `--refresh` | 忽略已缓存的响应并重新获取最新数据。 | | `--max-age SECONDS` | 仅接受时间小于指定秒数的 cache。 | | `--shodan-search QUERY` | 运行可选的 Shodan 搜索。消耗一次查询额度。 | ## 目标类型 CLI 会自动为您识别目标类型。 | 类型 | 示例 | |---|---| | `domain` | `example.com` | | `ip` | `8.8.8.8`, `2606:4700:4700::1111` | | `url` | `https://example.com/path` | | `hash` | `d41d8cd98f00b204e9800998ecf8427e` | | `evm_address` | `0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B` | 对于 domain，`enrich` 还会解析最多三个 IP，并针对这些 pivot 运行支持 IP 的 provider。如果您希望仅限于 domain 查询，请使用 `--no-pivots`。 ## 输出 默认情况下，运行结果会保存在： ``` ~/OSINT/reports/// ``` 每次运行包含： ``` raw/ raw provider JSON responses normalized/findings.jsonl one JSON object per normalized finding summary.md readable findings grouped by artifact and provider sources.md source URLs and observation times run-metadata.json target, providers, cache stats, errors, file manifest ``` 运行目录在创建时会进行严格的权限锁定：目录权限为 `700`，文件权限为 `600`。证据仅供您阅读，机器上的其他用户无权访问。 ## Cache Provider 响应会被缓存在： ``` ~/OSINT/.cache/osint-recon.sqlite ``` 这个 cache 能防止您频繁请求相同的 API，并允许速率限制在不同的独立运行之间延续。您可以使用 `--refresh` 绕过它，使用 `--offline` 强制依赖它，或者使用 `--max-age SECONDS` 仅信任近期的缓存记录。 ## 主动探测与 scope gate 大多数 provider 执行的是被动查询，但有三个本地工具会直接与目标交互：dnsx（DNS 解析）、httpx（HTTP 探测）和 tlsx（TLS 探测）。除非您传入 `--active` 参数，否则它们不会运行，因此常规的 `enrich` 绝不会探测目标： ``` uv run osint-recon enrich example.com --active ``` 首先使用 `--dry-run --active` 预览主动运行时会执行的操作，并且仅在您确实拥有授权的情况下才开启该功能。 `scope-gate` 命令用于记录该授权。它是一个审计追踪记录，而不是一个开关。它会写入一条 JSON 记录，表明您已获得授权。它不会为您启用 `--active`，其本身也不会执行任何探测： ``` uv run osint-recon scope-gate \ --target example.com \ --scope-file ./scope.txt \ --authorization-note "Bug bounty scope allows testing this domain" ``` ## 重建报告 如果仍然保留了运行目录？您可以直接从存储的原始响应中重建归一化的结果和 Markdown 报告，而无需调用任何 provider： ``` uv run osint-recon normalize ~/OSINT/reports/example.com/20260606T120000Z uv run osint-recon report ~/OSINT/reports/example.com/20260606T120000Z ``` 这在您更改了报告格式，或者想从旧证据中生成新的 Markdown 报告时非常有用。 ## 开发 运行测试： ``` uv run pytest ``` Lint 和格式化： ``` uv run ruff check . uv run ruff format --check . ``` ## 故障排除 已配置 API key 的 provider 被跳过了？检查它正在读取哪个 env 文件： ``` uv run osint-recon doctor uv run osint-recon --env ./apis.env doctor ``` 本地二进制 provider 运行失败？确保这些工具存在且具有可执行权限： ``` uv run osint-recon doctor --local ls -l ~/OSINT/bin/ ``` 希望 domain 运行完全不发起任何网络请求？禁用 pivot 并强制使用缓存数据： ``` uv run osint-recon enrich example.com --offline --no-pivots ``` ## 许可证 MIT

标签：ESC4, GitHub, OSINT, 信息聚合, 威胁情报, 安全调查, 实时处理, 开发者工具, 情报收集, 数据泄露, 漏洞研究, 逆向工具