iceman12276/malware-analysis-sandbox
GitHub: iceman12276/malware-analysis-sandbox
一个基于 Linux 宿主和 Windows 虚拟机的恶意软件分析沙箱，可在一次性虚拟环境中自动引爆样本并生成包含 MITRE ATT&CK 映射、网络 IoC 和行为遥测的结构化分析报告。
Stars: 0 | Forks: 0
# 恶意软件分析沙箱
一个多平台恶意软件分析沙箱：提交一个样本 → 它会在一次性
虚拟机中被引爆 → 您将获得一份结构化报告，包含 MITRE ATT&CK 映射、网络
IoC、行为遥测数据以及 YARA 命中。
技术栈与架构：参见 `docs/superpowers/specs/2026-04-25-malware-analysis-sandbox-design.md`。
项目状态、范围和约定：参见 `CLAUDE.md`。
## 本地开发
完整的开发栈在 Docker Compose 下运行：
```
docker compose up -d # db + api + frontend (default profile)
docker compose logs -f api # watch API logs
docker compose down # stop
```
| Service | 端口 | URL |
|----------|------|-------------------------|
| db | 5433 | postgres://localhost:5433/sandbox_v1 |
| api | 8000 | http://localhost:8000/healthz |
| frontend | 5173 | http://localhost:5173 |
开发数据库在 `down`/`up` 操作后依然保留 (卷: `postgres_dev_data`)。
## 针对预发布环境运行测试
集成测试套件不得在开发数据库上运行——模式迁移和
测试固定数据会破坏开发数据。我们通过在 `staging` compose 配置文件背后使用一个独立的预发布
Postgres 实例来解决这个问题。
```
# 启动 staging DB（端口 5434，独立 volume）。
docker compose --profile staging up -d db-staging
# 将 test runner 指向它。
export SANDBOX_STAGING_DATABASE_URL=postgresql://sandbox_app:sandbox_app_dev@localhost:5434/sandbox_v1
export SANDBOX_MIGRATE_DATABASE_URL=postgresql://sandbox_migrate:sandbox_migrate_dev@localhost:5434/sandbox_v1
# 运行 integration tests。
uv run pytest tests/integration/ -v
# 完成后 tear down。
docker compose --profile staging down
docker volume rm malware_analysis_sandbox_postgres_staging_data # optional: wipe staging data
```
在 `tests/integration/conftest.py` 中，`SANDBOX_STAGING_DATABASE_URL` 的优先级高于
`SANDBOX_APP_DATABASE_URL`。CI 仅使用 `SANDBOX_APP_DATABASE_URL`，
因为其 postgres 服务容器本身就是一个独立的一次性数据库，并且
已经充当了预发布环境的角色。
`db-staging` 服务使用与开发环境**相同**的 `dev_init.sql` 引导程序，因此角色
名称和授权与开发环境完全匹配——在预发布环境中通过的测试在开发环境中也会通过。
### 为什么使用独立的配置文件，而不仅仅是在同一服务器上使用独立数据库
独立的 compose 服务将故障域隔离开来：卡住的预发布
测试运行、损坏的卷，或针对预发布环境的手动 `pg_dump` 都不会
影响开发环境。`--profile staging` 标志意味着 `docker compose up` (常见的
情况) 仅启动开发栈；预发布环境只在您需要时才会启动。
## CI
GitHub Actions 会在每次推送到 `main` 分支和 PR 时运行。分为三层：
| 层级 | 目的 | 位置 |
|---|---|---|
| 1 | 各服务的正确性 (lint、类型检查、测试) | `backend`、`frontend` 作业 |
| 2 | 确定性安全门禁 (semgrep、bandit、gitleaks、trivy、pip-audit、测试质量 grep) | `security-gate` 作业 |
| 3 | KVM E2E (门控；每晚 + 选择加入标签) | 自托管 KVM 运行器上的 `kvm-e2e` 作业 |
第 1 层和第 2 层并行运行。第 3 层需要前两者都通过。完整架构：
`docs/architecture/ci.md`。
## 目录结构
```
src/backend/ FastAPI app + Postgres helpers
migrations/ alembic schema migrations + dev_init.sql role bootstrap
tests/unit/ isolated logic tests
tests/integration/ tests against a real Postgres (use the staging profile)
tests/regression/ pinned bug-repro tests
frontend/ React + Vite + TanStack + shadcn UI
docs/architecture/ living architecture docs (CI, migrations, etc.)
docs/superpowers/specs/ the design spec — source of truth
```
标签：AV绕过, Beacon Object File, DAST, Docker Compose, FastAPI, IoC提取, IP 地址批量处理, JSON 请求, Linux主机, meg, MITRE ATT&CK映射, Mr. Robot, PostgreSQL, Python, React, Syscalls, Windows客机, YARA规则匹配, 一次性虚拟机, 信息安全, 前端, 后端, 多平台支持, 威胁情报, 安全报告, 安全规则引擎, 开发者工具, 恶意软件分析, 搜索语句（dork）, 数据包嗅探, 数据库, 无后门, 无线安全, 样本引爆, 沙箱, 流量嗅探, 测试用例, 版权保护, 网络信息收集, 网络安全, 网络安全审计, 网络遥测, 自动化分析, 行为遥测, 跨站脚本, 逆向工具, 隐私保护, 集成测试