akshay1389/email-phishing-detection

# 高级电子邮件钓鱼检测器 V3 该工具分析电子邮件文件（.eml、.msg），通过多角度方法检测潜在的钓鱼尝试，包括头部分析、内容检查、外部威胁情报（VirusTotal）、图像的光学字符识别（OCR）以及可选的 AI 评估。 项目参考：https://github.com/akshayb220194/email-phishing-detector-test ## 功能 ### 全面解析 - 从 .eml 和 .msg 文件中提取头部、正文（文本/HTML）、附件和结构。 ### 头部分析 - 解码标准头部（主题、发件人、收件人、回复地址）。 - 从头部解析身份验证结果（SPF、DKIM、DMARC）。 - 执行 DNS 查询以获取 DMARC 策略（需要 dnspython）。 - 识别可疑模式（例如发件人与回复地址不匹配）。 - 从 Received 头部提取原始 IP 地址。 ### 正文分析 - 提取纯文本和 HTML 内容。 - 识别和提取 URL。 - 检测 HTML 中的可疑元素（表单、隐藏文本、JavaScript、缩短链接）。 - 分析链接是否存在品牌冒充和域名滥补（需要 python-Levenshtein）。 ### 附件分析 - 提取附件元数据（文件名、大小、内容类型）。 - 生成 MD5、SHA1、SHA256 哈希。 - 识别可疑附件类型/名称（可执行文件、压缩包、双扩展名）。 - OCR 集成：从图像附件中提取文本（需要 Tesseract、Pillow、pytesseract）。 ### VirusTotal 集成 - 将提取的 IP、URL 和附件哈希与 VirusTotal API v3 进行比对。 - 使用异步请求（aiohttp）提升效率。 - 在本地 SQLite 数据库中缓存 VT 结果，以减少 API 调用并加快重复分析速度。 ### AI 评估（可选） - 将详细报告发送至配置的 AI 模型（例如通过 OpenRouter）。 - 提示 AI 提供结构化 JSON 响应，包括： - 钓鱼评分（0-10） - 判定结果（CLEAN、SUSPICIOUS、MALICIOUS） - 置信度评分 - 详细解释 - 可疑元素列表 - 识别出的品牌 ### 报告 - 在控制台生成带颜色的详细报告（colorama）。 - 可选择将完整分析结果（包括 AI 响应）保存为 JSON 文件。 ## 安装 ### 1. 克隆仓库 ``` git clone cd ``` ### 2. 创建虚拟环境（推荐） ``` python -m venv venv source venv/bin/activate # On Windows use venv\Scripts\activate ``` ### 3. 安装依赖 ``` pip install -r requirements.txt ``` ### 4. 安装 Tesseract OCR 引擎 **Ubuntu/Debian：** ``` sudo apt update && sudo apt install tesseract-ocr tesseract-ocr-eng ``` **macOS：** ``` brew install tesseract tesseract-lang ``` **Windows：** 从 Tesseract OCR GitHub 下载安装程序，并在安装过程中确保将 Tesseract 添加到系统 PATH。 ### 5. 配置 API 密钥 **VirusTotal API 密钥：** ``` export VIRUSTOTAL_API_KEY="your_vt_api_key" # Windows (cmd): set VIRUSTOTAL_API_KEY=your_vt_api_key # Windows (PowerShell): $env:VIRUSTOTAL_API_KEY="your_vt_api_key" ``` **AI 提供商 API 密钥（可选，例如 OpenRouter）：** ``` export OPENROUTER_API_KEY="your_ai_api_key" ``` ### 6. 检查配置 修改 config/config.py 以进行更多设置： - AI_MODEL：指定 AI 模型。 - DATABASE_PATH：设置数据库位置。 - CACHE_DURATION_SECONDS：设置 VirusTotal 缓存时长。 - OCR_ENABLED、OCR_LANGUAGES、TESSERACT_CMD。 - LOG_LEVEL。 ## 使用 从命令行运行分析： ``` python main.py -f [options] ``` ### 参数 - -f, --file：要分析的电子邮件文件（.eml 或 .msg）路径（必需）。 - --ai：启用基于 AI 的分析（可选）。 - -o, --output：将分析结果保存为 JSON 文件（可选）。 - -v, --verbose：启用详细控制台输出（可选）。 ### 示例 基础分析： ``` python main.py -f suspicious_email.eml ``` 启用 AI 并将结果保存为 JSON： ``` python main.py -f urgent_invoice.msg --ai -o report.json ``` 带详细控制台的报告： ``` python main.py -f newsletter.eml -v ``` ## 流程图 ``` +-------------------------+ +-------------------------+ +-----------------------+ | Start (main.py) | ---> | Parse Command Line Args| ---> | Validate Input File | | (Input: email file path)| | (file, --ai, -o, -v) | | (Exists? Size? Ext?) | +-------------------------+ +------------+------------+ +-----------+-----------+ | | (Error -> Exit) | | v v (OK) +-------------------------+ +------------+------------+ +-----------+-----------+ | Initialize Components | <--+ | Run Full Analysis Async | | Parse Email File | | (DB Manager, VT Client)| | (run_full_email_analysis)| ---> | (email_parser.py) | +-------------------------+ +------------+------------+ +-----------+-----------+ | | (Error -> Exit) | | v v (OK) +-------------------------+ +-------------------------+ +-----------+-----------+ | Generate File Hashes | | Start Concurrent Tasks | | EmailMessage Obj | | (security_analyzer) | <--- | (analyze_headers, | | Raw Content String | +-------------------------+ | analyze_body, | +-----------------------+ | analyze_attachments) | +------------+------------+ | v (Await Tasks) +---------------------------+ +-------------------------+ +-------------------------+ | Analyze Attachments | <---| | ---> | Analyze Headers | | - Metadata, Hashes | | Gather Task Results | | - Decode, Auth, IPs | | - OCR (if image, enabled) | | (Handle Exceptions) | | - VT IP Checks | | - VT Hash Checks | +-----------+-------------+ | - Suspicious Indicators | | (security_analyzer) | | | (security_analyzer) | +---------------------------+ | +-------------------------+ | | | |------------------------------------|------------------------------------| | v +-------------------------+ +-------------+-----------+ +-------------------------+ | Analyze Body | <----| Combine Analysis Data | | AI Analysis (Optional) | | - Text/HTML Content | +-------------------------+ ---> | - Build Prompt | | - Links, URL Checks (VT)| | | - Call AI API | | - Typosquatting | | | - Parse JSON Response | | - Brand Impersonation | | | (ai_integration.py) | | (security_analyzer) | | +-----------+-------------+ +-------------------------+ | | (Store AI Result) v +-------------------------+ +-------------------------+ +-----------+-----------+ | Generate Console Report| <--- | Finalize Results Dict | | Save Results to JSON? | | (report_generator.py) | | (Set Status, Duration) | ---> | (If -o specified) | +-------------+-----------+ +------------+------------+ +-----------------------+ | | v v +-------------+-----------+ +----------+----------+ | Display Report to User | | Prune Database Cache| +-------------------------+ +---------------------+ | v +-------------+-----------+ | End (Exit Code) | +-------------------------+ ``` ## 核心组件 - **main.py**：协调分析流程。 - **config/config.py**：管理 API 密钥和设置。 - **src/email_parser.py**：解析 .eml 和 .msg 文件。 - **src/database_manager.py**：在 SQLite 中管理 VirusTotal 缓存。 - **src/security_analyzer.py**：执行头部、正文和附件分析。 - **src/ai_integration.py**：处理基于 AI 的评估。 - **src/report_generator.py**：生成控制台报告。 ## 待办事项 / 潜在改进 - **DMARC 对齐检查**：实现完整的 DMARC 验证。 - **URL 解码**：集成服务以解析缩短的 URL。 - **沙箱集成**：提交附件到沙箱环境。 - **HTML 渲染**：使用 BeautifulSoup 和 html2text 改进解析。 - **配置更新**：将已知域名和可疑 TLD 移至外部配置文件。 - **错误处理**：在部分失败时提高容错能力。 - **测试**：添加单元测试和集成测试。 ## 关于开发者 该项目由 Akshay Basavalingaiah 维护，他是一名后端软件工程师，拥有超过 5 年构建可扩展 API、微服务和分布式系统的经验。凭借在 Python、Golang 和 Java 方面的扎实背景，Akshay 专注于开发高性能安全工具和数据处理工作流。 联系方式： - 邮箱：akshayb220194@gmail.com - GitHub：akshayb220194 - LinkedIn：akshay-basavalingaiah

标签：AI评估, API安全, Ask搜索, CDN识别, DKIM, DMARC, DNS查询, JSON输出, MD5, OCR, OpenRouter, Pillow, SHA1, SHA256, SPF, SQLite, Tesseract, URL检测, VirusTotal, 光学字符识别, 压缩包检测, 双扩展名, 反钓鱼, 可执行文件检测, 品牌冒充, 哈希计算, 图像文本提取, 域名钓鱼, 头部分析, 威胁情报, 开发者工具, 异步请求, 机器学习评分, 结构化报告, 缓存, 逆向工具, 邮件分析, 邮件安全, 邮件解析, 钓鱼检测, 附件分析