bruhhh212/hexora

# HEXORA ### 一个可解释的静态二进制威胁分析与风险情报平台 [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](https://react.dev/) [](https://vite.dev/) [](LICENSE) HEXORA 是一个本地的、面向分析人员的平台，用于对 Windows PE (Portable Executable) 文件进行可解释的静态检查。它将加密哈希、PE 结构、节熵、可读字符串、候选指标、导入的 API、潜在能力、多信号关联以及确定性的风险证据整合到一个调查工作流程中。 ## 目录 - [项目概述](#project-overview) - [问题陈述](#problem-statement) - [目标](#objectives) - [功能](#features) - [技术栈](#technology-stack) - [环境要求](#requirements) - [仓库结构](#repository-structure) - [安装](#installation) - [配置](#configuration) - [使用方法](#usage) - [应用工作流](#application-workflow) - [架构](#architecture) - [截图](#screenshots) - [API 概述](#api-overview) - [文档](#documentation) - [局限性](#limitations) - [未来增强](#future-enhancements) - [学生信息](#student-information) - [许可证](#license) - [致谢](#acknowledgements) ## 项目概述 HEXORA 是一个 B.Tech 计算机科学与工程专业的重大项目，为石油与能源研究大学的网络安全专业开发。该应用程序接受最大不超过 25 MB 的单个文件，将其存储在基于 UUID 的临时名称下，仅将其作为数据读取，在分析后将其删除，并将派生的调查结果持久化保存在 SQLite 中。 React 接口提供仪表盘统计、上传、历史记录、调查详情、侧重证据的选项卡、删除以及 PDF 报告下载功能。FastAPI 后端协调独立的分析器和确定性的风险引擎，其贡献会被记录在证据账本中。 ## 问题陈述 早期的二进制文件分类通常要求分析人员在多个工具中结合文件标识、PE 元数据、节、熵、字符串、指标和导入的功能。单一且缺乏解释的风险标签难以审计，而依赖执行的工作流则需要更强的隔离性。HEXORA 提供了一个整合的、非执行的静态工作流，其中风险优先级的依据保持可见。 ## 目标 - 安全地接收并验证上传的单个文件，且不执行它。 - 计算 MD5、SHA-1、SHA-256 以及文件大小的元数据。 - 防御性地解析 Windows PE 头、节、特征和导入。 - 计算整个文件和特定节的熵。 - 提取有边界的 ASCII 和 UTF-16LE 字符串以及候选 IOC。 - 将导入的 API 映射到潜在的能力类别。 - 关联选定的多信号证据。 - 生成确定性的、有边界的、可解释的风险评分。 - 持久化、审查、删除和报告调查结果。 ## 功能 - 25 MB 服务器端上传限制，使用 1 MB 流式分块 - 基于 UUID 的临时存储和无条件清理 - 对原始文件名的路径安全处理 - 计算 MD5、SHA-1 和 SHA-256 - 防御性 PE 验证和架构识别 - 头、节、特征、熵、导入和 DLL 检查 - 带有结果边界的 ASCII 和 UTF-16LE 字符串提取 - 候选 URL、IPv4、电子邮件、域名、注册表路径和文件路径提取 - 十二种潜在的 API 能力类别 - 五条多信号关联规则 - 确定性的 0–100 风险评分，具有 LOW、MEDIUM、HIGH 和 CRITICAL 频段 - 可解释的评分账本、风险因素、置信度和注意事项 - 基于 SQLite 的仪表盘、历史记录、详情、删除和统计 - 使用 ReportLab 生成的可下载调查 PDF ## 技术栈 | 层级 | 技术 | |---|---| | 后端 | Python, FastAPI, Uvicorn, pefile, SQLAlchemy, SQLite, ReportLab | | 前端 | React, React Router, Axios, Recharts, Lucide React, Tailwind CSS | | 构建工具 | Vite, oxlint, npm | | 接口 | REST/JSON 和 multipart 表单上传 | 确切版本记录在 [`backend/requirements.txt`](backend/requirements.txt) 和 [`frontend/package.json`](frontend/package.json) 中。 ## 环境要求 ### 硬件 - 能够运行 Python、Node.js 和现代浏览器的现代 64 位计算机 - 足够的本地存储空间，用于存放依赖项和 SQLite 调查元数据 - 建议开发工作流至少使用 4 GB RAM ### 软件 - Python 3.10 或更高版本 - Node.js `20.19+` 或 `22.12+`（根据安装的 Vite/Oxlint 依赖集要求） - npm - 现代浏览器 - Windows、Linux、macOS，或通过 WSL 使用 Kali Linux 进行本地开发 ## 仓库结构 ``` HEXORA/ ├── backend/ # FastAPI service and static analyzers │ ├── analyzers/ # Hash, PE, entropy, strings/IOCs, API analysis │ ├── database/ # SQLAlchemy persistence │ ├── models/ # Pydantic response schemas │ ├── scoring/ # Deterministic risk engine │ ├── uploads/ # Temporary runtime upload directory │ ├── main.py # Application and REST routes │ └── report_generator.py # Investigation PDF generation ├── frontend/ # React/Vite analyst interface ├── docs/ # Synopsis, report, presentation, manuals and API docs ├── screenshots/ # Canonical application screenshots ├── README.md ├── LICENSE ├── requirements.txt # Root convenience include └── package.json # Root convenience scripts ``` ## 安装 ### 后端 ``` cd backend python3 -m venv .venv source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 python3 -m pip install -r requirements.txt python3 -m uvicorn main:app --reload ``` ### 前端 打开第二个终端： ``` cd frontend npm install npm run dev ``` 打开 `http://localhost:5173`。交互式 API 文档可在 `http://127.0.0.1:8000/docs` 获取。 有关详细的设置和故障排除，请参阅[安装指南](docs/installation-guide/Installation_Guide.pdf)。 ## 配置 不需要包含机密的环境文件。默认配置如下： | 设置 | 默认值 | |---|---| | 前端 | `http://localhost:5173` | | 后端 | `http://127.0.0.1:8000` | | CORS origin | `http://localhost:5173` | | 数据库 | 运行时的 `backend/hexora.db` | | 数据库覆盖 | `HEXORA_DATABASE_PATH` | | 上传限制 | 25 MB | SQLite 数据库、临时上传、依赖文件夹、缓存和生成的构建输出会被 Git 忽略。 ## 使用方法 1. 启动后端，然后启动前端。 2. 打开 **Analyze** 并选择最大 25 MB 的单个文件。 3. 提交文件并等待静态分析响应。 4. 查看概述、PE 结构、熵、字符串/IOC、能力和风险证据选项卡。 5. 使用 **History** 重新打开或删除存储的调查。 6. 当需要便携式记录时，从调查详情页面下载 PDF。 ## 应用工作流 ``` flowchart LR A[Analyst selects one file] --> B[React upload view] B --> C[FastAPI validation and UUID temporary file] C --> D[Static analyzer modules] D --> E[Deterministic risk engine] E --> F[SQLite investigation record] F --> G[Dashboard, history and detail views] F --> H[ReportLab PDF report] C --> I[Temporary file deleted] ``` ## 架构  前端通过本地 HTTP 与 FastAPI 通信。该服务协调分析器、评分、持久化和报告。分析器结果会被存储；上传的可执行字节在处理后不予保留。 ## 截图 | 仪表盘 | 上传二进制文件 | |---|---| |  |  | | 调查摘要 | PE 分析 | |---|---| |  |  |

更多调查视图

   

## API 概述 | 方法 | 路由 | 用途 | |---|---|---| | GET | `/` | API 标识和版本 | | GET | `/health` | 服务健康状况 | | POST | `/scan` | 上传并静态分析单个文件 | | GET | `/scans` | 分页的最新优先历史记录 | | GET | `/scans/{scan_id}` | 完整存储的调查 | | GET | `/scans/{scan_id}/report` | 生成的调查 PDF | | DELETE | `/scans/{scan_id}` | 删除单个调查 | | GET | `/stats` | 仪表盘聚合数据 | 请参阅 [API 文档](docs/api/API_Documentation.pdf)，或在后端运行时访问 `/docs` 的 Swagger UI。 ## 文档 - [项目摘要](docs/synopsis/HEXORA_Project_Synopsis.pdf) - [最终项目报告](docs/report/HEXORA_Final_Report.pdf) - [演示文稿](docs/presentation/HEXORA_Presentation.pdf) - [用户手册](docs/user-manual/User_Manual.pdf) - [安装指南](docs/installation-guide/Installation_Guide.pdf) - [API 文档](docs/api/API_Documentation.pdf) ## 局限性 - 静态分析无法观察运行时行为。 - 加壳、加密、编码或混淆的文件可能会隐藏证据。 - 导入的 API 表明的是潜在能力，而不是确认的使用。 - 字符串和模式提取可能会遗漏动态构建的构件。 - 确定性规则可能会产生误报或漏报。 - 当前的证据模型专注于 Windows PE 文件。 - HEXORA 不保证进行恶意软件分类。 ## 未来增强 未来的工作可能包括隔离沙箱集成、YARA 规则、注重隐私的威胁情报富化、数字签名验证、改进的加壳检测、更丰富的可视化、多文件比较、基于角色的访问控制、PostgreSQL 部署、容器化、CI/CD、云部署以及经过评估的机器学习辅助。当前代码库中尚未实现这些功能。 ## 学生信息 | 字段 | 详情 | |---|---| | 学生 | Havirsh Praneeth Inumella | | SAP ID | 500109600 | | 专业课程 | B.Tech 计算机科学与工程 | | 专业方向 | 网络安全 | | 学院 | 计算机科学学院 | | 大学 | 石油与能源研究大学 | | 导师 / 指导教师 | 未分配 | ## 许可证 本代码库基于 [MIT 许可证](LICENSE) 发布。 ## 致谢 向石油与能源研究大学计算机科学学院，以及支持本项目开发和文档编写的教职员工、家人和朋友致以诚挚的感谢。

标签：AV绕过, DAST, DNS 反向解析, FastAPI, Python, React, Syscalls, 二进制分析, 云安全监控, 云安全运维, 威胁情报, 开发者工具, 恶意软件分析, 无后门, 无线安全, 网络信息收集, 逆向工具, 静态分析