EngJoe20/Trapix
GitHub: EngJoe20/Trapix
Trapix 是一个集成了 Python 静态分析引擎和 AI 解读层的恶意软件分类 SaaS 平台，能自动对 PE 文件进行风险评估、IOC 提取并生成可下载的 PDF 报告。
Stars: 0 | Forks: 0
# Trapix — 专业的恶意软件分类 SaaS 平台
## 目录
1. [项目概述](#1-project-overview)
2. [架构概述](#2-architecture-overview)
3. [功能](#3-features)
4. [技术栈](#4-tech-stack)
5. [文件夹结构](#5-folder-structure)
6. [安装指南](#6-installation-guide)
7. [环境变量](#7-environment-variables)
8. [运行应用程序](#8-running-the-application)
9. [数据库设置](#9-database-setup)
10. [队列 / Worker 设置](#10-queue--worker-setup)
11. [Python 分析引擎](#11-python-analysis-engine)
12. [API 文档](#12-api-documentation)
13. [订阅与配额逻辑](#13-subscription--quota-logic)
14. [AI 集成层](#14-ai-integration-layer)
15. [安全说明](#15-security-notes)
16. [Docker 设置](#16-docker-setup)
17. [生产部署](#17-production-deployment)
18. [故障排除](#18-troubleshooting)
19. [未来改进](#19-future-improvements)
## 1. 项目概述
Trapix 集成了三个主要子系统：
| 层级 | 技术 | 角色 |
|---|---|---|
| **Frontend** | Laravel Blade + Tailwind + Alpine.js | 上传 UI、结果、仪表盘 |
| **Backend API** | Laravel 12 (PHP 8.2) | 任务编排、身份验证、配额 |
| **Analysis Engine** | Python 3.11+ | PE 静态分析、熵、VT、壳 |
处理流程如下：
```
User uploads file(s)
→ Laravel validates & stores files
→ Creates AnalysisJob record
→ Dispatches RunPythonAnalysis queue job
→ Worker calls bridge.py subprocess
→ Python writes result.json (+ optional report.pdf)
→ Laravel reads results, updates DB
→ Frontend polls status endpoint
→ Results displayed; PDF downloadable
```
## 2. 架构概述
```
┌─────────────────────────────────────────────────────────────────────────┐
│ FRONTEND (Blade/Alpine) │
│ Landing │ Pricing │ Login │ Dashboard │ Upload │ Results │ Subscription │
└───────────────────────────────┬─────────────────────────────────────────┘
│ HTTP / AJAX
┌───────────────────────────────▼─────────────────────────────────────────┐
│ LARAVEL BACKEND │
│ │
│ Routes → Middleware (Auth, Quota, Rate-limit) │
│ │
│ Controllers: │
│ AnalysisController → upload, status, result │
│ DashboardController → history, quota │
│ ReportController → PDF download with limit enforcement │
│ │
│ Services: │
│ AnalysisService → orchestrates job lifecycle │
│ PythonBridgeService → subprocess execution & result parsing │
│ QuotaService → guest/free/paid limit enforcement │
│ AiAnalysisService → AI provider abstraction (provider pattern) │
│ │
│ Queue Jobs: │
│ RunPythonAnalysis → calls PythonBridgeService asynchronously │
│ │
└──────────────┬────────────────────────────────────────────┬──────────────┘
│ MySQL/MariaDB │ Subprocess
▼ ▼
┌──────────────────────────┐ ┌────────────────────────────────┐
│ DATABASE │ │ PYTHON ANALYSIS ENGINE │
│ users │ │ │
│ plans │ │ bridge.py ← analysis_request.json
│ subscriptions │ │ │ │
│ analysis_jobs │ │ FileAnalyzer │
│ uploaded_files │ │ ├── PackerDetector │
│ analysis_reports │ │ ├── StaticAnalyzer │
│ report_downloads │ │ ├── EntropyAnalyzer │
│ ai_responses │ │ ├── VtClient │
│ guest_quota_tokens │ │ ├── UPXHandler │
│ api_usage_logs │ │ └── ReportGenerator │
└──────────────────────────┘ │ │ │
│ result.json + report.pdf │
└────────────────────────────────┘
│
┌─────────────▼──────────────────┐
│ AI LAYER (future) │
│ AiAnalysisService │
│ ├── OpenAiProvider │
│ ├── ClaudeProvider (todo) │
│ ├── GeminiProvider (todo) │
│ └── OllamaProvider (todo) │
└────────────────────────────────┘
```
## 3. 功能
### 上传系统
- 支持拖放文件上传并带有进度条
- 多文件 / 整个文件夹上传（最多 50 个文件）
- 上传验证：最大文件大小、MIME 类型检查
- 每个任务的临时处理目录
- SHA-256 去重
- N 天后自动清理
### 分析引擎
- PE 头解析（通过 `pefile`）
- 每个区段的 Shannon 熵分析
- 壳检测（UPX、Themida、VMProtect 等）
- UPX 自动脱壳
- 可疑 API 调用检测（100 多个 API）
- IOC 提取（URL、IP、注册表键、DLL、电子邮件、Base64）
- VirusTotal 哈希查询（支持限流处理）
- 导出：`result.json` + `report.pdf`
### 身份验证与商业功能
| 级别 | 限制 | 最大上传量 | PDF 下载 | AI | 优先级 |
|---|---|---|---|---|---|
| 游客（未登录） | 总共 3 次 | 10 MB | 每份报告 2 次 | ✗ | ✗ |
| 免费用户（已登录） | 10 次/月 | 10 MB | 每份报告 2 次 | ✗ | ✗ |
| 专业版 | 200 次/月 | 100 MB | 无限制 | ✓ | ✓ |
| 企业版 | 无限制 | 500 MB | 无限制 | ✓ | ✓ |
### 仪表盘与历史记录
- 完整的分析历史记录，支持搜索、分页和过滤
- 风险级别和状态过滤
- 每份报告的下载历史
- 配额使用追踪器
- 订阅管理
### AI 集成（面向未来）
- Provider 模式：通过一个环境变量即可在 OpenAI → Claude → Gemini → Ollama 之间切换
- 结构化 JSON 洞察
- MITRE ATT&CK 技术识别
- AI 生成的叙述性 PDF 报告
## 4. 技术栈
| 领域 | 技术 |
|---|---|
| 后端框架 | Laravel 12 (PHP 8.2+) |
| 前端 | Blade Templates、Tailwind CSS、Alpine.js |
| 数据库 | MySQL 8+ / MariaDB 10.6+ |
| 队列 | Laravel Queue（database 驱动，可升级至 Redis） |
| 分析引擎 | Python 3.11+、pefile、requests、colorama、tabulate、yara-python |
| AI 集成 | OpenAI API（适配器模式，支持未来的提供商） |
| 文件存储 | 本地磁盘（通过 Laravel Storage 抽象，支持 S3） |
| 身份验证 | Laravel Breeze（基于 session）+ API token 支持 |
| 进程隔离 | Symfony Process 组件 |
| 缓存 | Database（可升级至 Redis） |
| 开发工具 | Vite、Pint、Pest、Pail |
## 5. 文件夹结构
```
e:\Trapix\
├── Trapix/ ← Laravel backend + Blade frontend
│ ├── app/
│ │ ├── Console/Commands/
│ │ │ └── CleanupJobFiles.php
│ │ ├── Http/
│ │ │ ├── Controllers/
│ │ │ │ ├── AnalysisController.php
│ │ │ │ ├── DashboardController.php
│ │ │ │ └── ReportController.php
│ │ │ ├── Middleware/
│ │ │ │ └── CheckAnalysisQuota.php
│ │ │ └── Requests/
│ │ │ └── UploadAnalysisRequest.php
│ │ ├── Jobs/
│ │ │ └── RunPythonAnalysis.php
│ │ ├── Models/
│ │ │ ├── AnalysisJob.php
│ │ │ ├── AnalysisReport.php
│ │ │ ├── AiResponse.php
│ │ │ ├── GuestQuotaToken.php
│ │ │ ├── Plan.php
│ │ │ ├── ReportDownload.php
│ │ │ ├── Subscription.php
│ │ │ ├── UploadedFile.php
│ │ │ └── User.php
│ │ └── Services/
│ │ ├── AI/
│ │ │ ├── AiAnalysisService.php
│ │ │ ├── AiProviderInterface.php
│ │ │ └── OpenAiProvider.php
│ │ ├── AnalysisService.php
│ │ ├── PythonBridgeService.php
│ │ └── QuotaService.php
│ ├── config/
│ │ └── trapix.php
│ ├── database/
│ │ ├── migrations/
│ │ │ ├── 2026_05_09_000001_create_plans_table.php
│ │ │ ├── 2026_05_09_000002_add_plan_to_users_table.php
│ │ │ ├── 2026_05_09_000003_create_subscriptions_table.php
│ │ │ ├── 2026_05_09_000004_create_analysis_tables.php
│ │ │ └── 2026_05_09_000005_create_ai_and_tracking_tables.php
│ │ └── seeders/
│ │ ├── DatabaseSeeder.php
│ │ └── PlanSeeder.php
│ └── routes/
│ └── web.php
│
└── Tools/ ← Python analysis engine
├── bridge.py ← ← ← Laravel calls THIS (communication contract)
├── main.py ← standalone CLI entry point
├── config.py
├── requirements.txt
├── core/
│ ├── file_analyzer.py ← orchestrator
│ ├── entropy_analyzer.py
│ ├── packer_detector.py
│ ├── report_generator.py
│ ├── static_analyzer.py
│ ├── upx_handler.py
│ └── vt_client.py
└── utils/
├── hashing.py
├── logger.py
└── strings.py
```
## 6. 安装指南
### 前置条件
- PHP 8.2+ 及扩展：`pdo_mysql`、`zip`、`fileinfo`、`mbstring`、`openssl`
- Composer 2.x
- Node.js 20+ & npm
- Python 3.11+ 及 pip
- MySQL 8+ 或 MariaDB 10.6+
### 步骤 1 — 克隆并安装 PHP 依赖
```
cd e:\Trapix\Trapix
composer install
```
### 步骤 2 — 安装 Node 依赖并构建资产
```
npm install
npm run build
```
### 步骤 3 — 安装 Python 依赖
```
cd e:\Trapix\Tools
pip install -r requirements.txt
```
### 步骤 4 — 配置环境
```
cd e:\Trapix\Trapix
cp .env.example .env
php artisan key:generate
# 然后编辑 .env — 见第 7 节
```
### 步骤 5 — 运行迁移与数据填充
```
php artisan migrate
php artisan db:seed
```
### 步骤 6 — 创建 storage 符号链接
```
php artisan storage:link
```
## 7. 环境变量
将这些添加到 `e:\Trapix\Trapix\.env` 中：
```
APP_NAME="Trapix"
APP_ENV=local
APP_URL=http://localhost:8000
# ── Database ───────────────────────────────
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=trapix
DB_USERNAME=root
DB_PASSWORD=your_password
# ── Queue ──────────────────────────────────
QUEUE_CONNECTION=database
# ── Python Engine ──────────────────────────
PYTHON_EXECUTABLE=python
PYTHON_SCRIPT_PATH=E:\Trapix\Tools\bridge.py
PYTHON_TIMEOUT=300
# ── Upload Limits ──────────────────────────
MAX_UPLOAD_BYTES=52428800 # 50 MB (Free tier)
MAX_FILES_PER_JOB=50
# ── Quota Defaults ─────────────────────────
DEFAULT_MONTHLY_ANALYSES=10
GUEST_MAX_ANALYSES=3
# ── AI Integration ─────────────────────────
AI_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
# ── Storage ────────────────────────────────
FILESYSTEM_DISK=local
JOB_CLEANUP_DAYS=7
# ── Rate Limiting ──────────────────────────
API_RATE_LIMIT=60
UPLOAD_RATE_LIMIT=10
# ── VirusTotal (fallback if user doesn't supply key) ──
# VT_API_KEY 也在 Tools/config.py 中 — 保持同步
```
## 8. 运行应用程序
### 开发环境（所有服务在一个终端中）
```
cd e:\Trapix\Trapix
composer run dev
```
这将并行启动：Laravel 服务器 + 队列 worker + Vite。
### 单独运行服务
```
# PHP dev server
php artisan serve
# Queue worker (separate terminal)
php artisan queue:work --queue=high,default --tries=2
# Vite assets
npm run dev
# Scheduled tasks (run every minute via cron or Task Scheduler)
php artisan schedule:run
```
## 9. 数据库设置
```
# 创建数据库
mysql -u root -p -e "CREATE DATABASE trapix CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 运行 migrations
php artisan migrate
# Seed subscription plans
php artisan db:seed --class=PlanSeeder
# 或者 Seed 所有内容
php artisan db:seed
```
### 计划维护
添加到 Windows 任务计划程序或 cron（每分钟）：
```
php E:\Trapix\Trapix\artisan schedule:run
```
`trapix:cleanup` 命令每天运行，用于删除超过 `JOB_CLEANUP_DAYS` 天数的处理目录。
## 10. 队列 / Worker 设置
```
# 启动 worker (处理两个 priority queues)
php artisan queue:work --queue=high,default --tries=2 --timeout=360
# 监控失败的 jobs
php artisan queue:failed
# 重试失败的 jobs
php artisan queue:retry all
# 清空失败的 jobs
php artisan queue:flush
```
在生产环境中，请使用 **Supervisor** 保持 worker 持续运行：
```
[program:trapix-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/trapix/artisan queue:work database --queue=high,default --tries=2 --timeout=360
autostart=true
autorestart=true
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/trapix-worker.log
```
## 11. Python 分析引擎
### 独立命令行接口（未更改）
```
cd e:\Trapix\Tools
python main.py --file samples/test.exe
python main.py --dir samples/ --recursive
```
### 后端桥接（由 Laravel 调用）
Laravel 通过 `PythonBridgeService` 调用 `bridge.py`：
```
# 自动调用 — 用于手动测试：
python bridge.py --file C:\samples\malware.exe --output-dir C:\tmp\job_abc123 --format json
python bridge.py --dir C:\samples\ --output-dir C:\tmp\job_abc123 --format json --no-vt
```
#### 通信契约
**输入**（由 Laravel 写入）：
```
// analysis_request.json
{
"job_id": "uuid-...",
"work_dir": "/storage/app/jobs/uuid/processing",
"skip_vt": false,
"vt_api_key": "optional-override",
"options": {}
}
```
**输出**（由 Laravel 读取）：
```
// result.json
{
"success": true,
"job_type": "file",
"results": [
{
"file_name": "malware.exe",
"risk_level": "HIGH",
"virustotal": { "malicious": 45, "total_engines": 72 },
"packer": { "is_packed": true, "packer_name": "UPX" },
"suspicious_apis": { "VirtualAllocEx": "Process Injection" },
"iocs": { "URLs": ["http://evil.com/c2"] },
...
}
],
"summary": {
"total_files": 1,
"risk_level": "HIGH",
"analysis_time": "2026-05-09 23:00:00"
}
}
```
可选：同一目录下的 `report.pdf`。
## 12. API 文档
| 方法 | Endpoint | 身份验证 | 描述 |
|---|---|---|---|
| `POST` | `/api/analysis` | 公开 | 上传文件，创建分析任务 |
| `GET` | `/api/analysis/{id}` | 公开 | 轮询任务状态 |
| `GET` | `/api/analysis/{id}/result` | 公开 | 获取完整的 JSON 结果 |
| `GET` | `/api/analysis/{id}/report` | 公开 | 下载 PDF 报告 |
| `GET` | `/api/dashboard/quota` | 需认证 | 当前用户配额信息 |
| `GET` | `/dashboard/history` | 需认证 | 分页显示分析历史 |
### POST /api/analysis
```
POST /api/analysis
Content-Type: multipart/form-data
files[] = (required, 1–50 files)
skip_vt = false (optional)
vt_api_key = abc... (optional, 64 chars)
guest_token = xyz... (optional, issued on first request)
```
响应 `202 Accepted`：
```
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"file_count": 1,
"guest_token": "xyz...",
"poll_url": "http://localhost/api/analysis/550e..."
}
```
### GET /api/analysis/{id}
```
{
"job_id": "550e...",
"status": "completed",
"file_count": 1,
"started_at": "2026-05-09T20:00:00.000000Z",
"completed_at": "2026-05-09T20:00:45.000000Z",
"duration_s": 45
}
```
## 13. 订阅与配额逻辑
### 游客用户（未验证身份）
1. 首次请求会下发一个 `guest_token`（存储在 session + `guest_quota_tokens` 表中）。
2. 完成 3 次分析后，Endpoint 将返回包含“登录以继续”提示的 `HTTP 429`。
### 免费登录用户
- 每月 10 次分析（可通过 `DEFAULT_MONTHLY_ANALYSES` 配置）。
- 配额在每月 1 号重置。
- 超出限制后：返回带有升级行动呼吁 (CTA) 的 `HTTP 429`。
### 专业版 / 企业版
- 专业版：每月 200 次分析，100 MB 上传量，AI 访问权限，优先队列。
- 企业版：无限制，500 MB，包含所有功能。
- 配额通过 `User::canAnalyze()` → `Plan::monthly_analyses` 进行检查。
### PDF 下载限制
- 免费计划：每个用户对每份报告最多 **2 次下载**。
- 专业版 / 企业版：无限制。
- 在 `ReportController::download()` 中强制执行。
## 14. AI 集成层
AI 层使用 **Provider / Adapter 模式**。您可以在不触及业务逻辑的情况下添加新的 AI 后端：
1. 创建实现 `AiProviderInterface` 接口的 `app/Services/AI/YourProvider.php`。
2. 在 `AiAnalysisService::resolveProvider()` 中添加一个 `case`。
3. 在 `.env` 中设置 `AI_PROVIDER=your_provider`。
### 当前已实现
- **OpenAI** (`AI_PROVIDER=openai`) — GPT-4o / GPT-4o-mini
### 计划实现的适配器
| 提供商 | 类名 | `.env` 值 |
|---|---|---|
| Claude | `ClaudeProvider` | `claude` |
| Gemini | `GeminiProvider` | `gemini` |
| Ollama (本地) | `OllamaProvider` | `ollama` |
## 15. 安全说明
- **沙箱子进程**：Python 作为独立进程运行，没有 Laravel 上下文。
- **文件验证**：在请求层强制执行 MIME 类型 + 大小限制。
- **UUID 任务 ID**：无法进行顺序 ID 枚举。
- **游客 token**：与 session + IP 绑定的 48 位随机字符 token。
- **下载限制**：在服务器端强制执行，而不仅仅是前端。
- **速率限制**：通过 Laravel throttle 中间件实现每分钟 10 次上传、60 次 API 请求。
- **禁止任意代码执行**：Python 路径在配置中是固定的；用户无法选择要运行的脚本。
- **环境变量中的 API 密钥**：VT 密钥、OpenAI 密钥永远不会存储在代码中。
- **清理任务**：临时文件在 7 天后被清除。
### 推荐的生产环境附加配置
- 以 **非 root 专用用户** 身份运行队列 worker。
- 使用 **`noexec`** 标志挂载上传目录。
- 在 `PythonBridgeService` 执行分析之前添加 **ClamAV** 集成。
- 在上传 Endpoint 前启用 **WAF**（Cloudflare 等）。
- 使用 **S3 / R2** 存储报告而不是本地磁盘。
## 16. Docker 设置
```
# docker-compose.yml (starter — adapt as needed)
version: "3.9"
services:
app:
build: ./Trapix
ports: ["8000:8000"]
environment:
- APP_ENV=production
- DB_HOST=db
- PYTHON_EXECUTABLE=/usr/bin/python3
- PYTHON_SCRIPT_PATH=/app/../Tools/bridge.py
volumes:
- ./Trapix:/app
- ./Tools:/Tools
depends_on: [db, queue]
queue:
build: ./Trapix
command: php artisan queue:work --queue=high,default --tries=2
depends_on: [db]
db:
image: mysql:8
environment:
MYSQL_DATABASE: trapix
MYSQL_ROOT_PASSWORD: secret
volumes:
- db_data:/var/lib/mysql
volumes:
db_data:
```
## 17. 生产部署
```
# 在服务器上
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize
# 运行 migrations (在 CI 中切勿跳过 --force)
php artisan migrate --force
# 构建前端 assets
npm ci && npm run build
# 设置权限
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```
## 18. 故障排除
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| 任务卡在 `pending` 状态 | 队列 worker 未运行 | `php artisan queue:work` |
| `result.json not found` | Python 脚本路径错误 | 检查 `.env` 中的 `PYTHON_SCRIPT_PATH` |
| `429 Too Many Requests` | 游客/用户超出配额 | 登录或升级计划 |
| 上传时出现 `500` 错误 | `storage/app` 不可写 | `chmod -R 775 storage` |
| PDF 未生成 | 缺少 Python `reportlab` | `pip install reportlab` |
| VT 总是返回 `not found` | API 密钥无效 | 检查 `Tools/config.py` 中的 `VT_API_KEY` |
| `Class not found` 错误 | 缺少 autoload | `composer dump-autoload` |
## 19. 未来改进
- [ ] AI 生成的 PDF 叙述性报告
- [ ] Claude、Gemini、Ollama 提供商适配器
- [ ] Stripe/Paddle 计费集成
- [ ] YARA 规则上传与匹配
- [ ] WebSocket 实时状态更新（取代轮询）
- [ ] S3 / Cloudflare R2 存储后端
- [ ] 管理面板（任务管理、用户管理、计划管理）
- [ ] 分析完成时的 Webhook 通知
- [ ] 团队/组织账户
- [ ] 用于编程访问的 API 密钥管理
- [ 批量导出分析历史（CSV/JSON）
- [ ] 动态沙箱执行（未来：与 Cuckoo/Any.run API 集成）
*为安全社区倾注 ❤️ 打造 — Trapix v1.0*
标签：AI分析, Alpine.js, AMSI绕过, DAST, DNS 反向解析, Go语言工具, Laravel, Petitpotam, PE文件分析, PHP 8.2, Python, SaaS平台, Tailwind CSS, 云安全监控, 后端开发, 威胁检测, 安全合规, 安全情报, 恶意软件分析, 搜索引擎查询, 文件扫描, 无后门, 沙箱技术, 漏洞分析, 熵值计算, 网络代理, 网络安全, 请求拦截, 路径探测, 队列处理, 隐私保护, 静态分析