```
⚠ 3 registered · crit: 1 · mx: 1 · fresh <7d: 1
Otacon · target: github.com
┌────────────────────────────────┬────────────────────┬──────────┬─────┬────┬─────┬──────┐
│ Domain │ Risk │ Age │ DNS │ MX │ SSL │ HTTP │
├────────────────────────────────┼────────────────────┼──────────┼─────┼────┼─────┼──────┤
│ githubupdate.com │ #######- 92 crit │ 3d │ + │ + │ + │ 200 │
│ combosquat . "GitHub - Security Update Required" │
│ bithub.com │ #####--- 68 high │ 2y │ + │ - │ + │ 301 │
│ typo │
│ githuub.com │ ####---- 48 med │ 8mo │ + │ - │ - │ 404 │
│ typo │
└────────────────────────────────┴────────────────────┴──────────┴─────┴────┴─────┴──────┘
Permutations: 143 · registered: 3 · med: 1 · high: 1 · crit: 1
```
## 目录
- [为什么使用 Otacon？](#why-otacon)
- [快速开始](#quick-start)
- [安装](#install)
- [用法](#usage)
- [模式](#modes)
- [输出格式](#output-formats)
- [评分机制](#how-scoring-works)
- [检测技术](#detection-techniques)
- [CI/CD 集成](#cicd-integration)
- [Watch 模式 — 持续监控](#watch-mode--continuous-monitoring)
- [交互模式](#interactive-mode)
- [白名单 / 防御性标志](#whitelist--defensive-flag)
- [与 dnstwist 的对比](#comparison-with-dnstwist)
- [常见问题](#faq)
- [故障排除](#troubleshooting)
- [贡献与开发](#contributing--development)
- [许可与道德规范](#license--ethics)
## 为什么使用 Otacon？
网络钓鱼活动几乎总是从**相似域名**开始的。攻击者会在实际攻击发生前的几周（或几天）注册 `github-update.com`、`paypa1.com`、`goog1e.com`。当人们注意到时，凭证早已被盗取。
Otacon 专为需要在**攻击发生前**找到这些域名的人而构建：
| 角色 | 用例 |
|---|---|
| **渗透测试人员 / 红队** | 侦察 — 找出针对客户品牌的现有相似域名，以纳入测试范围或用于社会工程学测试 |
| **蓝队 / SOC** | 持续监控您自己的域名 — 当出现新的伪造域名（尤其是带有 MX 记录或新注册的域名）时立即收到报警 |
| **品牌保护** | 一次性审查数百个变体，导出为 JSON/HTML 格式，供法务团队或 DMCA 申报使用 |
| **CI/CD 门禁** | 当出现严重的仿冒域名在线时阻止部署 (`--fail-on critical`) |
Otacon 是**完全被动**的：DNS 查询、TLS 握手、每个变体一次 HTTP GET 请求。没有尝试漏洞利用、没有身份验证、没有大规模爬取。
## 快速开始
```
pipx install git+https://github.com/notimeftnoir/otacon.git
otacon scan example.com
```
就是这样。大约 10 秒钟内，您就可以获得一个按风险排序的彩色终端表格。
需要不进行网络检查的字典？`otacon generate example.com -o wordlist.txt`
想要引导模式？只需不带参数运行 `otacon`。
## 安装
**推荐 — 通过 [pipx](https://pipx.pypa.io) 进行独立的全局安装：**
```
pipx install git+https://github.com/notimeftnoir/otacon.git
```
**备选 — 在任何活动的虚拟环境中使用标准 pip 安装：**
```
pip install git+https://github.com/notimeftnoir/otacon.git
```
开发安装（从源码，包含测试）
```
git clone https://github.com/notimeftnoir/otacon.git
cd otacon
python3 -m venv .venv
source .venv/bin/activate # Linux / macOS
.venv\Scripts\activate # Windows (PowerShell)
pip install -e ".[dev]"
pytest && ruff check .
```
## 用法
```
otacon # interactive mode (guided prompts)
otacon scan example.com # one-shot scan, all signals
otacon scan example.com --no-http # DNS only — faster, fewer signals
otacon scan example.com --all # include unregistered variants
otacon scan example.com --concurrency 100 # crank concurrency (default 50)
otacon scan example.com --exclude "alias.com,brand.io"
otacon scan example.com --exclude-file allowed.txt
otacon scan example.com --json r.json --html r.html --markdown r.md
otacon scan example.com --fail-on high # CI gate — exit 2 on high/critical
otacon watch example.com --interval 24h # continuous loop, baseline diff
otacon watch example.com --interval 6h \
--notify https://hooks.example.com/abc # POST diff JSON on high-risk changes
otacon generate example.com -o variants.txt # wordlist only, no network
otacon --version # print version and exit
```
### CLI 参数参考
| 参数 | 默认值 | 描述 |
|---|---|---|
| `--no-http` | 关闭 | 跳过 HTTP 和 TLS 探测。仅保留 DNS+MX+WHOIS。禁用 ⚑ 防御性标志。 |
| `--all` | 关闭 | 在输出中显示未注册的变体。 |
| `-c`, `--concurrency` | `50` | 最大并发 DNS/HTTP 检查数。请谨慎增加 — 您的解析器可能会进行速率限制。 |
| `-x`, `--exclude` | — | 逗号分隔的白名单：`--exclude "alias.com,brand.io"` |
| `--exclude-file` | — | 文件路径，每行一个域名。`#` 开头为注释。 |
| `--json` | — | 将完整报告（每个变体、每个信号、每个原因）写入文件。 |
| `--markdown` / `--md` | — | 写入可直接粘贴到工单中的 Markdown 表格。 |
| `--html` | — | 生成一个自带深色主题的独立 HTML 报告。 |
| `--fail-on` | — | `low` / `medium` / `high` / `critical` — 当任何已注册变体达到此级别时，以 `2` 退出。 |
| `--interval` *(watch)* | 单次 | 每隔 `N{h,m,s}` 循环执行。省略则仅执行一次。 |
| `--notify` *(watch)* | — | Webhook URL。当 NEW（新增）或 CHANGED（变更）域名为 high/critical 时，POST 包含差异内容的 JSON。 |
| `-V`, `--version` | — | 打印版本号并退出。 |
### 退出代码（用于 CI 门禁）
| 代码 | 含义 |
|---|---|
| `0` | 正常 — 没有达到 `--fail-on` 阈值及以上的内容 |
| `1` | 运行时错误（输入错误、域名为空、文件 I/O 错误） |
| `2` | 超过阈值 — 至少有一个已注册的变体达到了 `--fail-on` 标准 |
## 模式
Otacon 有三个子命令以及一个交互式引导模式：
| 模式 | 联网？ | 适用场景 |
|---|---|---|
| `scan` | 是 | 一次性审查。最常用。 |
| `watch` | 是 | 持续监控。与保存的基准进行差异对比。在高风险变更时触发 Webhook。 |
| `generate` | **否** | 离线字典生成。用于提供给外部工具（`subfinder`、`nuclei` 等）或测试 Otacon *会*检查哪些内容。 |
| *(无子命令)* | 是 | **交互模式** — 引导式提示，随后是扫描后操作循环（在浏览器中打开、WHOIS、重新扫描、加入白名单）。 |
## 输出格式
一次扫描，四种消费方式。请选择适合您工作流程的格式：
| 格式 | 参数 | 最适合 |
|---|---|---|
| **丰富的终端表格** | *(默认)* | 交互式分发处理 — 颜色、风险条、命中结果实时流式显示 |
| **JSON** | `--json r.json` | 流程、SIEM 摄取、自定义分析。包含每个变体的 `risk_reasons`。 |
| **Markdown** | `--md r.md` | 直接粘贴到 Jira / GitHub issues / Slack 中 |
| **HTML** | `--html r.html` | 交给法务 / 合规 / 管理层。自带深色主题的独立文件，无外部依赖。 |
您可以同时传入这三个导出参数 — 每种格式都是从同一个内存报告渲染出来的，因此它们始终保持一致。
### JSON 结构（节选）
```
{
"target": "github.com",
"started_at": "2026-06-08T14:23:01+00:00",
"total_permutations": 143,
"results": [
{
"domain": "githubupdate.com",
"kind": "combosquat",
"resolves": true,
"has_mx": true,
"has_ssl": true,
"http_status": 200,
"page_title": "GitHub - Security Update Required",
"created_at": "2026-06-05T09:12:00+00:00",
"age_days": 3,
"risk_score": 92,
"risk_level": "critical",
"risk_reasons": [
"technique: combosquat (+20)",
"resolves to an IP (+10)",
"has an MX record — ready for email phishing (+25)",
"active SSL certificate (+15)",
"responds HTTP 200 — active site (+15)",
"registered 3 days ago (+20)"
],
"is_likely_defensive": false
}
]
}
```
每个评分都被完全分解 — 您总能回答出*“为什么它得了 92 分？”*。
## 评分机制
每个分数都是**明确、可解释的信号**的总和 — 没有 ML，没有黑盒。每个原因都会在 JSON 导出 (`risk_reasons`) 和交互式详情视图中展示。
信号分值
| 信号 | 分数 |
|---|---|
| **MX 记录** — 准备好进行邮件钓鱼 | +25 |
| **技术** — homoglyph（同形异义字）/ IDN | +25 |
| subdomain spoof（子域名欺骗） | +22 |
| combosquat（组合抢注） | +20 |
| typo（拼写错误） | +18 |
| soundsquat（发音抢注） | +16 |
| bitsquat · vowel-swap（位翻转 · 元音替换） | +15 / +14 |
| hyphenation · plural · TLD-swap（连字符化 · 复数 · 顶级域替换） | +12 / +10 / +10 |
| **域名年龄** — <7 天 | +20 |
| <30 天 · <90 天 | +12 / +5 |
| **SSL** 证书有效 | +15 |
| **HTTP** 2xx 存活 · 3xx 重定向 | +15 / +10 |
| 4xx · 5xx | +5 / +3 |
| **解析**到 IP | +10 |
| **重定向**到其他地方（非 2xx，非 3xx） | +5 |
分数上限为 100。未注册的域名始终为 0 分。
### 风险级别
| 级别 | 分数 | 含义 |
|---|---|---|
| 🔴 **critical** | 80–100 | 存在活跃的基础设施且具备发送邮件能力 — 应视为活跃威胁。立即调查。 |
| 🟠 **high** | 60–79 | 已注册且带有严重信号（MX 记录或在线网站）。加入监控；考虑进行下线处理。 |
| 🟡 **medium** | 35–59 | 已注册，有一些信号 — 值得关注。 |
| 🔵 **low** | 15–34 | 已注册，信号极少。可能是停放 / 未使用。 |
| 🟢 **safe** | 0–14 | 未注册或可忽略。 |
## 检测技术
Otacon 实现了 **11 种排列技术**，这些技术均以真实攻击为模型：
| 技术 | 示例 (`example.com`) | 真实攻击向量 |
|---|---|---|
| **Homoglyph（同形异义字）** | `exаmple.com` *(西里尔字母 а)* | 视觉欺骗 — 人类肉眼无法分辨区别 |
| **IDN / Punycode** | `xn--exmple-4ve.com` | ACE 编码的 Unicode，浏览器可能会原生渲染 |
| **Typo（拼写错误）** | `exmple.com`, `exsmple.com`, `exampel.com` | QWERTY 键盘上的误触输入 |
| **Combosquat（组合抢注）** | `example-login.com`, `secureexample.com` | 添加“信任”关键字 — 常见于钓鱼邮件链接 |
| **TLD swap（顶级域替换）** | `example.io`, `example.xyz` | 同名，不同（通常更便宜）的 TLD |
| **Subdomain spoof（子域名欺骗）** | `example.com.login.net` | 将原始域名用作标签；利用 URL 地址栏进行欺骗 |
| **Bitsquat（位抢注）** | `dxample.com`（`e`→`d` 只翻转了一位） | DRAM/DNS 内存错误翻转了单个位 |
| **Hyphenation（连字符化）** | `ex-ample.com` | 插入/删除连字符 |
| **Soundsquat（发音抢注）** | `egzample.com`, `eksample.com` | 语音替换（ph/f, c/k, s/z, x/ks） |
| **Vowel swap（元音替换）** | `exomple.com`, `exumple.com` | 将一个元音替换为另一个 |
| **Plural（复数）** | `examples.com` | 单复数变体 |
生成器会对结果进行去重，并且**永远不会在输出中包含原始域名**。
## CI/CD 集成
在您的发布流程中添加品牌保护门禁。如果出现严重的仿冒域名上线，流水线将失败。
### GitHub Actions
```
name: brand-protection
on:
schedule:
- cron: "0 6 * * *" # daily at 06:00 UTC
workflow_dispatch:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: sudo apt-get install -y libc-ares-dev
- run: pip install git+https://github.com/notimeftnoir/otacon.git
- run: otacon scan example.com --json report.json --fail-on critical
- if: failure()
uses: actions/upload-artifact@v4
with:
name: otacon-report
path: report.json
```
### GitLab CI
```
brand-protection:
image: python:3.12
before_script:
- apt-get update && apt-get install -y libc-ares-dev
- pip install git+https://github.com/notimeftnoir/otacon.git
script:
- otacon scan $CI_PROJECT_NAME.com --html report.html --fail-on high
artifacts:
when: always
paths: [report.html]
only: { refs: [schedules] }
```
## Watch 模式 — 持续监控
`watch` 会重新运行整个流水线，与保存的基准（`~/.otacon/
.json`）进行差异对比，并且仅打印发生变更的内容：
- **NEW（新增）** — 自上次运行以来新注册的变体
- **CHANGED（变更）** — 分数或级别发生转变（例如，突然获得了 MX 记录）
- **GONE（消失）** — 变体已注销或失效
```
otacon watch example.com --interval 6h \
--notify https://hooks.slack.com/services/XXX/YYY/ZZZ \
--json diff.json
```
Webhook **仅在高优先级变更**（high/critical 级别的新增或变更域名）时触发 — 不会因低风险 churn 产生干扰。Diff payload 与序列化为 JSON 的 `WatchDiff` 模型相同，因此您可以轻松将其路由到 Slack、PagerDuty 或您自己的 SIEM。
使用 `Ctrl+C` 中断 — 当前迭代完成后，循环将干净地退出。
## 交互模式
直接运行 `otacon`（不带子命令）即可获得引导式体验。扫描完成后，您可以分别对每个已注册的域名进行操作：
```
Action for githubupdate.com:
[*] [o]pen — open in browser
[w]hois — show registration info
[e]xport — save result as JSON
[a]llow — skip in this session
[r]escan — re-check this domain now
[b]ack — pick a different domain
[q]uit — exit actions
```
旨在无需离开终端即可对新的扫描结果进行分发处理：打开可疑网站、检查 WHOIS、决定加入白名单还是上报。
## 白名单 / 防御性标志
品牌通常会出于防御目的拥有自己的相似域名（例如，google.com` 拥有 `gooogle.com` 并将其重定向）。当重定向指向原始域名时，Otacon 会用 ⚑ 标志进行标记：
```
microsft.com ⚑ → microsoft.com crit(85) — but defensive
```
扫描完成后，Otacon 会提示将所有带有 ⚑ 标志的域名写入 `whitelist.txt`。在同一目录下的后续运行会自动识别此文件；您也可以使用 `--exclude-file path/to/list.txt` 指向自定义文件。
白名单文件格式：
```
# 防御性注册，由我们拥有
gooogle.com
goggle.com
g00gle.com
```
白名单中的域名会在进行任何网络调用之前被跳过 — 从而节省时间和配额。
## 与 dnstwist 的对比
[`dnstwist`](https://github.com/elceef/dnstwist) 是该领域的元老级工具。Otacon 和 dnstwist 解决的问题有所交集，但侧重点不同。
| | **Otacon** | **dnstwist** |
|---|---|---|
| 带有详细信号说明的风险**评分** | ✓ 0–100，每一分都有来源 | ✗ 仅有原始信号 |
| 防御性注册标志 | ✓ 重定向至原域名时显示 ⚑ | ✗ |
| 带有基准差异对比的 Watch 模式 | ✓ NEW/CHANGED/GONE | ✗（需手动重新运行 + 差异对比） |
| 高风险变更时触发 Webhook | ✓ | ✗ |
| CI/CD 退出代码门禁 | ✓ `--fail-on` | ✗ |
| 独立的 HTML 报告 | ✓ 深色主题，无 JS | 部分（`--format html`） |
| 交互式扫描后分发处理 | ✓ 打开/whois/重新扫描/允许 | ✗ |
| 排列技术 | 11 | 13+ |
| 页面的可视化截图 | ✗ | ✓ |
| 模糊/语音字典攻击 | ✓ soundsquat | ✓ |
| GeoIP / Whois 丰富化 | 仅 WHOIS | 两者皆有 |
**如果您**需要截图、模糊哈希、更深度的丰富化，**请使用 dnstwist**。
**如果您**需要主观的风险评分、防御性标志检测、带有 webhook 的 watch 模式以及 CI 友好的退出代码，**请使用 Otacon**。
## 常见问题
这合法吗？它会触碰目标域名吗？
Otacon 仅执行**被动侦察**：标准的 DNS 查询、:443 端口上的 TLS 握手（无数据交换）以及一次 HTTP GET 请求。没有登录尝试、没有扫描、没有大规模爬取。这与在浏览器中访问页面的活动级别相同。
话虽如此，请将其用于**您自己的域名**或**在授权的测试任务中**。请参阅 `LICENSE` 和 `SECURITY.md`。
为什么不使用机器学习？
因为渗透测试人员和 SOC 分析师需要为自己的发现进行*辩护*。“我们的模型给了它 87 分”不是一个站得住脚的回答。而 `risk_reasons` 是。Otacon 中的每个分数都带有生成它的确切信号列表 — 可以在五秒钟内审计，只需在 `scoring.py` 中编辑一行即可调整。
它有多快？
在家庭网络下，对一个包含 150 个变体的域名进行带 HTTP 探测的完整扫描通常可在 **8–15 秒**内完成。仅 DNS 模式 (`--no-http`) 大约**快 3 倍**。
瓶颈通常是：
1. WHOIS 查询的速率限制（我们限制并发数为 4）
2. DNS 解析器延迟（默认的 `--concurrency 50` 比较保守；在具有快速解析器的服务器上可以调高）
3. `c-ares` 库 — 确保它是原生安装的，而不是回退到 Python 的 stdlib 解析器
它能发现 IDN homoglyph 攻击（xn-- 域名）吗？
能。`IDN` 技术会为每个 Unicode homoglyph 生成 punycode 编码的变体。它们在表格中显示为 `xn--...`。基础分为 +25，与 homoglyph 相同 — 这些是最危险的，因为它们在大多数浏览器中会渲染为原始字形。
它支持国际化域名（非 ASCII 目标）吗？
部分支持。Otacon 接受 Unicode 输入，但排列引擎主要针对 ASCII 标签进行调整。IDN/punycode 编码适用于*输出*（ASCII 原始域名的生成 homoglyph）。引擎真正的 i18n 国际化支持已列入路线图。
为什么我知道有伪造域名，但我的扫描结果却显示 0？
可能的原因，按顺序排列：
1. **仅 DNS 模式漏掉了它们** — 在 `--no-http` 模式下，您只能看到已解析的变体。请尝试完整扫描。
2. **它们隐藏在 Cloudflare / CDN 后面** — 它们能够解析，但 SSL/HTTP 探测超时了。增加 `--concurrency` 没有帮助；如果经常出现此问题，请在 `resolver.py` 中提高单次请求的超时时间。
3. **您的 DNS 解析器受到速率限制** — 尝试使用其他解析器或降低 `--concurrency`。
4. **伪造域名位于我们默认列表中没有的 TLD 上** — 请提交一个包含该 TLD 的 issue。
WHOIS 数据来自哪里？
我们使用 [`asyncwhois`](https://pypi.org/project/asyncwhois/)，它直接与 TLD WHOIS 服务器通信（无需第三方 API，没有配额限制）。一些 TLD（例如 `.ai`、`.io`）有时会返回受限或被剥离的响应 — 在这种情况下，`age_days` 将为 `null`，并且基于年龄的评分计算将被跳过（优雅降级）。
如何添加我自己的排列技术？
1. 在 `models.py` 中的 `PermutationType` 枚举里添加一个值
2. 在 `permutations.py` 中添加一个 `_my_technique(label: str) -> set[str]` 函数
3. 将其添加到 `generate()` 的流水线列表中 — 顺序对于去重优先级很重要
4. 在 `scoring._KIND_BASE` 中添加一个基础分数
5. 在 `tests/test_permutations.py` 中带上测试提交一个 PR
## 故障排除
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 安装时出现 `ModuleNotFoundError: aiodns` | 缺少 `c-ares` 系统库 | `apt install libc-ares-dev` / `brew install c-ares`，然后重新安装 |
| 扫描卡在 "Checking variants" | DNS 解析器无法访问或受到速率限制 | 降低 `--concurrency`，更换解析器 (`1.1.1.1`, `8.8.8.8`) |
| 对于 `.ai` / `.io` / `.pl`，WHOIS 始终为 `—` | 注册局 WHOIS 速率限制 | 稍后重试；这是正常现象 |
| Windows: `ConnectionResetError [WinError 10054]` | 在 1.0+ 版本中应该已自动修复 | 确保您使用的是最新版本；这曾经使用了 Proactor 循环，我们在 Windows 上已切换至 Selector |
| `Unverified HTTPS request` 警告 | 有意被抑制 — 我们是故意探测无效证书的 | 无，默认已隐藏 |
如果仍有问题无法解决，请[提交一个 issue](https://github.com/notimeftnoir/otacon/issues)，并附上：
- Otacon 版本 (`otacon --version`)
- Python 版本、操作系统和架构
- 完整的命令和（如果可以安全分享的话）目标域名
- 错误消息或异常行为
## 贡献与开发
有关开发环境设置、Lint 和测试命令，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
简要概述：
```
git clone https://github.com/notimeftnoir/otacon.git
cd otacon
python -m venv .venv && source .venv/bin/activate # or .venv\Scripts\activate
pip install -e ".[dev]"
pytest && ruff check .
```
架构深度解析：[`docs/DESIGN.md`](docs/DESIGN.md)。
安全披露政策：[`SECURITY.md`](SECURITY.md)。
## 许可与道德规范
**MIT 许可证。** 可自由使用。
Otacon **仅进行被动操作** — DNS 查询、TLS 握手、每个变体一次 HTTP GET 请求。不进行漏洞利用尝试，不进行暴力破解，不进行身份验证。
**仅适用于：**
- 您拥有的域名
- 授权的安全测试任务中的域名（须有书面测试范围授权）
- 您获得明确监控许可的域名
**请勿用于：** 骚扰、人肉搜索或构建攻击工具。如果您在防御任务中发现它很有用，请[打个招呼](https://github.com/notimeftnoir/otacon/issues) — 您的反馈将决定未来的路线图。