richardwaters9049/MalViz

# MalViz MalViz 是一个本地优先的恶意软件分析 MVP，用于安全地上传可疑文件，在应用程序仓库之外进行隔离，在 Python worker 中运行静态分析，并向用户和管理员提供清晰、可解释的扫描报告。 它有意采取保守策略：上传的样本绝不会被执行，原始文件字节不会存储在 PostgreSQL 中，并且 Next.js 应用程序本身不执行恶意软件分析。 ## 目录 | 章节 | 描述 | | --- | --- | | [项目目标](#project-aim) | MalViz 旨在实现的目标。 | | [概述](#overview) | 主要应用程序流程和架构。 | | [技术栈](#tech-stack) | 框架、服务和运行时工具。 | | [预期输出](#expected-output) | 完成的扫描报告的样式。 | | [仓库结构](#repository-structure) | 重要代码存放的位置。 | | [前置条件](#prerequisites) | 本地开发所需的工具。 | | [环境变量](#environment) | 必需的配置值。 | | [如何运行](#how-to-run) | 单命令、Docker 和手动设置选项。 | | [如何使用该程序](#how-to-use-the-programme) | 上传、扫描、审查和管理文件。 | | [测试与验证](#testing-and-verification) | 检查项目的命令。 | | [安全说明](#security-notes) | 处理可疑文件的安全边界。 | | [当前项目状态](#current-project-status) | 目前已实现的功能和剩余工作。 | ## 项目目标 MalViz 的目标是为静态恶意软件分析提供一个干净、安全且可扩展的基础。 该项目侧重于： - 可疑文件的安全上传处理 - 在 Git 项目之外进行隔离存储 - Web 应用程序和分析 worker 之间清晰的职责边界 - 模块化的静态分析插件 - 可解释的风险评分 - 对非专业人士有用，同时展示技术细节的报告 - 能够在日后无需大规模重写的情况下支持更深层检测器的代码库 MalViz 不是一个沙箱，不会动态执行恶意软件。动态分析、沙箱机制、机器学习和外部恶意软件共享功能被刻意排除在当前 MVP 的范围之外。 ## 概述 在宏观层面上，MalViz 的工作方式如下： ``` User -> Next.js App Router -> authentication -> uploads -> dashboard -> scan and admin pages -> thin API routes -> service/security modules -> PostgreSQL -> metadata -> scan jobs -> scan results -> indicators -> feedback -> audit logs -> Redis / BullMQ -> upload-side queue signal -> Python worker -> claims queued jobs -> reads quarantined files -> runs static-analysis plugins -> scores findings -> writes structured reports -> Next.js UI -> displays status, verdict, score, reasons, indicators, and actions ``` Next.js 负责用户体验、身份验证、上传验证、元数据存储、队列信号传递和报告展示。Python worker 负责文件分析。 上传的原始文件会被写入 `MALVIZ_QUARANTINE_DIR`，而不是应用程序仓库，不是 `frontend/public`，也不是 PostgreSQL。 ## 技术栈 | 领域 | 技术 | | --- | --- | | Web 应用 | Next.js App Router 16, React 19, TypeScript | | 样式 | Tailwind CSS, 本地 UI 组件, lucide-react 图标 | | 包管理/运行时 | Bun | | 数据库 | PostgreSQL | | ORM | Prisma | | 队列信号 | Redis 和 BullMQ | | Worker | Python 3 | | Worker 测试 | pytest | | 前端/后端测试 | Vitest, TypeScript, ESLint | | 本地服务 | Docker Compose | Docker Compose 将本地服务映射到非默认端口，以避免常见的冲突： - PostgreSQL: `localhost:55432` - Redis: `localhost:56379` ## 预期输出 成功的扫描会生成一份结构化的 JSON 报告，存储在 PostgreSQL 中并显示在 UI 中。 用户应期望看到： - 扫描状态，例如 `Queued`、`Scanning`、`Clean`、`Suspicious`、`Malicious` 或 `Failed` - 判定结论 - 满分为 100 的风险评分 - 纯英文摘要 - 评分背后的原因 - 提取的指标，如哈希值、URL、域名、IP 地址、电子邮件或可疑命令 - 建议的操作 - 匹配的规则 - 技术发现 JSON - 分析元数据，包括插件结果和非致命的插件错误 报告内容示例： ``` Verdict: Suspicious Risk score: 45/100 Summary: This file shows suspicious indicators with a score of 45/100. Reasons: - The file appears to be a script capable of running commands. - Network indicators were embedded in the file. Suggested actions: - Treat this file cautiously until reviewed. - Avoid opening it on a normal workstation. - Review the listed reasons and indicators. ``` 该报告是刻意设计为可解释的。MalViz 不应在没有说明原因的情况下断言文件是恶意的。 ## 仓库结构 ``` frontend/ src/ app/ Next.js App Router pages and API route shells components/ UI, layout, upload, scan, and admin components public/ static assets served by Next.js next.config.ts Next.js app configuration postcss.config.mjs frontend CSS pipeline configuration backend/ lib/ auth, Prisma client, services, security, reports, queues prisma/ database schema, migrations, and seed data scripts/ backend database and maintenance helpers tests/ TypeScript service tests and safe upload fixtures worker/python/ Python static-analysis worker, plugins, and pytest tests infra/ docker/ Docker-only image definitions config/ eslint.config.mjs lint configuration prisma.config.ts Prisma CLI configuration vitest.config.ts test runner configuration scripts/ dev/ local startup scripts ``` ## 前置条件 在本地运行 MalViz 之前，请安装以下内容： - Bun - Docker 和 Docker Compose - Python 3 一键启动脚本将创建 worker 虚拟环境，并为常规开发安装 Python 依赖项。 ## 环境变量 从示例文件创建本地环境文件： ``` cp .env.example .env ``` 重要变量： ``` DATABASE_URL="postgresql://malviz:malviz@localhost:55432/malviz?schema=public" REDIS_URL="redis://localhost:56379" APP_URL="http://localhost:3000" SESSION_COOKIE_NAME="malviz_session" MALVIZ_QUARANTINE_DIR="/tmp/malviz-quarantine" MALVIZ_DELETED_FILE_RETENTION_DAYS="7" MAX_UPLOAD_SIZE_MB="25" MAX_UPLOAD_BYTES="26214400" ``` 注意事项： - 请将 `.env` 保留在本地。它会被 Git 忽略。 - 确保提交 `.env.example`。 - 推荐使用 `MAX_UPLOAD_SIZE_MB`。 - 为保持兼容性，仍支持 `MAX_UPLOAD_BYTES`。 - `MALVIZ_QUARANTINE_DIR` 应指向 Git 项目之外。 - 切勿使用 `frontend/public`、项目目录或任何同步文件夹进行隔离存储。 ## 如何运行 ### 选项 1：单命令本地启动 从全新克隆开始： ``` bun run setup ``` 此脚本会： - 安装 Bun 依赖项 - 启动 PostgreSQL 和 Redis - 应用数据库迁移 - 填充演示用户数据 - 验证填充的用户身份 - 创建 Python worker 虚拟环境 - 安装 worker 依赖项 - 启动 Python worker - 启动 Next.js 开发服务器 在以下地址打开应用程序： [http://localhost:3000](http://localhost:3000) ### 选项 2：Docker 热重载 在 Docker 中运行完整的开发技术栈： ``` bun run docker:dev ``` 这将启动： - PostgreSQL - Redis - 迁移和数据填充任务 - Next.js 开发服务器 - Python worker Web 和 worker 容器共享一个挂载在 `/quarantine` 的命名隔离卷。 使用以下命令停止 Docker 技术栈： ``` bun run docker:dev:down ``` ### 选项 3：手动设置 启动基础服务： ``` docker compose --project-directory . -f infra/docker/compose.yml up -d ``` 安装依赖项并准备数据库： ``` bun install bun run db:generate bun run db:migrate --name init bun run db:seed ``` 创建 Python worker 环境： ``` python3 -m venv backend/worker/python/.venv source backend/worker/python/.venv/bin/activate pip install -r backend/worker/python/requirements.txt ``` 启动 Web 应用程序： ``` bun run dev ``` 在另一个终端中启动 worker： ``` bun run worker:python ``` ## 如何使用该程序 1. 打开 [http://localhost:3000](http://localhost:3000)。 2. 选择一个预置的演示用户。 3. 前往 `/upload`。 4. 上传一个或多个文件。 5. MalViz 会验证文件元数据，将字节写入隔离存储，将元数据存储在 PostgreSQL 中，并创建扫描作业。 6. Python worker 会提取排队的作业并运行静态分析插件。 7. 前往 `/scans` 查看扫描历史记录。 8. 打开扫描详情页面以查看判定结论、分数、原因、指标、建议的操作和技术细节。 9. 管理员用户可以前往 `/admin` 审查可疑、恶意、未知或失败的扫描，并添加反馈备注。 有用的路由： | 路由 | 用途 | | --- | --- | | `/` | 登录 / 选择账户 | | `/dashboard` | 当前扫描概览 | | `/upload` | 上传待分析文件 | | `/scans` | 扫描历史记录 | | `/scans/[id]` | 扫描报告详情 | | `/admin` | 管理员审查队列 | | `/settings` | 账户和运行时设置 | 为了兼容性，旧的 `/results` 路由会重定向到 `/scans`。 ## 测试与验证 Python 测试脚本使用 `python3 -m pytest`，并将 `PYTHONPATH` 指向 `backend/worker/python`。在运行之前，请确保你的 `python3` 解释器可以使用 `pytest`。如果你使用虚拟环境，请先激活它。 运行主要检查： ``` bun run lint bunx tsc --noEmit bun run test bun run test:python bunx prisma validate --config config/prisma.config.ts bun run build ``` 手动验收检查： - 上传 `backend/tests/fixtures/samples/clean-note.txt` 并确认它获得了低风险结果。 - 上传 `backend/tests/fixtures/samples/suspicious-script.txt`、`backend/tests/fixtures/samples/network-indicators.log` 或 `backend/tests/fixtures/samples/base64-heavy.txt`，并确认报告解释了可疑信号。 - 确认上传的文件被写入 `MALVIZ_QUARANTINE_DIR` 目录下。 - 确认上传的文件未被写入 `frontend/public` 或 Git 项目目录下。 - 确认非管理员用户只能看到他们自己的扫描记录。 - 确认管理员用户可以审查可疑、恶意、未知和失败的扫描。 清理软删除的隔离文件： ``` bun run quarantine:prune ``` ## 安全说明 - 将每次上传都视为具有敌意。 - 不要执行上传的样本。 - Next.js 不得分析或执行文件内容。 - Python worker 仅执行静态分析。 - 原始文件名仅作为元数据存储。 - 存储的文件名基于 UUID。 - 原始文件字节保留在隔离存储中。 - 原始文件字节不存储在 PostgreSQL 中。 - 上传和扫描事件会被审计记录。 - 当 Redis 可用时，使用基于 Redis 的上传速率限制，并为本地开发提供内存中回退机制。 ## 当前项目状态 MalViz 目前具有： - 由服务模块支持的轻量级 API 路由 - 外部隔离存储 - PostgreSQL 元数据和结构化报告 - 基于 Redis/BullMQ 的上传端队列信号传递 - Python 静态分析 worker - 用于哈希计算、文件类型检测、字符串提取、熵分析和指标提取的模块化 worker 插件 - 可解释的风险评分 - 扫描历史记录和详情页面 - 管理员审查工作流 - 移动端导航 - 针对核心逻辑的 TypeScript 和 Python 测试覆盖率 剩余的战略工作： - 选择一个权威的生产环境队列源 - 为 Office、PDF、归档文件、JavaScript、PowerShell 和 PE 文件添加更深层的文件格式检测器 - 添加端到端的 UI 自动化 - 为更庞大的数据集添加更丰富的扫描过滤和分页功能

标签：DAST, Python, 云安全监控, 安全检测工具, 恶意软件分析, 搜索引擎查询, 文件隔离, 无后门, 测试用例, 自动化攻击, 请求拦截, 逆向工具, 静态分析