samthehackers/MIRAGE

# MIRAGE **基于 AI 的钓鱼、伪造和社会工程学检测框架** 由 [TrustGeeks Security](https://github.com/trustgeeks) 构建 — 涵盖攻防安全、威胁情报和防御工具。 []() [](LICENSE) []() ## 功能简介 MIRAGE 通过多层管道分析电子邮件和 URL，检测其中的钓鱼、伪造和社会工程学指标： 1. **确定性分析器** — SPF/DKIM/DMARC 对齐、显示名称伪造、同形字/Unicode 冒充、回复地址不匹配、typosquat/combosquat 检测、punycode、URL 混淆技巧、BEC 话术模式。 2. **AI 推理层** — 默认使用 Claude API，如果 Claude 不可用（无密钥、触发频率限制、离线），会**自动回退到本地 Ollama 模型**，并最终以完全离线的启发式回退作为最后手段。AI 绝不会只返回一个简单的分数 — 它始终会用通俗易懂的语言解释*原因*，并引用实际证据。 3. **加权风险引擎** — 将所有发现整合为一个透明的 0-100 分数以及 `SAFE / SUSPICIOUS / HIGH_RISK / CRITICAL` 判定结论，并提供一句话的高管摘要。 4. **报告生成** — JSON（用于 SIEM/SOAR 摄取）、Markdown（用于工单/PR）和面向客户的 HTML 报告。 一切都**在设计上保证可解释**：每项发现都包含描述、证据、严重性，以及（在适用时）MITRE ATT&CK 映射。 ## 诞生背景 钓鱼和 AI 辅助的社会工程学攻击不会消失 — 它们正变得越来越低成本，且逐年更具迷惑性。MIRAGE 致力于成为一个持久的、可由社区扩展的工具：其坚实的内核在威胁态势演变时依然保持实用，同时通过插件系统，可以无需修改核心代码即可添加新的攻击模式（如深度伪造语音、短信钓鱼、QR 钓鱼、特定平台的诈骗）。 ## 安装说明 ``` git clone https://github.com/samthehackers/MIRAGE.git cd mirage poetry install ``` 或者使用 pip： ``` pip install -e . ``` ### 可选：启用完整的 AI 推理 ``` export ANTHROPIC_API_KEY="sk-ant-..." ``` 没有密钥？MIRAGE 会自动尝试本地的 [Ollama](https://ollama.com) 实例（`ollama pull llama3.1`），如果该实例也无法访问，则会回退到离线启发式解释器。**扫描绝不会因为 AI 不可用而失败** — 您至少始终能获得完整的确定性分析。 ## 使用说明 ``` # 分析单个电子邮件 mirage analyze suspicious_email.eml # 分析 URL mirage analyze-url https://paypa1-secure-login.com # 批量分析包含 .eml 文件的文件夹，输出 HTML 报告 mirage analyze-folder samples/ --report report.html # 跳过 AI（仅启发式，最快，完全离线） mirage analyze email.eml --no-ai # 用于脚本 / SOAR pipelines 的 JSON 输出 mirage analyze email.eml --json # 在 HIGH_RISK/CRITICAL 时返回非零 exit code — 管道传入 automation mirage analyze email.eml --no-ai || quarantine.sh email.eml ``` ### 输出示例 ``` CRITICAL suspicious_invoice.eml (100/100) suspicious_invoice.eml scored 100/100 (critical) across 9 finding(s). Top indicators: Display name impersonates a role of authority ('ceo'); Business Email Compromise language patterns detected; Possible typosquat of 'paypal.com'. ┏━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Severity ┃ Score ┃ Finding ┃ ┡━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ high │ 30 │ Business Email Compromise language patterns detected │ │ high │ 20 │ Possible typosquat of 'paypal.com' │ │ high │ 15 │ DMARC alignment failed │ └──────────┴───────┴────────────────────────────────────────────────────────┘ AI (claude): This message shows strong, corroborated evidence of a Business Email Compromise attempt impersonating a CEO... ``` ## 架构设计 有关完整的模块分解，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。简短版本如下： ``` mirage/ ├── email/ # .eml parsing, SPF/DKIM/DMARC, spoofing/homoglyph/BEC detection ├── urls/ # typosquat, punycode, entropy, obfuscation heuristics ├── ai/ # Claude + Ollama reasoning layer with automatic fallback ├── analyzer/ # risk engine + top-level orchestrator ├── reports/ # JSON / Markdown / HTML renderers ├── plugins/ # plugin base class + loader — extend without touching core ├── models/ # shared Finding / Verdict / AIExplanation schemas └── cli/ # Typer-based CLI ``` ## 扩展 MIRAGE（插件） 扩展目标检测器 — 短信钓鱼、语音钓鱼、深度伪造音频特征、QR 钓鱼、Slack/Teams/Discord 诈骗检测 — 旨在作为插件发布，而非核心代码修改。详情请参阅 [docs/PLUGIN_GUIDE.md](docs/PLUGIN_GUIDE.md)。 ## 路线图 请参阅 [docs/ROADMAP.md](docs/ROADMAP.md)。核心 v1 版本（即本版本）涵盖电子邮件 + URL 情报、AI 推理和报告生成。后续计划：附件/宏分析、实时威胁情报源集成（VirusTotal、URLHaus、AbuseIPDB）、浏览器扩展，以及上述基于插件的扩展目标。 ## 开源许可证 MIT — 详见 [LICENSE](LICENSE)。 *由 [TrustGeeks Security](https://github.com/trustgeeks) 构建并维护。*

标签：AI风险缓解, ESC8, Python, 人工智能, 威胁情报, 开发者工具, 无后门, 用户模式Hook绕过, 社会工程学, 网络安全, 调试插件, 逆向工具, 钓鱼检测, 隐私保护