atharva07-cyber/ThreatLens-Lite

# 🔍 ThreatLens-Lite — SOC 分析师分诊工具包     ## 📌 这是什么？ ThreatLens-Lite 是一个作品集项目，模拟了 SOC L1 分析师每天都要执行的三项任务： 1. **分诊用户报告或被过滤器拦截的可疑链接** 2. **调查转发到安全收件箱的钓鱼邮件** 3. **在接触样本之前，根据已知的恶意软件数据库检查文件 hash** 它特意缩减了完整的生产级 SOC 技术栈范围——其目的是展示*推理过程*，而不是取代真实的 SIEM/EDR。 ## ⚡ 功能 | 模块 | 功能说明 | |---|---| | 🔗 **URL 扫描器** | 从 URL 中提取 20 个词法/结构特征（IP 字面量主机、`@` 欺骗、连字符、短链接、可疑关键词、HTTPS 等），并使用训练好的 Gradient Boosting 分类器对其进行评分 | | 📧 **邮件分析器** | 标记紧急性话术、凭据窃取短语、通用问候语、品牌冒充、链接文本不匹配以及 Reply-To/From 欺骗 | | 🦠 **Hash 检查器** | 通过 VirusTotal 公共 API 查询 MD5/SHA1/SHA256 hash，并返回检测率及判定结果 | | 📄 **报告导出** | 每次扫描都可以下载为格式化的 PDF 事件报告（包含判定结果、风险评分、发现的问题、原始特征/检测数据） | 除了可选的需要您自己的免费 API key 的 VirusTotal 查询外，所有操作均**离线**运行。 ## 🖥️ 截图 仪表盘风格的分析师控制台：包含一个主标题栏、胶囊式的扫描器标签页、颜色编码的判定卡片（安全/可疑/恶意）、风险仪表盘、快速统计卡片、解释*为何*被标记的问题列表，以及每个结果上的 **Download Report (PDF)** 按钮。  ## 🏗️ 项目结构 ``` threatlens/ ├── app.py # Flask app + API routes ├── train_model.py # Trains the URL phishing classifier ├── requirements.txt ├── scanner/ │ ├── url_features.py # Lexical feature extraction (no network calls) │ ├── url_scanner.py # ML verdict + explainable heuristic fallback │ ├── email_scanner.py # Phishing-pattern email analysis │ ├── hash_checker.py # VirusTotal API integration │ └── report_generator.py # PDF incident report builder (reportlab) ├── data/ │ └── generate_sample_dataset.py # Builds a synthetic labeled URL dataset ├── model/ # Trained model + metrics (generated, gitignored) └── templates/ └── index.html # Analyst console UI ``` ## 🚀 如何在本地运行 ### 1. 克隆并安装 ``` git clone https://github.com/atharva07-cyber/threatlens-lite.git cd threatlens-lite pip install -r requirements.txt ``` ### 2. 生成数据集并训练 URL 模型 ``` python data/generate_sample_dataset.py python train_model.py ``` 这将创建 `data/urls.csv`（合成的钓鱼 URL 与合法 URL —— 参见下方的说明），并训练 `model/phishing_model.joblib`。 如果没有已训练的模型，URL 扫描器会自动回退到透明的基于规则的评分器，因此即使您在未进行任何训练前，该应用程序也能正常工作。 ### 3.（可选）为 hash 检查器设置 VirusTotal ``` export VT_API_KEY="your_key_here" # Windows: set VT_API_KEY=your_key_here ``` 在 [virustotal.com](https://www.virustotal.com) 获取免费 key → Profile → API Key。 免费层级：每天 500 次请求，每分钟 4 次。 ### 4. 运行应用程序 ``` python app.py ``` 打开 **http://127.0.0.1:5000** ## 🧪 关于训练数据（在面试展示前请阅读此说明） `data/generate_sample_dataset.py` 构建了一个**合成**数据集（根据已知的钓鱼/合法模式生成的 URL），从而使整个 pipeline 能够在零配置的情况下端到端运行。 它可以顺利训练，但仅基于合成数据训练的模型并不能代表真实的准确率——因为这些模式太容易被区分了。 要将其打造成您简历上极具说服力的 ML 成果： 1. 从 Kaggle 下载 [Web Page Phishing Detection Dataset](https://www.kaggle.com/datasets/shashwatwork/web-page-phishing-detection-dataset) 2. 将其保存为包含 `url` 和 `label` 列的 `data/urls.csv`（如果真实数据集的列名不同，请调整 `train_model.py` 中的加载器） 3. 重新运行 `python train_model.py` 4. 在您的 README 中报告来自 `model/metrics.json` 的真实指标 坦诚说明哪些数据来自真实数据，哪些来自合成数据，正是 SOC/安全面试官所看重的严谨态度。 ## 🔧 技术栈 - **后端** — Python 3, Flask - **机器学习** — scikit-learn (Gradient Boosting), pandas, numpy - **威胁情报** — VirusTotal API v3 - **前端** — HTML5, CSS3, 原生 JavaScript（无框架） ## 📚 展示的技能 - 钓鱼 URL 特征工程与分类 - 针对社会工程学指标的邮件标头/内容分析 - 威胁情报 API 集成 (VirusTotal) - 可解释的检测（每个判定结果都附带*原因*，而不仅仅是评分） - Flask REST API 设计 - SOC 分析师分诊工作流 ## 🗺️ 路线图 / 扩展此项目的想法 - [ ] 为邮件发现添加 MITRE ATT&CK 技术标记 - [ ] PDF/DOCX 附件扫描器（提取嵌入的链接/宏） - [ ] 对上传的文件进行 YARA 规则匹配 - [ ] 批量 CSV 上传 URL/hash - [ ] 用于一键部署的 Dockerfile ## ⚠️ 免责声明 专为**教育和作品集目的**而构建。不能替代真实的 SIEM/EDR/威胁情报平台。请勿在隔离的 VM 之外分析活跃的恶意软件样本。 ## 📄 许可证 MIT — 查看 [LICENSE](LICENSE)。

标签：Apex, Flask, Python, 威胁情报, 安全运营, 开发者工具, 扫描框架, 数据可视化, 无后门, 机器学习, 逆向工具, 钓鱼检测