Laakhishiv6/malware-analysis
GitHub: Laakhishiv6/malware-analysis
基于 EMBER 2018 LightGBM 模型的全栈恶意软件静态分析平台，上传 PE 文件即可秒级获得恶意性判定结果。
Stars: 0 | Forks: 0
# MalSand — AI 恶意软件分析平台
由 **EMBER 2018 LightGBM** 模型驱动的全栈恶意软件分析沙箱。
上传任何 PE 二进制文件，即可获得即时的静态分析判定结果：**MALICIOUS**（恶意）、**SUSPICIOUS**（可疑）或 **BENIGN**（良性）。
## 技术栈
| 层级 | 技术 |
|---|---|
| 前端 | Next.js 15, TypeScript, TailwindCSS, shadcn/ui, Zustand |
| 后端 | FastAPI (async), SQLAlchemy 2.0, PostgreSQL, Celery, Redis |
| ML 模型 | EMBER 2018 LightGBM (2381特征静态 PE 分析) |
| 认证 | JWT (access + refresh tokens), bcrypt |
| 基础设施 | Docker Compose (6个服务) |
## 项目结构
```
malware analysis project/
├── backend/ # FastAPI application
│ ├── main.py # App entry point
│ ├── requirements.txt
│ ├── Dockerfile
│ └── app/
│ ├── api/v1/endpoints/ # REST endpoints (auth, analysis, health)
│ ├── core/
│ │ ├── config.py # Pydantic settings
│ │ ├── ember_model.py # LightGBM model loader + inference
│ │ └── security.py # JWT + bcrypt
│ ├── models/ # SQLAlchemy models (User, AnalysisJob)
│ ├── repositories/ # Async DB repositories
│ ├── services/ # Business logic (AuthService, AnalysisService)
│ ├── tasks/
│ │ └── analysis_tasks.py # Celery task — runs EMBER inference
│ └── websockets/ # WebSocket connection manager
├── frontend/ # Next.js application
│ └── src/
│ ├── app/(dashboard)/analyses/page.tsx # Upload + results page
│ ├── components/analysis/ # UploadZone, ResultCard
│ ├── lib/api.ts # Axios client + analysisApi helpers
│ └── types/index.ts # Shared TypeScript types
├── ember2018/ # Pre-trained model (you provide this)
│ └── ember_model_2018.txt # LightGBM model file (121 MB)
├── tests/ # pytest test suite
│ ├── conftest.py
│ ├── test_ember_inference.py
│ ├── test_analysis_api.py
│ └── test_analysis_task.py
├── scripts/
│ └── test_model.py # CLI tool to test the model directly
├── docker-compose.yml
└── .env.example
```
## 前置条件
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)（适用于推荐的 Docker 方式）
- **或者** Python 3.12 + Node.js 18+（适用于本地开发）
- 项目根目录下包含 `ember_model_2018.txt` 的 `ember2018/` 目录
## 快速开始 — Docker Compose
这是运行完整技术栈最简单的方式。
### 1. 克隆 / 打开项目
```
cd "D:\malware analysis project"
```
### 2. 创建您的 `.env` 文件
```
# Windows PowerShell
Copy-Item .env.example .env
# macOS / Linux
cp .env.example .env
```
生成一个安全的 `SECRET_KEY` 并将其粘贴到 `.env` 中：
```
python -c "import secrets; print(secrets.token_urlsafe(64))"
```
您的 `.env` 文件应如下所示：
```
SECRET_KEY=
DEBUG=false
DATABASE_URL=postgresql://malsand:malsand@postgres:5432/malsand
REDIS_URL=redis://redis:6379/0
CORS_ORIGINS=["http://localhost:3000"]
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000
```
### 3. 构建并启动所有服务
```
docker compose up --build
```
首次构建需要几分钟时间（安装包括 LightGBM 和 LIEF 在内的 ML 依赖）。
### 4. 打开应用
| 服务 | URL |
|---|---|
| **前端** | http://localhost:3000 |
| **后端 API** | http://localhost:8000 |
| **API 文档** | http://localhost:8000/api/docs *(需要 `DEBUG=true`)* |
| **Celery Flower** | http://localhost:5555 |
注册账号并登录，然后在侧边栏导航至 **Analyses** 以上传文件。
### 停止技术栈
```
docker compose down # stop containers, keep data
docker compose down -v # stop containers AND delete all data
```
## 本地开发（不使用 Docker）
如果您希望后端和前端都启用热重载，请使用此方式。
### 仅启动基础设施
```
docker compose up postgres redis -d
```
### 后端
```
cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1 # Windows PowerShell
# source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt
```
设置环境变量并启动服务器：
```
$env:DATABASE_URL = "postgresql://malsand:malsand@localhost:5432/malsand"
$env:REDIS_URL = "redis://localhost:6379/0"
$env:SECRET_KEY = "dev-secret-change-me"
$env:EMBER_MODEL_DIR = "..\ember2018"
$env:UPLOAD_DIR = ".\uploads"
$env:DEBUG = "true"
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
### Celery Worker（新终端）
```
cd backend
.venv\Scripts\Activate.ps1
$env:DATABASE_URL = "postgresql://malsand:malsand@localhost:5432/malsand"
$env:REDIS_URL = "redis://localhost:6379/0"
$env:EMBER_MODEL_DIR = "..\ember2018"
$env:UPLOAD_DIR = ".\uploads"
celery -A app.tasks.celery_app worker --loglevel=info --concurrency=2
```
### 前端（新终端）
```
cd frontend
npm install
npm run dev
```
打开 http://localhost:3000。
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SECRET_KEY` | — | **必填。** JWT 签名密钥。使用 `secrets.token_urlsafe(64)` 生成 |
| `DATABASE_URL` | `postgresql://malsand:malsand@postgres:5432/malsand` | PostgreSQL 连接字符串 |
| `REDIS_URL` | `redis://redis:6379/0` | Redis 连接字符串 |
| `EMBER_MODEL_DIR` | `../ember2018` | 包含 `ember_model_2018.txt` 的目录路径 |
| `UPLOAD_DIR` | `./uploads` | 上传的样本文件存储位置 |
| `DEBUG` | `false` | 启用 `/api/docs` 的 API 文档和 SQL 回显 |
| `CORS_ORIGINS` | `["http://localhost:3000"]` | 允许的 CORS 源（JSON 数组） |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `30` | JWT access token 有效期 |
| `REFRESH_TOKEN_EXPIRE_DAYS` | `7` | JWT refresh token 有效期 |
## API 接口
### 认证
```
POST /api/v1/auth/register Register a new user
POST /api/v1/auth/login Login → { access_token, refresh_token }
POST /api/v1/auth/refresh Refresh access token
```
### 分析
```
POST /api/v1/analysis/upload Upload a binary → { job_id, status, filename }
GET /api/v1/analysis/{job_id} Get job status and result
GET /api/v1/analysis/?skip&limit List all analysis jobs
```
### 其他
```
GET /api/v1/health/ Health check
WS /ws/analysis/{id} WebSocket for real-time updates
```
## 分析工作原理
```
User uploads file
│
▼
POST /api/v1/analysis/upload
→ SHA256 hash computed
→ File saved to uploads/
→ AnalysisJob created (status=PENDING)
→ Celery task queued
→ Returns job_id immediately (HTTP 202)
│
▼
Celery Worker picks up task
→ Reads file bytes
→ EMBER PEFeatureExtractor → 2381-feature vector
→ LightGBM Booster.predict() → score [0, 1]
→ Maps score to verdict:
≥ 0.90 → MALICIOUS / HIGH
≥ 0.50 → MALICIOUS / MEDIUM
≥ 0.20 → SUSPICIOUS / LOW
< 0.20 → BENIGN / HIGH
→ Updates AnalysisJob (status=COMPLETED)
│
▼
Frontend polls GET /api/v1/analysis/{job_id} every 2s
→ Displays verdict, score bar, SHA256, file size
```
## 运行测试
```
# 从项目根目录
cd "D:\malware analysis project"
# 安装测试 deps（如果尚未在 venv 中）
pip install pytest pytest-asyncio pytest-mock
# 运行所有测试
pytest tests/ -v
```
测试覆盖率：
| 文件 | 测试内容 |
|---|---|
| `test_ember_inference.py` | `score_to_verdict`（8个参数化用例），带有模拟 LightGBM/ember 的 `predict_bytes` |
| `test_analysis_api.py` | 上传 202，缺少文件 422，获取任务，404，无效 UUID，列表分页，limit 验证 |
| `test_analysis_task.py` | 任务未找到路径，正常路径结果，文件缺失时设置 FAILED 状态 |
## 快速模型测试（无需服务器）
直接从命令行在任何文件上测试 EMBER 模型：
```
python scripts/test_model.py "C:\Windows\System32\notepad.exe"
# 指向不同的模型目录
python scripts/test_model.py sample.exe --model-dir path/to/ember2018
```
示例输出：
```
[*] Loading model from ember2018\ember_model_2018.txt ...
[+] Model loaded
[*] Analysing notepad.exe (201,216 bytes) ...
==================================================
File : notepad.exe
Size : 201,216 bytes
Score : 0.012341 [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]
Verdict : BENIGN
Confidence : HIGH
==================================================
```
## 故障排除
**找不到 `ember_model_2018.txt`**
确保 `ember2018/` 目录位于项目根目录且包含 `ember_model_2018.txt`。在 Docker 中，这会作为只读卷自动挂载。
**`ember` 包安装失败**
手动安装依赖：
```
pip install lightgbm lief numpy
pip install git+https://github.com/elastic/ember.git
```
**文件不是有效的 PE / 分数异常**
EMBER 模型是在 Windows PE 文件（`.exe`、`.dll`、`.sys`）上训练的。上传非 PE 文件（脚本、压缩包、文档）将产生不可靠的分数。
**Celery 任务一直处于 PENDING 状态**
Worker 容器（或本地 Celery 进程）未运行。请检查 `docker compose ps` 或手动启动 Worker。
**端口已被占用**
如果 3000、8000 或 5432 端口被占用，请在 `docker-compose.yml` 中修改主机端口（例如 `"8001:8000"`）。
标签：AI安全, AMSI绕过, Apex, AV绕过, bcrypt, Celery, Chat Copilot, DAST, DNS 反向解析, Docker, Docker Compose, EMBER, FastAPI, JWT, LightGBM, PE文件分析, PostgreSQL, Python, Redis, shadcn/ui, TailwindCSS, TypeScript, Zustand, 二进制分析, 云安全监控, 云安全运维, 人工智能, 威胁检测, 安全分析平台, 安全插件, 安全防御评估, 异步编程, 恶意软件分析, 搜索引擎查询, 无后门, 机器学习, 样本分析, 沙箱, 测试用例, 深度学习, 用户模式Hook绕过, 网络信息收集, 网络安全, 请求拦截, 逆向工具, 隐私保护, 静态分析