TheManishCode/Explainable-Hybrid-Threat-Intelligence-Engine-for-Malware-and-URL-Analysis

# MalwareGuard - 分层网络安全检测系统 MalwareGuard 是一个模块化、分层的网络安全检测系统，包含 FastAPI 后端、通用 URL/文件威胁引擎、PE 模型丰富化、结构化指标、SHA256 缓存、URL 接入，以及带有电影级产品落地页和操作员控制台的 Angular 19 前端。 在进行 AI 辅助修改之前，请阅读 `AI_CONTEXT.md`。在对代码、文档、配置或构建进行任何更改后，必须在结束运行前更新该文件。生产环境规范要求：始终在目标 runtime 中运行并验证应用程序，更新 README/requirements/gitignore 及其他所需的项目元数据，并清理工作过程中遇到的未使用或生成的冗余文件。 ## 核心亮点 | 领域 | 功能说明 | | --- | --- | | 文件扫描 | 上传 PE 文件、脚本、归档文件、文档、ELF/Mach-O/通用二进制文件或文本制品，以进行静态分层分析 | | URL 扫描 | 分析 HTTP/HTTPS、基于 IP 的、GitHub blob/raw/release 链接以及 `.onion` URL；安全地获取符合条件的 clearnet 内容以进行本地静态检查 | | 分层引擎 | 包括 Normalizer、静态分析器、语义意图引擎、行为推断、上下文引擎、加权评分和判定生成 | | PE 模型丰富化 | PE 样本将额外使用位于 `models/lgbm.pkl` 的已训练 LightGBM 模型及 SHAP 元数据进行评分 | | 解释说明 | 输出结构化指标、各层分数、推理过程和行为假设 | | 缓存 | 按 SHA256 将扫描结果存储在 `cache/` 中，TTL 为七天 | | 前端 | Angular 落地页体验，包含 GSAP/ScrollTrigger 动画、扫描工作区、结果标签页和历史记录仪表板 | | API | 用于扫描、健康检查、历史记录和缓存管理的 FastAPI endpoint | ## 快速开始 使用 Python 3.9 或更高版本。自带的 conda 工作流已在 `malware` 环境中使用 Python 3.9.25 进行了验证。 安装 Python 依赖项： ``` cd malware-classifier pip install -r requirements.txt ``` 如果缺少 `models/lgbm.pkl`，请训练模型： ``` python train.py --data-dir ..\ember-2018 ``` 构建 Angular 前端： ``` cd frontend npm install npm run build cd .. ``` 启动 FastAPI 服务器： ``` uvicorn src.api.app:app --host 0.0.0.0 --port 8000 ``` 打开 `http://localhost:8000`。根路由显示产品落地页；扫描器可在 `/scanner` 访问。 ## 开发说明 运行 API： ``` uvicorn src.api.app:app --reload --port 8000 ``` 运行 Angular 并启用热重载： ``` cd frontend npm start ``` 打开 `http://localhost:4200`。Angular 开发根目录显示落地页，并链接到 `/scanner` 和 `/history`。 当 Angular 在端口 `4200` 上运行时，`ApiService` 会调用 `http://localhost:8000`。生产环境构建使用同源相对 API 调用，并由 FastAPI 从 `frontend/dist/frontend/browser` 提供服务。 ## API 参考 | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/health` | 模型/API 就绪状态及已完成的扫描计数 | | `POST` | `/scan/file` | Multipart 文件上传，带有可选的 `threshold` 查询参数 | | `POST` | `/scan/url` | URL 扫描，JSON 请求体为 `{ "url": "...", "threshold": 0.5 }` | | `POST` | `/scan` | 旧版原始 2,381 个值的特征向量评分 | | `GET` | `/history` | 当前 API 进程的扫描历史记录 | | `GET` | `/cache/stats` | 缓存条目计数、大小、目录和 TTL | | `DELETE` | `/cache` | 清除已缓存的扫描结果 JSON 文件 | 扫描响应包含现有的控制台字段，以及用于结构化分层引擎输出的 `indicators`、`reasoning` 和 `analysis_layers`。 文件扫描示例： ``` curl -X POST http://localhost:8000/scan/file ` -F "file=@sample.exe" ` -F "threshold=0.5" ``` ## 项目结构 ``` malware-classifier/ run.bat Interactive Conda environment launcher frontend/ Angular 19 standalone SPA src/app/ pages/landing/ Cinematic GSAP product landing page pages/scan/ Scanner workspace pages/history/ Session history dashboard services/ API service models/ TypeScript interfaces src/ api/app.py FastAPI app and SPA serving config/ settings.py Centralized system configurations weights.py Heuristic score weights and confidence rules core/ indicators.py Structured ThreatIndicator class scoring_engine.py Layer-aware weighted scoring and verdict gates detection/ normalizer.py URL/file canonicalization, decoding, type detection, hashes, and strings static_analyzer.py Low-level URL/file indicators semantic_analyzer.py Intent inference from grouped evidence behavior_analyzer.py Safe behavior inference without execution context_engine.py Infrastructure and weak safety context universal_engine.py End-to-end layered detection pipeline services/ fetcher.py SSRF-safe HTTP fetcher with DNS and redirect validation url_analyzer.py URL scanner service backed by the universal engine file_analyzer.py Universal file scanner with optional PE model/SHAP enrichment sandbox_service.py Sandboxed validation context service utils/ validators.py SSRF and .onion validation helpers logger.py Configured module logger helpers scanner.py Scanner facade for URL/file orchestration sandbox.py Sandbox facade for PE validation helpers url_fetcher.py Fetcher Facade (download file safely) cache.py SHA256 JSON cache features/ pe_extractor.py PE to EMBER-style feature vector explainer.py Human-readable feature explanations inspector.py Feature group analysis models/ lgbm_model.py LightGBM train/load/predict helpers threshold.py Threshold tuning utilities data/ EMBER data loading and splitting evaluation/ Metrics, plots, SHAP reports models/ Trained model artifacts reports/ Evaluation reports and images cache/ Local scan cache train.py Training pipeline predict.py CLI vector scoring AI_CONTEXT.md Required handoff file for future AI runs ``` ## 安全模型 - 样本永远不会被执行。 - PE 解析在扫描路径中是只读且完全在内存中进行的。 - 脚本和 URL 行为仅根据静态证据和解码后的制品进行推断。 - 上传和下载的大小上限为 50 MB。 - URL 获取仅允许 HTTP/HTTPS clearnet 主机，阻止直接获取 `.onion`，在请求前解析 DNS，阻止解析到的私有/内部地址，并手动验证重定向。 - `.onion` URL 被接受进行 URL 级别分析，并记录为匿名基础设施，默认情况下不被视为恶意。由于直接获取 onion 内容被刻意阻止，因此仅限 onion 的结果会被报告为可疑/未验证，而不是正常。 - GitHub `blob`、`raw` 和 release 下载链接会被规范化为可直接下载的内容。如果无法获取具备 payload 能力的 URL，判定结果将变为可疑/未验证，而非良性。 - Sandbox 助手会清理名称，并可在需要磁盘隔离时创建只读临时上下文。 ## 当前局限性 - 仅限静态分析；行为预测是基于静态和语义指标推断出的假设。 - 这不是动态 sandbox、特征码数据库或 VirusTotal 的替代品。 - 加壳或高度混淆的恶意软件可能会逃避纯静态分析。 - 除非以后添加外部情报提供商，否则 URL 信誉和历史流行度均为本地/离线启发式判断。 ## 验证 当前的前端构建已通过以下验证： ``` cd frontend npm run build ``` 落地页、扫描器和历史记录路由也已在本地 Microsoft Edge 的桌面和移动端视口尺寸下进行了检查。 ## 许可证 仅供教育和研究使用。

标签：Angular, Apex, AV绕过, DNS 反向解析, FastAPI, Go语言工具, Grype, 云安全监控, 威胁情报, 开发者工具, 搜索语句（dork）, 机器学习, 网络信息收集, 逆向工具, 静态分析