bkhnaq/phising-triage-bot

# 🔍 自动化钓鱼邮件分类 Bot 一款 SOC（安全运营中心）自动化工具，用于分析分析师通过 Telegram 转发的可疑钓鱼邮件，并返回结构化的安全报告。 ## 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ Telegram Chat │ │ SOC analyst uploads .eml file │ └──────────────────────┬───────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ bot/telegram_handler.py │ │ • Receives the file │ │ • Orchestrates the analysis pipeline │ │ • Sends the report back │ └──────────────────────┬───────────────────────────────────────────┘ │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │ email_ │ │ threat_ │ │ scoring/ │ │ analysis/ │ │ intel/ │ │ risk_scoring │ │ │ │ │ │ │ │ • parser │ │ • VirusTotal│ │ • Weighted │ │ • headers │ │ • AlienVault│ │ score 0-100│ │ • URLs │ │ OTX │ │ • Verdict │ │ • attach. │ │ • AbuseIPDB │ │ │ │ • QR codes │ │ • Security- │ │ │ │ • AI class.│ │ Trails │ │ │ └────────────┘ └─────────────┘ └──────┬───────┘ │ ▼ ┌──────────────┐ │ report/ │ │ report_gen. │ │ │ │ • Markdown │ │ report │ └──────────────┘ ``` ## 项目结构 ``` phishing-triage-bot/ ├── main.py # Entry point – starts the bot ├── config/ │ └── settings.py # Loads env vars & configuration ├── bot/ │ └── telegram_handler.py # Telegram bot commands & file handler ├── email_analysis/ │ ├── email_parser.py # Parses .eml files │ ├── header_analyzer.py # SPF / DKIM / DMARC checks │ ├── header_forensics.py # SMTP relay chain forensics │ ├── url_extractor.py # Extracts & expands URLs │ ├── attachment_analyzer.py # Extracts attachments, SHA-256 hashes │ ├── heuristic_analyzer.py # Brand impersonation, keywords, domain age │ ├── homograph_analyzer.py # Unicode / Cyrillic homograph detection │ ├── qr_code_analyzer.py # QR code scanning in image attachments │ ├── ai_classifier.py # AI phishing classifier (Gemini) │ └── phishing_rules.py # Display name spoofing & lookalike domains ├── threat_intel/ │ ├── virustotal_checker.py # VirusTotal v3 API integration │ ├── alienvault_checker.py # AlienVault OTX API integration │ ├── ip_reputation.py # AbuseIPDB + Spamhaus DNSBL checks │ └── passive_dns.py # SecurityTrails passive DNS lookups ├── scoring/ │ └── risk_scoring.py # Weighted risk scoring engine ├── report/ │ └── report_generator.py # Markdown report builder ├── requirements.txt ├── Dockerfile ├── .env.example ├── .gitignore └── README.md ``` ## 功能特性 | # | 功能 | 模块 | |---|---------|--------| | 1 | 通过 Telegram 接收 `.eml` 文件 | `bot/telegram_handler.py` | | 2 | 解析邮件头与正文 | `email_analysis/email_parser.py` | | 3 | SPF / DKIM / DMARC 分析 | `email_analysis/header_analyzer.py` | | 4 | SMTP 中继链取证与 IP 地理位置 | `email_analysis/header_forensics.py` | | 5 | 从邮件正文中提取所有 URL | `email_analysis/url_extractor.py` | | 6 | 检测并展开短链接 | `email_analysis/url_extractor.py` | | 7 | 提取附件并计算 SHA-256 哈希值 | `email_analysis/attachment_analyzer.py` | | 8 | 品牌冒充与可疑关键词检测 | `email_analysis/heuristic_analyzer.py` | | 9 | Unicode / 西里尔字母同形字检测 | `email_analysis/homograph_analyzer.py` | | 10 | 扫描图片附件中的二维码 | `email_analysis/qr_code_analyzer.py` | | 11 | 显示名称欺骗检测 | `email_analysis/phishing_rules.py` | | 12 | 相似域名检测 (Levenshtein) | `email_analysis/phishing_rules.py` | | 13 | AI 钓鱼分类 (Gemini) | `email_analysis/ai_classifier.py` | | 14 | VirusTotal 威胁情报 | `threat_intel/virustotal_checker.py` | | 15 | AlienVault OTX 威胁情报 | `threat_intel/alienvault_checker.py` | | 16 | IP 信誉 (AbuseIPDB + Spamhaus) | `threat_intel/ip_reputation.py` | | 17 | 被动 DNS (SecurityTrails) | `threat_intel/passive_dns.py` | | 18 | 加权风险评分 (0-100) | `scoring/risk_scoring.py` | | 19 | 格式化钓鱼报告 | `report/report_generator.py` | ## 快速开始 ### 1. 克隆与配置 ``` git clone cd phishing-triage-bot # 从示例创建 .env cp .env.example .env # 编辑 .env 并添加您的 API keys ``` ### 2. 安装依赖 ``` python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate pip install -r requirements.txt ``` ### 3. 获取 API 密钥 | 服务 | 获取密钥地址 | 是否必须 | |---------|---------------------|----------| | **Telegram Bot** | 在 Telegram 上与 [@BotFather](https://t.me/BotFather) 对话 | 是 | | **VirusTotal** | https://www.virustotal.com/gui/my-apikey | 推荐 | | **AlienVault OTX** | https://otx.alienvault.com/accounts/signup | 推荐 | | **Gemini AI** | https://aistudio.google.com/apikey | 可选 | | **AbuseIPDB** | https://www.abuseipdb.com/account/api | 可选 | | **SecurityTrails** | https://securitytrails.com/app/signup | 可选 | ### 4. 运行 Bot ``` python main.py ``` ### 5. 使用方法 1. 打开 Telegram 并与你的 Bot 开始对话。 2. 发送 `/start` 以确认其运行正常。 3. 上传一个 `.eml` 文件。 4. 等待钓鱼分类报告。 ## 使用 Docker 运行 ``` docker build -t phishing-triage-bot . docker run --env-file .env phishing-triage-bot ``` ## 分析流程原理 1. **解析** – 使用 Python 内置的 `email` 库解析 `.eml` 文件。提取主题、发件人、收件人、日期、正文（文本 + HTML）和原始头信息。 2. **认证** – 检查 `Received-SPF` 和 `Authentication-Results` 头信息，以确定 SPF、DKIM 和 DMARC 的通过/失败状态。 3. **头信息取证** – 从 `Received` 头信息中重建 SMTP 中继链。对源 IP 进行地理定位，并检查其是否为托管/代理指标。 4. **提取 URL** – 从纯文本和 HTML 正文中提取所有 URL。检测并展开已知的短链接域名（如 bit.ly, t.co 等）。 5. **提取附件** – 将 MIME 附件保存到磁盘并计算其 SHA-256 哈希值。 6. **二维码扫描** – 扫描图片附件中嵌入的二维码。发现的任何 URL 都将输入到分析流程中。 7. **启发式分析** – 检查域名是否存在品牌冒充、可疑关键词、高熵值、同形字攻击、域名年龄和重定向链。 8. **显示名称欺骗** – 检查发件人显示名称是否包含与发件人域名不匹配的受保护品牌名称。 9. **相似域名检测** – 使用 Levenshtein 编辑距离将 URL 域名与受保护品牌进行比对（≤ 2 则触发检测）。 10. **威胁情报** – 在 VirusTotal 和 AlienVault OTX 中检查每个 URL 域名和附件哈希值。在 AbuseIPDB 和 Spamhaus 中检查 IP。SecurityTrails 提供被动 DNS 数据。 11. **AI 分类** – 将邮件发送至 Google Gemini 进行独立的钓鱼/可疑/合法判定。 12. **风险评分** – 根据所有指标计算加权分数（0-100），并映射为判定结果：**LOW**（低）、**MEDIUM**（中）、**HIGH**（高）或 **CRITICAL**（严重）。 13. **报告** – 生成包含所有发现的 Markdown 格式报告，并发送回 Telegram 聊天。 ## 风险评分细则 | 指标 | 分值 | |-----------|--------| | SPF 失败/软失败/无 | +15 | | DKIM 失败/无 | +15 | | DMARC 失败/无 | +20 | | 恶意 URL (每个 URL) | +20 | | 可疑 URL (每个 URL) | +10 | | 短链接 (每个 URL) | +5 | | 恶意附件哈希值 | +25 | | AlienVault OTX 脉冲命中 | +10 | | URL 中的品牌冒充 | +25 | | 域名中的可疑关键词 | +15 | | 显示名称欺骗 | +20 | | 相似域名 (Levenshtein) | +20 | | 包含 URL 的二维码 | +15 | | 黑名单 IP (AbuseIPDB/Spamhaus) | +20 | | AI 判定: 钓鱼 | +25 | | AI 判定: 可疑 | +10 | | SMTP 中继异常 | +10–15 | 分数上限为 100。阈值可通过环境变量进行配置。 ## 许可证 本项目仅供教育目的。请负责任地使用，并遵守你所在组织的安全策略。

标签：AbuseIPDB, IOC提取, Python, SOC工具, Telegram机器人, VirusTotalAPI, 事件响应自动化, 企业安全, 威胁情报, 安全报告生成, 安全运营, 实时查询, 库, 应急响应, 开发者工具, 扫描框架, 搜索语句（dork）, 数字取证, 无后门, 漏洞发现, 电子邮件安全, 网络安全, 网络资产管理, 自动化分类, 自动化脚本, 诱饵检测, 请求拦截, 逆向工具, 钓鱼邮件分析, 隐私保护, 风险评分