openSquat Core

## 📑 目录 - [什么是 openSquat？](#-what-is-opensquat) - [媒体报道](#-featured-in) - [Open-Core 模式](#-open-core-model) - [核心功能](#-key-features) - [快速开始](#-quick-start) - [环境要求](#-requirements) - [用法](#-usage) - [Premium 和 API 模式](#-premium-and-api-modes) - [配置说明](#%EF%B8%8F-configuration) - [自动化](#-automation) - [CLI 参考](#-cli-reference) - [贡献指南](#-contributing) - [作者](#-author) - [许可证](#-license) ## 🎯 什么是 openSquat？ openSquat 是一款**开源情报 (OSINT)** 安全工具，用于识别针对您的品牌或域名的域名抢注威胁： | 威胁类型 | 描述 | |-------------|-------------| | 🎣 **钓鱼攻击** | 模仿您的品牌的欺诈域名 | | 🔤 **拼写错误抢注** | 包含常见拼写错误的域名（例如 `gooogle.com`） | | 🌐 **IDN 同形异义词** | 来自其他字母表的形似字符 | | 👥 **Doppelgänger (克隆域名)** | 包含您的品牌名称的域名 | | 🔀 **Bitsquatting (比特抢注)** | 域名中的单比特错误 | ## 🌟 媒体报道 ### 学术引用 ## 🔓 Open-Core 模式 openSquat 遵循 **open-core 模式**： - **核心检测引擎** — 开源且由社区驱动 - **高级功能** — 通过商业情报服务提供 该模式支持透明度和社区协作，同时满足企业使用的规模、可靠性和运营需求。 ## ✨ 核心功能 - 📅 **每日 NRD 订阅源** — 自动更新新注册域名 - 🔍 **相似度检测** — Levenshtein 距离算法 - 🔓 **三种运行模式** — **Community**（免费订阅源）、**Premium Feed**（付费订阅源，相同的本地流水线），或 **Premium API**（托管式形似域名服务）。两个 Premium 模式共享同一个 openSquat API key — 详见 [Premium 和 API 模式](#-premium-and-api-modes)。 - 🛡️ **VirusTotal 集成** — 检查域名信誉 - 🌐 **Quad9 DNS 验证** — 识别恶意域名 - 📜 **证书透明度** — 监控 SSL/TLS 证书 - 📊 **多种输出格式** — TXT, JSON, CSV ## 🚀 快速开始 ### 通过 pip 安装（推荐） ``` pip install opensquat opensquat -k keywords.txt ``` ### 或克隆代码仓库 ``` git clone https://github.com/atenreiro/opensquat cd opensquat pip install -r requirements.txt python3 opensquat.py -k keywords.txt ``` ## 📦 环境要求 - **Python 3.10+** - 依赖项：`confusable_homoglyphs`, `homoglyphs`, `colorama`, `requests`, `dnspython`, `beautifulsoup4` ## 📖 用法 ### 基本命令 ``` # 默认运行 opensquat # 显示所有选项 opensquat -h # 使用自定义 keywords 文件 opensquat -k my_keywords.txt ``` ### 验证选项 ``` # 通过 Quad9 进行 DNS 验证 opensquat --dns # 检查 Certificate Transparency 日志 opensquat --ct # 扫描开放端口 (80/443) opensquat --portcheck # 交叉引用钓鱼数据库 opensquat --phishing results.txt ``` ### 输出格式 ``` # 保存为 JSON opensquat -o results.json -t json # 保存为 CSV opensquat -o results.csv -t csv ``` ### 置信度级别 | 级别 | 标志 | 描述 | |-------|------|-------------| | 0 | `-c 0` | 非常高（结果较少，准确率高） | | 1 | `-c 1` | 高（默认） | | 2 | `-c 2` | 中 | | 3 | `-c 3` | 低 | | 4 | `-c 4` | 非常低（结果较多，误报较多） | ## 💎 Premium 和 API 模式 openSquat 支持三种模式。默认模式（Community）保持不变 — 现有用户无需使用任何标志。两个 Premium 模式共享同一个 openSquat API key；如果您希望在更大的订阅源下使用相同的本地检测流水线，请选择 **Premium Feed**；如果您希望进行服务端检测且不下载本地订阅源，请选择 **Premium API**。 | 模式 | 标志 | 功能说明 | |------|------|--------------| | **Community**（默认） | _(无)_ | 下载免费的 NRD 订阅源（每天约 10 万个域名）并运行本地 Levenshtein 检测。 | | **Premium Feed** | `--premium` | 使用您的 openSquat API key 下载付费的 NRD 订阅源（`nrd-lite`，规模更大），然后运行相同的本地 Levenshtein 检测。 | | **Premium API** | `--api` | 跳过本地订阅源下载。针对每个关键字查询 openSquat 形似域名 REST API，并返回服务端匹配结果。 | ### 获取 API key 在 [opensquat.com](https://opensquat.com) 注册以获取 key。同一个 key 同时适用于 Premium Feed (`--premium`) 和 Premium API (`--api`)。 ### 提供 API key（优先级顺序） 1. 命令行中的 `--api-key YOUR_KEY` 2. `OPENSQUAT_API_KEY` 环境变量 3. 当前目录下的 `api_key.txt` 文件（每个文件一个 key，允许使用 `#` 添加注释） ### 示例 ``` # Premium Feed 模式 — 相同的本地 pipeline，更大的 feed export OPENSQUAT_API_KEY=os_xxxxxxxxxxxx opensquat -k keywords.txt --premium # Premium API 模式 — 针对每个 keyword 进行服务器端检测 opensquat -k keywords.txt --api # Premium API + 对每个返回的 domain 进行 DNS 信誉检查 opensquat -k keywords.txt --api --dns # 带 JSON 输出的 Premium API，按 keyword 分组 opensquat -k keywords.txt --api -t json -o results.json # 调整 Premium API 搜索 opensquat -k keywords.txt --api --api-fuzziness high --api-history-days 7 --api-max-results 200 ``` 当 `--premium` 或 `--api` 成功加载 key 时，CLI 会打印一行掩码确认信息，以便您验证使用了哪个 key，同时不会泄露它： ``` [*] API key loaded: os_gL...L5Mb ``` 在 Premium API 模式下，运行摘要会报告当前的活动模式、发起的 API 调用次数，以及剩余余额和使用增量（例如 `4972 (used 4 of 4976 this run)`）。尽管调用是并行运行的，但每个关键字的进度行会按照与您的关键字文件相同的顺序显示。配额耗尽（HTTP 429）会优雅地返回部分结果；认证错误（401）和套餐错误（403）会中止操作并显示明确的提示信息。 如果后端对您的请求进行了限速（带有 `Retry-After` 标头的 HTTP 429），工具会将其与配额耗尽区分开来：您将看到黄色的 `[!] Rate limit hit (retry in Ns)` 警告，而不是红色的 `quota exhausted` 消息，同时仍会返回部分结果，并且摘要会保留您真实的 API 余额，以便您准确查看实际使用了多少 credit。为了避免在大型扫描中触发速率限制，请传入 `--api-rate-limit N` 来限制所有 worker 的每秒出站请求数。对于大多数后端，值为 `8` 是一个安全的起点。 ``` # 所有限制为所有 worker 每秒 8 个请求 opensquat -k keywords.txt --api --api-rate-limit 8 ``` ### 输出格式建议 **JSON 是 Premium API 模式的推荐输出格式**，因为 API 返回的每个域名的元数据无法像其他格式那样清晰地承载：注册的 TLD、NRD 首次发现日期、IDN 同形异义词标志，以及当该域名是同形异义词时的 unicode 渲染形式。 ``` opensquat -k keywords.txt --api -t json -o results.json ``` Premium API 模式下更丰富输出的示例（已截断）： ``` [ { "keyword": "microsoft", "domains": [ {"domain": "securite-microsoft.fr", "tld": "fr", "date": "09-04-2026", "idn": false}, {"domain": "xn--mirosoft-hw7c.com", "tld": "com", "date": "09-04-2026", "idn": true, "unicode": "miᴄrosoft.com"} ] } ] ``` `idn` 标志加上 `unicode` 渲染让您可以一目了然地看到 `xn--mirosoft-hw7c.com` 实际上是 `ᴄ`（拉丁字母小写大写 C）冒充了 "microsoft" 中的 `c` — 这是纯 punycode 字符串完全隐藏的信息。 同样支持 CSV 输出，并会为每个域名生成一行包含相同元数据列的数据，这非常适合在 Excel 或 pandas 中工作的分析师： ``` opensquat -k keywords.txt --api -t csv -o results.csv ``` CSV 文件在写入时带有 UTF-8 BOM，以便 Windows 上的 Excel 能够正确渲染 unicode 同形异义词列。 Community 和 Premium Feed 模式为了保持跨模式的一致性，会输出相同的 JSON 顶层结构，但每个条目仅填充了 `domain` 字段 — NRD 订阅源不包含只有托管 API 才能提供的每个域名的元数据： ``` [ { "keyword": "microsoft", "domains": [ {"domain": "mirosoft.com"}, {"domain": "mcrosoft.net"} ] } ] ``` 如果您传入 `--api-key` 但未同时选择 `--premium` 或 `--api`，CLI 会打印一行提示，告知您该 key 将在 Community 模式下被忽略（不会进行静默的模式切换）。 在 Premium API 模式下，`-c/--confidence` 会自动映射到 API 的 fuzziness（`0→exact`、`1→low`、`2→auto`、`3→high`、`4→high`）。使用 `--api-fuzziness` 可进行覆盖。 Premium API (`--api`) 与 `--doppelganger` 和 `-d/--domains` 不兼容。 ## ⚙️ 配置说明 ### 关键字文件 (`keywords.txt`) ``` # 以 # 开头的行是注释 mycompany mybrand myproduct ``` ### VirusTotal API Key (`vt_key.txt`) 要使用 `--vt` 或 `--subdomains`，请添加您的 API key： ``` # 在 https://www.virustotal.com 获取免费 API key your_api_key_here ``` ### openSquat API Key (`api_key.txt`) `--premium` 和 `--api` 所必需。在工作目录中创建一个 `api_key.txt` 文件： ``` # 在 https://opensquat.com 获取你的 key # 以 # 开头的行将被忽略；使用第一个非注释行。 os_your_key_here ``` CLI 按以下顺序解析 key：`--api-key` 标志 → `$OPENSQUAT_API_KEY` 环境变量 → `api_key.txt` 文件。在共享环境中，首选环境变量和文件方法，因为 CLI 参数可以通过 `ps` 命令看到。 ## 🤖 自动化 通过 crontab 每日运行： ``` # 通过 pip 安装（推荐） — 每天早上 8 点，feed 在 UTC 时间约 早上 7:30 更新 0 8 * * * cd /path/to/workdir && opensquat -k keywords.txt -o results.json -t json # 通过 Repo checkout — 直接使用 python3 调用 opensquat.py 0 8 * * * cd /path/to/opensquat && python3 opensquat.py -k keywords.txt -o results.json -t json ``` ## 📋 CLI 参考 | 参数 | 默认值 | 描述 | |----------|---------|-------------| | `-k, --keywords` | `keywords.txt` | 要搜索的关键字文件 | | `-o, --output` | `results.txt` | 输出文件名 | | `-t, --type` | `txt` | 输出格式：`txt`, `json`, `csv` | | `-c, --confidence` | `1` | 置信度级别 (0-4)。在 `--api` 模式下，这会自动映射到 fuzziness（`-c 3` 和 `-c 4` 均对应 `high`）。 | | `-d, --domains` | — | 使用本地域名文件而不是下载 | | `-u, --url` | opensquat feed | 下载域名订阅源的 URL | | `--dns` | — | 启用 Quad9 DNS 验证 | | `--doppelganger` | — | 仅 Doppelganger 模式（包含关键字且进行可达性检查） | | `--ct` | — | 搜索证书透明度日志 | | `--phishing` | — | 交叉比对钓鱼数据库 | | `--subdomains` | — | 通过 VirusTotal 获取子域名 | | `--portcheck` | — | 检查开放端口 80/443 | | `--vt` | — | 通过 VirusTotal 进行验证 | | `--premium` | — | **Premium Feed 模式** — 使用付费的 NRD 订阅源（需要 openSquat API key） | | `--api` | — | **Premium API 模式** — 针对每个关键字查询 openSquat 形似域名 REST API（无本地订阅源） | | `--api-key` | — | openSquat API key（或设置 `$OPENSQUAT_API_KEY`，或使用 `api_key.txt`） | | `--api-fuzziness` | _(来自 `-c`)_ | Premium API 模式：`exact`、`low`、`high` 或 `auto` | | `--api-history-days` | — | Premium API 模式：以天为单位的 NRD 历史时间窗口（根据套餐上限截断） | | `--api-max-results` | — | Premium API 模式：每个关键字的最大结果数（根据套餐上限截断） | | `--api-rate-limit` | _(无限)_ | Premium API 模式：所有 worker 每秒的最大出站请求数 | ## 👤 作者 **Andre Tenreiro** — [LinkedIn](https://www.linkedin.com/in/andretenreiro/) · [PGP Key](https://mail-api.proton.me/pks/lookup?op=get&search=andre@opensquat.com) ## 📜 许可证 本项目基于 [GNU GPL v3](LICENSE) 授权。

标签：Cybersquatting检测, ESC4, OSINT, Python, 域名监控, 威胁情报, 开发者工具, 无后门, 网络测绘, 逆向工具