useru1k/email-analysis

# 用于检测钓鱼与恶意邮件的邮件分析系统 一个具备威胁评分、URL/附件安全检查及全面安全分析的邮件分析工具，用于检测钓鱼和恶意邮件。 ## 功能 - **威胁评分计算**：基于多个安全因素，进行综合的 0-100 威胁评分 - **邮件认证分析**：SPF、DKIM 与 DMARC 验证 - **IP 分析**： - 地理位置追踪 - 集成 AbuseIPDB 进行黑名单检查 - IP 信誉评分 - **URL 分析**： - 短链接展开 - 集成 VirusTotal 扫描 URL 与文件哈希 - 可疑链接检测 - 使用 `tldextract`、`python-whois` 和 `dnspython` 进行域名情报分析（WHOIS、DNS 记录） - **附件分析**： - 高风险文件类型检测 - 集成 MalwareBazaar 进行恶意软件检测 - SHA-256 哈希计算 - **本地哈希缓存**：存储之前的 VirusTotal 结果（加速重复扫描） - **恶意软件报告搜索**：自动查找并链接到已标记文件的分析报告 - **邮件头分析**：提取并验证邮件头 - **双模式运行**：在线模式（需API集成）与离线模式 ## 安装说明 ### 前置条件 - Python 3.8 或更高版本 - pip（Python 包安装器） - Git（用于克隆仓库） ### 分步安装指南 1. **克隆仓库** ``` git clone https://github.com/useru1k/email-analysis.git cd email-analysis ``` 2. **创建虚拟环境**（推荐） Windows 系统： ``` python -m venv venv venv\Scripts\activate ``` Linux/Mac 系统： ``` python3 -m venv venv source venv/bin/activate ``` 3. **安装依赖项** ``` pip install -r app/requirement.txt ``` 4. **配置环境变量**（可选，用于在线模式） 在根目录下创建一个 `.env` 文件： ``` VIRUSTOTAL_API_KEY=your_virustotal_api_key_here ABUSEIPDB_API_KEY=your_abuseipdb_api_key_here IPAPI_URL=http://ip-api.com/json/ ``` **注意**： - VirusTotal API 密钥可选，但建议用于 URL 和文件哈希扫描 - AbuseIPDB API 密钥可选，但建议用于 IP 信誉检查 - 即使没有 API 密钥，您也可以使用应用程序的离线模式 ## 运行应用程序 ### 运行测试 项目包含一个小型的 pytest 测试套件，用于测试核心服务功能。 ``` pip install pytest # or use your environment's dependency manager pytest -q ``` ### 启动服务器 **运行 FastAPI 服务器** ``` uvicorn app.main:app --reload ``` 或指定特定主机和端口： ``` uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload ``` **访问应用程序** - 打开您的网页浏览器 - 访问地址：`http://localhost:8000` ## 威胁评分计算 威胁评分在 0-100 的尺度上计算，分数越高表示威胁程度越大。该评分系统会评估多个安全因素： ## 配置 ### 环境变量 | 变量名 | 描述 | 是否必需 | 默认值 | |--------|------|----------|--------| | `VIRUSTOTAL_API_KEY` | 用于 URL 和文件（哈希查找）扫描的 VirusTotal API 密钥 | 是 | 空 | | `ABUSEIPDB_API_KEY` | 用于 IP 信誉检查的 AbuseIPDB API 密钥 | 否 | 空 | | `GOOGLE_SEARCH_API_KEY` | 用于恶意软件报告搜索的 Google 自定义搜索 API 密钥 | 否 | 空 | | `GOOGLE_SEARCH_CX` | 用于恶意软件报告搜索的 Google 自定义搜索引擎 ID | 否 | 空 | | `IPAPI_URL` | IP 地理位置 API 端点 | 否 | `http://ip-api.com/json/` | | `HASH_CACHE_PATH` | 存储/检索缓存哈希报告的文件路径 | 否 | `hash_cache.json` | ### 分析模式 - **在线模式**： - 展开缩短的 URL - 通过 AbuseIPDB 检查 IP - 使用 VirusTotal 扫描 URL 和附件哈希 - 执行 WHOIS 和 DNS 查询 - 完整功能需要 API 密钥 - **离线模式**： - 分析邮件结构和头部 - 检测高风险附件和链接 - 基于本地分析计算威胁评分 - 无需外部 API 调用 ## 项目结构 ``` email-analysis/ ├── app/ │ ├── __pycache__/ │ ├── main.py # FastAPI application and routes (thin, orchestrates services) │ ├── config.py # application configuration and settings │ ├── services/ # business logic modules (parsers, analysis, scoring) │ │ ├── parser.py │ │ ├── ip_analysis.py │ │ ├── url_analysis.py │ │ ├── attachment_analysis.py │ │ ├── auth_analysis.py │ │ └── threat_scoring.py │ ├── requirement.txt # Python dependencies │ ├── static/ │ │ └── style.css # Application styles │ ├── templates/ │ │ ├── index.html # Main upload interface │ │ └── result.html # Analysis results page │ └── venv/ # Virtual environment ├── sample/ # Sample email files for testing ├── .env # Environment variables (create this) └── README.md # This file ``` ## 使用的技术 - **FastAPI**：用于构建 API 的现代 Web 框架 - **Jinja2**：用于 HTML 渲染的模板引擎 - **dnspython**：用于域名查询的 DNS 工具包 - **requests/httpx**：用于 API 集成的 HTTP 客户端库 - **tldextract**：从 URL 中提取域名 - **python-dotenv**：环境变量管理 ## 外部集成 - **VirusTotal**：URL 和域名信誉检查 - **AbuseIPDB**：IP 地址信誉和滥用报告 - **ip-api.com**：IP 地理位置服务 - **Whois/DNS**：使用 `python-whois` 和 `dnspython` 进行本地查询 ## 使用示例 ### 分析邮件文件 1. 将邮件保存为 `.eml` 格式 2. 通过网页界面上传文件 3. 选择分析模式 4. 查看全面的威胁分析和评分 ### 分析原始邮件内容 1. 复制原始邮件头和正文 2. 粘贴到网页界面的文本区域 3. 选择分析模式 4. 即时获取安全分析结果 ## 贡献 欢迎贡献！请随时提交 Pull Request。 ## 免责声明 本工具仅用于安全分析和教育目的。请务必通过多个来源核实结果，并在处理潜在恶意邮件时保持谨慎。

标签：运行时操纵, 逆向工具