SmykRwt/PhishIntel-AI

# PhishIntel AI ### 使用 DistilBERT 的可解释多模态钓鱼情报与威胁审计系统 PhishIntel 是一个 AI 驱动的钓鱼分析平台，它结合了经典机器学习、基于 transformer 的 NLP、基于规则的威胁检测以及 LLM 推理，以生成可解释的钓鱼情报报告。 本项目旨在作为一个端到端原型，用于检测可疑电子邮件、粘贴的文本消息、上传的 `.eml` 文件以及可疑内容的截图。 ## 功能 - 用于钓鱼分析 API 的 FastAPI 后端 - 用于扫描、分析和历史审计审查的 Streamlit 仪表板 - 使用 DistilBERT、经典 ML 和基于规则评分的混合检测 - 针对可疑词汇、规则、URL 和 header 的可解释指标 - URL typosquatting（域名抢注/仿冒）和可疑域名检查 - SPF、DKIM、DMARC、发件人和回复至 header 分析 - 通过 Tesseract 支持截图 OCR - 使用 Ollama 或 OpenAI 的可选 GenAI 分析师摘要 - 支持 PostgreSQL（通过 Docker Compose）并在本地运行时回退至 SQLite - 在 Docker 模式下用于实验跟踪的 MLflow 服务 ## 架构 ``` graph TD User([User / Analyst]) --> Frontend[Streamlit Dashboard] Frontend --> Backend[FastAPI Backend] Backend --> Parser[Email Parser] Backend --> OCR[Tesseract OCR] Backend --> Rules[Heuristic Rules Engine] Backend --> Headers[Header Analyzer] Backend --> URLs[URL Analyzer] Backend --> ML[Hybrid ML Engine] ML --> BERT[DistilBERT] ML --> Classical[Classical ML Models] Backend --> Scorer[Threat Scorer] Scorer --> LLM[Ollama / OpenAI Analyst] Backend --> DB[(PostgreSQL / SQLite)] Backend --> MLflow[MLflow Tracking] ``` ## 技术栈 - **后端：** FastAPI、SQLAlchemy、Pydantic - **前端：** Streamlit - **ML/NLP：** PyTorch、Transformers、scikit-learn、XGBoost - **可解释性：** Token 归因和规则级别的解释 - **数据库：** Docker 中的 PostgreSQL，本地回退至 SQLite - **OCR：** 通过 `pytesseract` 调用 Tesseract - **实验跟踪：** MLflow - **容器化：** Docker Compose ## 威胁分类输出 系统在三个级别报告钓鱼检测结果： 1. 来自组合威胁评分器的**最终风险判定**： - `Safe` - `Suspicious` - `High Phishing Risk` 2. 来自 Ollama/OpenAI 或确定性后备方案的 **GenAI 分析师威胁类型**： - `Safe Email` - `Suspicious Message` - `Potential Phishing Scam` - `Credential Harvesting` - `Brand Impersonation` - `Financial Wire Fraud` - 由配置的 LLM 生成的其他密切相关的威胁标签 3. 来自启发式引擎的**基于规则的技术指标**，例如： - 凭证收集诱饵 - 紧急或施压策略 - 冒充模式 - 财务请求诱饵 - 奖品或奖励诱饵 - 密码重置诱饵 - 账号暂停威胁 - 发票或虚假账单诈骗 - 礼品卡索要 - 二维码钓鱼 - 危险附件风险 对于没有可疑规则、URL 或 header 异常的良性文本，后备方案报告会将其分类为 `Safe Email`，严重程度为 `Low`。 ## 仓库结构 ``` . |-- backend/ | |-- app/ | | |-- api/endpoints/ # Analysis, history, dashboard, health APIs | | |-- core/ # App settings and lazy-loaded dependencies | | |-- database/ # SQLAlchemy models and sessions | | |-- llm/ # GenAI report generation | | |-- ml/ # Datasets, training, inference, benchmarks | | |-- rules/ # Heuristic phishing rules | | |-- schemas/ # Pydantic request/response models | | |-- services/ # Parser, OCR, URL, header, and scoring services | | `-- main.py # FastAPI application entry point |-- frontend/ | `-- streamlit_app.py # Streamlit user interface |-- docker/ | `-- backend.Dockerfile # Backend image definition |-- datasets/ # Train, validation, and test datasets |-- experiments/ # Benchmark outputs |-- docker-compose.yml # Local container orchestration |-- requirements.txt # Root requirements redirect |-- spam.csv # Base dataset `-- README.md ``` ## 开始使用 ### 前置条件 - Python 3.10 或更高版本 - Docker Desktop，如果使用 Docker 运行 - Tesseract OCR，如果在 Docker 外部本地运行 OCR - 可选：在本地运行 Ollama 以获取本地 LLM 摘要 - 可选：OpenAI API key，用于基于 OpenAI 的摘要 ## 使用 Docker Compose 运行 Docker Compose 会启动 PostgreSQL、MLflow、FastAPI 和 Streamlit。 ``` docker compose up --build ``` 打开 Streamlit 应用： ``` http://localhost:8501 ``` 其他服务： - FastAPI 文档：`http://localhost:8000/docs` - MLflow UI：`http://localhost:5000` - 后端健康状态：`http://localhost:8000/api/v1/health` 在保留扫描历史记录的同时停止容器： ``` docker compose down ``` 要重置 Docker 扫描历史记录，请删除 PostgreSQL volume： ``` docker compose down -v ``` ## 不使用 Docker 在本地运行 创建并激活虚拟环境： ``` python -m venv venv ``` Windows PowerShell： ``` .\venv\Scripts\Activate.ps1 ``` macOS/Linux： ``` source venv/bin/activate ``` 安装依赖项： ``` pip install -r backend/requirements.txt ``` 启动 FastAPI 后端： ``` uvicorn backend.app.main:app --reload ``` 在第二个终端中启动 Streamlit 前端： ``` streamlit run frontend/streamlit_app.py ``` 本地应用 URL： - Streamlit UI：`http://localhost:8501` - FastAPI 文档：`http://localhost:8000/docs` 未设置 `DATABASE_URL` 时，后端将回退到项目根目录下的 `phishing_db.sqlite`。 重置本地扫描历史记录： ``` Remove-Item .\phishing_db.sqlite ``` ## 配置 配置从环境变量或可选的 `.env` 文件中读取。 ``` DATABASE_URL=sqlite+aiosqlite:///./phishing_db.sqlite OLLAMA_HOST=http://localhost:11434 OLLAMA_MODEL=llama3 OPENAI_API_KEY= OPENAI_MODEL=gpt-4o-mini MLFLOW_TRACKING_URI=sqlite:///mlflow.db TESSERACT_CMD= ``` 在 Docker 模式下，`DATABASE_URL`、`OLLAMA_HOST` 和 `MLFLOW_TRACKING_URI` 由 `docker-compose.yml` 提供。 ## API 概述 主要 endpoint 位于 `/api/v1` 下。 | 方法 | Endpoint | 描述 | | --- | --- | --- | | `GET` | `/api/v1/health` | 后端健康检查 | | `POST` | `/api/v1/analyze/email` | 分析粘贴的电子邮件或消息文本 | | `POST` | `/api/v1/analyze/email/upload` | 分析上传的 `.eml` 文件 | | `POST` | `/api/v1/analyze/screenshot` | 使用 OCR 提取截图文本并进行分析 | | `GET` | `/api/v1/analyze/{analysis_id}` | 检索一条已保存的分析记录 | | `GET` | `/api/v1/history` | 列出已保存的分析记录 | | `GET` | `/api/v1/dashboard` | 聚合仪表板指标 | | `GET` | `/api/v1/metrics` | 基本的后端指标 | ## 模型训练与基准测试 运行基准测试模块以训练/评估可用模型并生成报告： ``` python -m backend.app.ml.benchmark ``` 输出将写入 `experiments/` 目录。像 `best_model.pkl` 和 `bert_model/` 这样的训练产物会被 Git 忽略，因为它们可能非常大且取决于特定环境。 ## 历史记录与数据隐私 此原型不包含身份验证或单用户账户。扫描历史由连接到同一后端数据库的所有人共享。 - Docker 历史记录存储在 PostgreSQL 的 `pgdata` volume 中。 - 本地历史记录存储在 `phishing_db.sqlite` 中。 - 使用 `docker compose down -v` 或删除 `phishing_db.sqlite` 以重置历史记录。 身份验证、单用户历史隔离、基于角色的访问控制以及 UI 上的清除历史记录功能是计划中的未来增强项。 ## 当前局限性 - 没有登录系统或单用户历史隔离 - OCR 质量取决于本地或容器的 Tesseract 设置 - LLM 报告需要连接到 Ollama/OpenAI，否则将回退到确定性摘要 - 大型模型文件不打算提交到 Git - 这是一个研究/原型系统，不应用作唯一的生产环境安全控制手段 ## 未来改进 - 用户身份验证和单用户审计历史 - Streamlit UI 中的清除历史记录选项 - 用于自动化测试和容器构建的 CI/CD pipeline - 针对 API endpoint 和评分逻辑的扩展测试套件 - 更好的模型产物管理 - 更多的钓鱼数据集和评估报告 ## 作者 Samyak Rawat | AI/ML 工程师 | Thapar Institute of Engineering and Technology

标签：Apex, AV绕过, FastAPI, Kubernetes, 凭据扫描, 威胁情报, 开发者工具, 机器学习, 测试用例, 系统调用监控, 网络安全, 请求拦截, 逆向工具, 钓鱼检测, 隐私保护