SinghAman21/malware-analysis

# 🐞 恶意软件分析沙箱 一个自托管的、小型的 [Cuckoo](https://cuckoosandbox.org/) / [Any.run](https://any.run/)-style 平台。上传一个可疑文件 → 它会在一个**一次性的、隔离的 Docker 容器**内引爆 → 系统会捕获它执行的所有操作（文件、进程、网络） → 你会获得一份 干净、结构化的威胁报告。 它被构建为一套可组合的“乐高积木”：**隔离 → 观察 → 报告**，并封装在 可扩展的 API 和精致的仪表盘中。**无需付费的 API 密钥** — 一切均 自托管运行（VirusTotal 情报丰富是可选的，且默认关闭）。 ## 它的功能 - **静态分析** — 哈希、libmagic 文件类型、熵/加壳检测、ASCII+UTF‑16 字符串提取、ELF/PE 头解析，以及使用可编辑规则的 **YARA** 扫描。 - **动态分析（引爆）** — 在锁定的容器内通过 `strace` 运行 ELF 二进制文件和脚本，重建**进程树**、**文件活动**、**网络连接**和**植入的文件**。可选的数据包捕获 (`.pcap`)。 - **评分与裁决** — 行为特征 + YARA 严重程度 → 0–100 的威胁评分以及 干净 / 可疑 / 恶意的裁决。 - **IOC** — 提取并聚合所有运行过程中的威胁指标 (IP、域名、URL、哈希)。 - **报告** — 实时报告 UI（进程树、时间线、IOC、产物）以及可下载的 原始产物（`strace.log`、`.pcap`、植入的文件）。 界面与 API 端点 **1:1** 映射 — 请参阅 [`docs/API.md`](docs/API.md)。 ## 技术栈 | 层级 | 选择 | |-------|--------| | API | **NestJS** (REST + OpenAPI/Swagger)，Zod 验证 | | 队列 | 基于 **Redis** 的 **BullMQ** | | Worker | 编排 **Docker**、`strace`、`tcpdump`、`yara`、`file` 的 TypeScript pipeline | | 数据库 | **PostgreSQL** + **Prisma** | | 存储 | **MinIO** (兼容 S3，自托管) | | Web | **Next.js 14** (App Router) · React · Tailwind · shadcn 风格 UI · TanStack Query | | 隔离 | 一次性 **Docker** 容器 (`--network none`，降权，资源限制) | | Monorepo | **pnpm** 工作区 (`apps/*`，`packages/*`) | ## 架构 ``` ┌───────────┐ upload ┌──────────────┐ Browser ───▶│ Next.js │───────────────────▶│ NestJS API │ (:3000) │ (web) │◀── live report ────│ (:4000) │ └───────────┘ └──────┬───────┘ │ enqueue job (BullMQ) ┌──────────┐ ◀────────────┤ │ Redis │ │ store sample └────┬─────┘ ▼ │ pull job ┌────────────┐ ▼ │ MinIO/S3 │ ┌────────────┐ ◀──────┤ (samples, │ │ Worker │ fetch │ artifacts) │ │ (pipeline) │ └────────────┘ └─────┬──────┘ static ──────────────── │ ──────────────── dynamic hashes/entropy/strings │ docker run --network none --cap-drop ALL ELF·PE parse · YARA │ ┌───────────────────────────────┐ └─▶│ sandbox-guest (disposable) │ │ strace ⟶ sample ⟶ /results │ └───────────────────────────────┘ │ parse strace → events/proc tree/net ▼ ┌────────────┐ │ PostgreSQL │ results, signatures, IOCs, verdict └────────────┘ ``` 深入探讨：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ## 快速开始 ### 前置条件 - **Node ≥ 20**，**pnpm ≥ 9**，**Docker**（确保你的用户在 `docker` 组中） - Linux 主机（沙箱用于观察 Linux 样本）。建议预留约 4 GB 空闲内存。 ### 一键设置 ``` bash scripts/setup.sh ``` 这将复制 `.env`，安装依赖项，启动基础设施，构建共享 包，推送数据库 schema，植入内置的 YARA 规则，并构建沙箱客户机镜像。 ### 运行（黄金路径 — 友好的低内存模式） 基础设施运行在 Docker 中；三个 Node 应用运行在主机上： ``` pnpm dev # starts @sandbox/api, @sandbox/worker, @sandbox/web together ``` 打开 **http://localhost:3000**。API 文档位于 **http://localhost:4000/docs**。 然后上传 `scripts/samples/benign_test.sh` 即可查看内容完整的报告。 ### 手动步骤（等同于 setup.sh） ``` cp .env.example .env pnpm install docker compose up -d postgres redis minio createbuckets # infra only pnpm --filter @sandbox/shared build pnpm --filter @sandbox/database generate && pnpm --filter @sandbox/database build pnpm db:push # sync schema pnpm db:seed # load built-in YARA rules + settings pnpm sandbox:build # build sandbox-guest:latest pnpm dev ``` ### 在 Docker 中运行完整技术栈（进阶） ``` docker compose --profile apps up -d --build ``` ## 实用命令 ``` make help # list all targets pnpm dev # run api + worker + web pnpm db:studio # Prisma Studio pnpm sandbox:build # rebuild the guest image pnpm typecheck # typecheck every package docker compose logs -f worker # (if running apps in docker) ``` ## 配置 所有配置都位于 `.env` 中（从 `.env.example` 复制）。重点如下： | 变量 | 默认值 | 含义 | |-----|---------|---------| | `SANDBOX_NETWORK_MODE` | `none` | `none` (离线，最安全) · `internal` (隔离 + pcap) · `inetsim` | | `SANDBOX_TIMEOUT_SEC` | `60` | 最大引爆时间 | | `SANDBOX_MEMORY_MB` / `SANDBOX_CPUS` | `512` / `1` | 单次引爆的资源上限 | | `VIRUSTOTAL_ENABLED` | `false` | 可选的哈希情报丰富（需免费层级的密钥） | | `MAX_UPLOAD_MB` | `64` | 上传大小限制 | ## 故障排除 - **“Docker 或客户机镜像不可用 — 仅限静态分析”** → 运行 `pnpm sandbox:build`， 并确保你的用户无需 sudo 即可运行 `docker ps`（`sudo usermod -aG docker $USER`， 然后重新登录）。 - 在客户机内部出现 **`strace: ptrace: Operation not permitted`** → worker 已经添加了 `--cap-add=SYS_PTRACE`；请确保你的 Docker 没有通过自定义的 seccomp profile 阻止它。 - **在主机上找不到 YARA** → 没关系。Worker 会自动在客户机镜像内运行 YARA。 - **内存不足** → 仅在 Docker 中运行基础设施，并通过 `pnpm dev` 运行各个应用（黄金路径）。 - **Prisma 找不到 `DATABASE_URL`** → 数据库脚本会通过 `dotenv-cli` 加载根目录的 `.env`； 请确保在仓库根目录下存在 `.env` 文件。 ## 文档 - [`docs/SETUP.md`](docs/SETUP.md) — **逐步的设置与运行指南**（从这里开始） - [`docs/WHY.md`](docs/WHY.md) — 动机与目标 - [`docs/FEATURES.md`](docs/FEATURES.md) — 完整功能列表 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 各个组件是如何组合的 - [`docs/API.md`](docs/API.md) — API 端点 ↔ 界面对照 - [`docs/SECURITY.md`](docs/SECURITY.md) — 隔离模型与局限性 - [`docs/LEARNINGS.md`](docs/LEARNINGS.md) — 构建这个项目带给我们的启示 - [`docs/COMMON-QUESTIONS.md`](docs/COMMON-QUESTIONS.md) — 关于该项目的综合问答 ## 许可证 MIT — 仅用于教育和授权的防御用途。

标签：DAST, Docker, NestJS, 云安全监控, 安全沙箱, 安全防御评估, 恶意软件分析, 搜索引擎查询, 测试用例, 自动化攻击, 请求拦截, 静态分析