LahsenAitOiahmane/Hexplain

# Hexplain — AI 辅助的二进制分析平台 **Hexplain** 是一个用于静态分析 PE/ELF/.NET 可执行文件的生产就绪平台，由大型语言模型 (LLM) 和检索增强生成 (RAG) 提供支持。它将不透明的二进制内容转化为带有可靠风险评分的通俗语言网络安全报告——使得专家和新手都能进行恶意软件分析。 ## 问题所在 可执行二进制文件的静态分析是网络安全中最专业、最耗时的技能之一。分析师通常需要： - 精通 x86/x64 汇编语言（2 年以上实践经验） - 了解 PE 和 ELF 文件格式、导入表、熵分析 - 熟练使用 Ghidra、IDA Pro、YARA 和 Mandiant Capa 等工具 - 手动关联多个互不相关工具的分析结果 - 对单个二进制文件进行彻底分析需要 4 到 8 个小时 Hexplain 通过自动化完整的分析 pipeline 并将原始技术输出转化为任何人都能理解的自然语言解释，从而消除了这些障碍。 ## 解决方案 一个统一的 pipeline，只需上传单个文件即可： 1. 依次运行 9 个静态分析模块（元数据、结构、可疑 API、字符串/IOC、YARA、Capa/MITRE ATT&CK、反编译、威胁情报、启发式评分） 2. 将汇总的结果发送给 LLM（通过 Groq 使用 Gemini 2.0 Flash 或 Llama-3.1）以生成自然语言报告 3. 将报告索引到本地 ChromaDB vector store 中 4. 提供一个上下文 RAG 聊天机器人，专门根据报告数据回答有关二进制文件的问题 ## 平台截图 **登录页面**  **分析 Pipeline — 实时进度**  **完整分析报告 (严重 — 93/100)**  **能力 (Capa/MITRE)、IOC 和二进制区段**  **反编译函数 — 并排显示反汇编 + 伪 C 代码**  **RAG 聊天机器人 — AI Copilot**  **导出 PDF**  ## 架构 ``` Client (Browser) | v Frontend (Next.js 14 — :3000) | v HTTP REST API (FastAPI — :8000) | \ | v Redis SQLite (hexplain.db) Broker | | ChromaDB (RAG embeddings) v Worker (Celery — concurrency=1) | |--- Module 1: Metadata + Entropy |--- Module 2: PE/ELF Structure (LIEF) |--- Module 3: Suspicious API Detection |--- Module 4: Strings + IOC Extraction |--- Module 5: YARA Rule Scanning |--- Module 6: Capa (MITRE ATT&CK) |--- Module 7: Ghidra / ILSpy Decompilation |--- Module 8: Threat Intel (VirusTotal, MalwareBazaar, OTX) |--- Module 9: Heuristic Risk Scoring (0-100) | v LLM Layer (Gemini 2.0 Flash / Groq Llama-3.1) | v RAG Index (ChromaDB + sentence-transformers all-MiniLM-L6-v2) External Services: VirusTotal API MalwareBazaar API AlienVault OTX Gemini / Groq ``` 所有容器通过隔离的 Docker bridge 网络 (`hexplain_net`) 进行通信。Redis 未在主机上暴露。隔离卷 (quarantine volume) 绝不会通过 HTTP 提供服务。 ## 技术栈 | 组件 | 技术 | |---|---| | 后端 API | FastAPI (Python), 异步, Pydantic v2 | | 任务队列 | Celery + Redis 7 | | 数据库 | 通过 SQLAlchemy 2.0 + Alembic 实现的 SQLite | | 二进制解析 | LIEF, pefile, pyelftools, capstone | | 特征检测 | YARA-Python (社区规则) | | 能力检测 | Mandiant Capa + MITRE ATT&CK | | 反编译 | Ghidra 11 (headless 模式), ILSpy (ilspycmd) | | 威胁情报 | VirusTotal, MalwareBazaar, AlienVault OTX | | LLM 集成 | Google Gemini 2.0 Flash / Groq (Llama-3.1-8b) | | 向量存储 | ChromaDB (本地, 持久化) | | Embeddings | sentence-transformers all-MiniLM-L6-v2 | | 前端 | Next.js 14, TypeScript, Tailwind CSS | | 导出 PDF | @react-pdf/renderer | | 身份验证 | Argon2id + JWT (HttpOnly cookies) | | 容器化 | Docker + Docker Compose v2 | | CI/CD | GitHub Actions (SCP + SSH 部署) | | 托管 | DigitalOcean Droplet (Ubuntu) | ## 安全模型 | 层级 | 保护措施 | |---|---| | 身份验证 | Argon2id 密码哈希, 存于 HttpOnly cookies 的 JWT, CSRF 双提交 cookie | | 文件验证 | 两步验证：原始 magic bytes (PE/ELF 头) + libmagic，严格的白名单 | | 文件存储 | 位于隔离 quarantine 卷中、以 UUID 命名的 `.bin` 文件，chmod 0o440，绝不被公开访问 | | 静态分析 | 所有工具 (YARA, Capa, Ghidra, ILSpy) 均以只读方式运行 — 绝不执行二进制文件 | | 数据隔离 | 所有数据库查询均通过 `user_id` 进行过滤 — 不存在跨用户数据访问 | | 速率限制 | 在身份验证 endpoint 使用 slowapi (每分钟 5 次登录 / 3 次注册) | | HTTP 标头 | CSP, X-Frame-Options, X-Content-Type-Options, Permissions-Policy | | 敏感信息 | 无硬编码值 — 环境变量 -> 敏感文件 -> 带警告的临时配置 | | 序列化 | Celery 仅使用 JSON (不使用 pickle) | | 子进程 | 所有工具调用均使用参数列表 (shell=False) | ## 前置条件 | 要求 | 版本 | 检查命令 | |---|---|---| | Docker Engine | 24+ | `docker --version` | | Docker Compose | v2+ | `docker compose version` | | Git | 2.x | `git --version` | **WSL2 用户 (Windows)：** Ghidra 需要大量内存（每次分析最高达 1 GB）。在运行技术栈之前，请配置 `.wslconfig` 为 WSL2 分配至少 6 GB 的内存。 ## 快速开始 ### 1. 克隆仓库 ``` git clone https://github.com/LahsenAitOiahmane/Hexplain.git cd Hexplain ``` ### 2. 配置环境 ``` cp .env.example .env ``` 生成安全的密钥（持久会话所需）： ``` python3 -c "import secrets; print(secrets.token_hex(32))" # 将输出复制两次到 .env 中的 JWT_SECRET_KEY 和 CSRF_SECRET_KEY ``` 将您的 API 密钥添加到 `.env` 中： - `GEMINI_API_KEY` 或 `GROQ_API_KEY`（生成报告至少需要一个 LLM 密钥） - `VIRUSTOTAL_API_KEY`（免费层级 — 4 次请求/分钟） - `OTX_API_KEY`（免费层级） ### 3. 构建并启动 ``` docker compose up --build ``` 这将启动 4 个容器： - `hexplain-frontend` — 位于 `http://localhost:3000` 的 Next.js 仪表板 - `hexplain-api` — 位于 `http://localhost:8000` 的 FastAPI 后端 - `hexplain-worker` — Celery 分析 worker（无暴露端口） - `hexplain-redis` — Redis broker（仅限内部访问） ### 4. 验证健康状态 ``` curl -s http://localhost:8000/api/health | python3 -m json.tool ``` 所有系统应报告为 `"healthy"`。 ## API 参考 | 方法 | 路径 | 授权 | CSRF | 描述 | |---|---|---|---|---| | GET | `/api/health` | 否 | 否 | 健康检查 (DB + Redis + 隔离区) | | POST | `/api/auth/register` | 否 | 否 | 创建用户账户 | | POST | `/api/auth/login` | 否 | 否 | 身份验证，接收 JWT + CSRF cookies | | POST | `/api/auth/logout` | 是 | 是 | 使会话失效 | | GET | `/api/auth/me` | 是 | 否 | 获取当前用户资料 | | POST | `/api/upload` | 是 | 是 | 提交二进制文件进行分析 | | GET | `/api/jobs` | 是 | 否 | 列出分析历史 | | GET | `/api/jobs/{id}` | 是 | 否 | 获取作业状态和 pipeline 进度 | | GET | `/api/jobs/{id}/report` | 是 | 否 | 获取完整分析报告 | | GET | `/api/jobs/{id}/functions` | 是 | 否 | 列出反编译的函数 | | GET | `/api/jobs/{id}/functions/{name}` | 是 | 否 | 获取函数详情 (汇编 + 伪 C 代码) | | GET | `/api/jobs/{id}/sections` | 是 | 否 | 列出带有熵值的二进制区段 | | POST | `/api/jobs/{id}/explain` | 是 | 是 | 对任何报告元素进行 AI 解释 | | GET | `/api/jobs/{id}/sessions` | 是 | 否 | 列出此作业的聊天会话 | | POST | `/api/jobs/{id}/sessions` | 是 | 是 | 创建新的聊天会话 | | POST | `/api/jobs/{id}/sessions/{sid}/chat` | 是 | 是 | 向 RAG 聊天机器人发送消息 | 交互式文档可在 `http://localhost:8000/docs` 获取。 ## 项目结构 ``` Hexplain/ ├── backend/ # FastAPI API + Celery worker │ ├── app/ │ │ ├── api/ # Route handlers (auth, upload, jobs, chat, health) │ │ ├── core/ # Configuration, security utilities, dependencies │ │ ├── models/ # SQLAlchemy ORM models (User, AnalysisJob, AnalysisReport, Chat) │ │ ├── schemas/ # Pydantic request/response validation schemas │ │ ├── services/ │ │ │ ├── analysis/ # Pipeline modules (9 modules + orchestrator) │ │ │ ├── llm_explanation.py # LLM report generation (Gemini/Groq) │ │ │ ├── rag_chatbot.py # RAG pipeline (ChromaDB + sentence-transformers) │ │ │ └── file_service.py # Upload validation + quarantine management │ │ ├── workers/ # Celery task definitions │ │ └── main.py # FastAPI application factory │ ├── migrations/ # Alembic database migrations │ ├── scripts/ # Utility scripts (DB init, rule updates) │ ├── data/ # SQLite database + ChromaDB (git-ignored) │ ├── quarantine/ # Uploaded binaries (git-ignored, never served) │ ├── requirements.txt # Python dependencies │ └── Dockerfile # Multi-stage build (Python + Ghidra + ILSpy) ├── frontend/ # Next.js 14 dashboard │ ├── src/ │ │ ├── app/ # Next.js App Router pages │ │ ├── components/ # Shared React components │ │ └── lib/ # API client, utilities, type definitions │ ├── public/ # Static assets │ ├── Dockerfile # Production Next.js build │ └── package.json ├── samples/ # Test binaries and C source files (not for production) ├── tests/ # Development testing resources │ ├── fixtures/ # Additional sample binaries │ ├── scripts/ # E2E test scripts (bash + Python) │ └── reports_and_logs/ # Raw JSON reports and pipeline logs ├── rapport/ # Internship report (LaTeX — Overleaf) ├── .env.example # Environment configuration template ├── docker-compose.yml # Multi-container orchestration └── README.md # This file ``` ## 所需的外部 API 密钥 | 服务 | 免费层级 | 注册链接 | |---|---|---| | Google Gemini (主要 LLM) | 是 — 宽裕的免费配额 | https://aistudio.google.com/ | | Groq (备用 LLM) | 是 — 免费层级 6K tokens/分钟 | https://console.groq.com/ | | VirusTotal | 是 — 4 次请求/分钟，500 次/天 | https://www.virustotal.com/gui/join-us | | MalwareBazaar | 是 — 无严格限制 | https://auth.abuse.ch/ | | AlienVault OTX | 是 — 无严格限制 | https://otx.alienvault.com/ | 即使没有任何 API 密钥，pipeline 也能平稳运行 — 会跳过 LLM 层和威胁情报模块，并生成一份仅基于启发式分析的报告。 ## 已知的局限性 - **单 worker 并发**：Ghidra 每次分析需要高达 1 GB 的内存。Celery worker 以 `--concurrency=1` 运行，以防止在普通硬件上发生 OOM 崩溃。 - **仅限静态分析**：无动态沙箱集成。高度混淆或加壳的二进制文件可能会产生不完整的反编译输出。 - **SQLite**：适用于开发和低并发部署。若要大规模投入生产环境，请迁移至 PostgreSQL。 - **不支持 Office 宏 / 脚本分析**：仅支持 PE/ELF/.NET。PowerShell 脚本、VBA 宏和 PDF 漏洞利用不在范围内。 ## 路线图 - [x] Sprint 1 — 安全基础 (身份验证, 上传, 隔离区, 异步作业) - [x] Sprint 2 — 静态分析引擎 (PE/ELF 解析, YARA, Capa, Ghidra, .NET, 威胁情报, 启发式评分) - [x] Sprint 3 — LLM 解释层 (Gemini/Groq 报告生成, RAG 聊天机器人, ChromaDB) - [x] Sprint 4 — 前端仪表板 (Next.js 14, 实时 pipeline 追踪, 反编译查看器, 导出 PDF, CI/CD) - [ ] Sprint 5 — 迁移至 PostgreSQL，多 worker 架构，分析仪表板 - [ ] Sprint 6 — 动态沙箱集成 (Cuckoo/CAPE)，Office 宏支持，MISP 导出 ## 致谢与第三方许可证 本项目依赖于多个优秀的开源工具和库。其各自组件适用其相应的许可证： - **Ghidra** (美国国家安全局) — [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) - **Mandiant Capa** (FireEye/Mandiant) — [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) - **LIEF** (Romain Thomas) — [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) - **ChromaDB** — [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) - **YARA** (VirusTotal) — [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause) - **FastAPI**, **Next.js**, **React**, **Tailwind CSS** — [MIT License](https://opensource.org/licenses/MIT) ## 许可证 本项目基于 [MIT License](LICENSE) 授权。 学术实习项目 — ENSA Marrakech, Filiere GCDSTE, 2025。 于摩洛哥拉巴特的 AIOX Labs 实习期间开发。

标签：DAST, DLL 劫持, 二进制分析, 云安全监控, 云安全运维, 云资产清单, 人工智能, 大语言模型, 威胁情报, 开发者工具, 恶意软件分析, 搜索引擎查询, 用户模式Hook绕过, 请求拦截, 逆向工程, 静态分析