yonglunyao/harmony-malware-analysis-platform2

# 鸿蒙恶意应用分析平台     ## 项目概述 本项目是一个专门针对 HarmonyOS 应用的恶意软件分析平台，通过 AI 驱动的自动化分析流程，帮助安全团队快速识别恶意应用、评估安全风险，并生成详细的检测报告。 ### 核心特性 - **智能任务管理**: 批量导入、筛选、搜索和状态跟踪 - **AI 深度分析**: 基于 OpenCode AI 引擎的对话式分析 - **团队协作**: 任务分配、领取、活动追踪 - **消息持久化**: 完整的对话历史保存和恢复 - **风险分级**: 自动风险评分，支持人工复核 - **经验库**: 分析经验归档和知识检索 - **数据管理**: 静态分析、动态数据、过程数据统一管理 - **MCP 管理微服务**: 12 个功能工具，支持任务、分析、评估、信誉管理 - **响应式导航**: 可折叠 Sidebar + 移动端抽屉支持 - **一键部署**: 自动化部署脚本，支持 PM2 进程管理 ### 架构设计 ┌─────────────────────────────────────────────────────────────────┐ │ 用户界面 │ │ (Next.js 15 Web App) │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 任务管理 │ │ 分析工作台 │ │ 经验库 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 报告中心 │ │ 设置管理 │ │ MCP 管理 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ HTTP API ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 业务逻辑层 │ │ (Next.js API Routes) │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 任务 CRUD │ │ 分析引擎 │ │ MCP 服务器 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ OpenCode SDK / MCP ▼ ┌─────────────────────────────────────────────────────────────────┐ │ AI 能力层 │ │ (OpenCode Service :1381) │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ LLM 服务 │ │ 会话管理 │ │ 工具系统 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ## 快速开始 ### 🚀 一键部署（推荐） **Windows:** # 双击运行或在命令行中执行 setup-local.bat **Linux/macOS:** # 添加执行权限并运行 chmod +x setup-local.sh ./setup-local.sh 脚本会自动完成以下操作： 1. 安装依赖 2. 初始化数据库 3. 启动 OpenCode 服务 4. 创建测试数据（可选） 5. 启动开发服务器 ### 手动部署 ### 1. 环境准备 确保已安装以下软件： - Node.js 18+ - pnpm 8+ - Git ### 2. 克隆项目 git clone https://github.com/yonglunyao/harmony-malware-analysis-platform2.git cd harmony-malware-analysis-platform2 ### 3. 安装依赖 pnpm install ### 4. 初始化数据库 # 从项目根目录运行 pnpm db:push ### 5. 启动 OpenCode 服务 # 安装 OpenCode CLI（首次） npm install -g @opencode-ai/cli # 启动服务（在新终端） # 注意：LLM 提供商配置请参考 OpenCode 官方文档 opencode serve --port 4096 # 服务运行在 http://localhost:4096 ### 6. 启动开发服务器 pnpm dev 访问 http://localhost:3500 ### 7. 测试连接 # 测试 OpenCode 服务连接 pnpm test:connection ## 项目配置 ### 环境变量 (apps/web/.env.local) # OpenCode 服务地址 OPENCODE_SERVER_URL="http://localhost:4096" # 数据库（开发环境默认） DATABASE_URL="file:./prisma/dev.db" **注意**: LLM 提供商 API Key 由 OpenCode 服务端管理，Web 应用无需配置。 ## 功能特性 ### 任务管理 - **任务列表**: 分页显示、实时状态更新 - **智能筛选**: 按状态、风险评分、搜索词筛选 - **任务详情**: 完整的应用信息和风险概览 - **团队协作**: 任务分配、领取、活动日志 - **状态管理**: PENDING → ASSIGNED → ANALYZING → COMPLETED / ARCHIVED ### AI 分析 - **对话式分析**: 与 AI 助手实时交互 - **消息持久化**: 对话历史自动保存 - **结构化输出**: 支持结构化分析结果 - **批量分析**: 多任务并行处理 ### 数据管理 - **静态分析**: 权限、敏感 API、证书、组件信息 - **动态分析**: API 调用序列、网络通信、行为日志 - **过程数据**: 代码片段、证据、发现、笔记 - **风险评估**: 针对权限、API、代码的风险评估 ### 经验库 - **自动归档**: 分析完成自动保存经验 - **智能搜索**: 按标签、内容检索 - **知识复用**: 历史经验参考 ### MCP 管理微服务 - **12 个功能工具**: Tasks、Analysis、Assessment、Reputation 四大模块 - **9 个管理 API**: 状态查询、统计信息、调用日志、配置管理 - **中间件系统**: 错误处理、日志记录、参数验证 - **管理界面**: 完整的 MCP 设置页面 (/settings/mcp) ### 响应式导航 - **桌面端**: 256px 展开 / 64px 折叠切换 - **平板端**: 默认折叠模式 - **移动端**: 侧边抽屉导航 - **分组导航**: 工作台、知识库、管理三组 ## API 端点 ### 任务管理 | 端点 | 方法 | 描述 | |------|------|------| | `/api/tasks` | GET | 获取任务列表（分页、搜索、筛选） | | `/api/tasks/my` | GET | 获取我的任务 | | `/api/tasks/assigned` | GET | 获取分配给我的任务 | | `/api/tasks/[id]` | GET | 获取任务详情 | | `/api/tasks/[id]/status` | PATCH | 更新任务状态 | | `/api/tasks/[id]/claim` | POST | 领取任务 | | `/api/tasks/[id]/assign` | POST | 分配任务 | | `/api/tasks/[id]/archive` | POST | 归档任务 | | `/api/tasks/sync` | POST | 同步任务列表 | ### 任务详情数据 API | 端点 | 方法 | 描述 | |------|------|------| | `/api/tasks/[id]/artifacts` | GET | 获取分析过程数据 | | `/api/tasks/[id]/static-data` | GET | 获取静态分析数据 | | `/api/tasks/[id]/assessments` | GET | 获取风险评估 | ### 分析 API | 端点 | 方法 | 描述 | |------|------|------| | `/api/analysis/start` | POST | 启动任务分析 | | `/api/analysis/sessions/[id]/prompt` | POST | 发送分析消息 | | `/api/analysis/sessions/[id]/messages` | GET | 获取消息历史 | | `/api/analysis/batch` | POST | 批量分析 | ### OpenCode API | 端点 | 方法 | 描述 | |------|------|------| | `/api/opencode/health` | GET | 健康检查 | | `/api/opencode/status` | GET | 服务状态 | | `/api/opencode/sessions` | GET/POST | 会话管理 | | `/api/opencode/sessions/[id]/interactions` | GET | 交互日志 | ### 数据管理 API (MCP) | 功能 | 描述 | |------|------| | `list_tasks` | 获取任务列表 | | `get_task` | 获取任务详情 | | `search_tasks` | 搜索任务 | | `update_task_status` | 更新任务状态 | | `upsert_artifact` | 创建/更新分析过程数据 | | `get_artifacts` | 获取过程数据列表 | | `update_static_data` | 更新静态分析数据 | | `get_static_data` | 获取静态分析数据 | | `create_assessment` | 创建风险评估 | | `get_assessments` | 获取风险评估列表 | | `get_developer_reputation` | 获取开发者信誉 | | `update_developer_reputation` | 更新开发者信誉 | ### MCP 管理微服务 API (v0.5.0 新增) | 端点 | 方法 | 描述 | |------|------|------| | `/api/mcp/status` | GET | 服务器状态 | | `/api/mcp/stats` | GET | 调用统计数据 | | `/api/mcp/logs` | GET | 调用日志列表 | | `/api/mcp/config` | GET/POST | MCP 配置管理 | | `/api/mcp/sync` | POST | 手动触发同步 | | `/api/mcp/test` | POST | 测试工具调用 | | `/api/mcp/platform` | GET | MCP 协议标准接口 | | `/api/mcp/route` | POST | 路由工具调用 | ### 经验库 API | 端点 | 方法 | 描述 | |------|------|------| | `/api/experiences/search` | GET | 搜索经验 | | `/api/experiences/[id]` | GET | 获取经验详情 | | `/api/experiences/archive` | POST | 归档经验 | ## MCP Server 配置指南 本平台提供两个 MCP Server 端点，可集成到 OpenCode 和 Claude Code 中使用。 ### MCP Server 端点 | 端点 | 工具数 | 说明 | |------|--------|------| | `/api/mcp` | 12 | 完整功能：任务管理、分析数据、风险评估 | | `/api/mcp/platform` | 8 | 标准协议：分析数据管理（适用于外部集成） | **注意**: 开发环境服务运行在端口 **3501**，生产环境请使用实际配置的端口。 ### 配置到 OpenCode **方式一：配置文件** 编辑 `~/.opencode/config.json` (Windows: `%USERPROFILE%\.opencode\config.json`): { "mcpServers": { "harmony-platform": { "url": "http://localhost:3500/api/mcp/platform", "description": "HarmonyOS 恶意应用分析平台" } } } **方式二：环境变量** export OPENCODE_MCP_SERVERS='{ "harmony-platform": { "url": "http://localhost:3500/api/mcp/platform" } }' ### 配置到 Claude Code **方式一：用户配置** 编辑 `~/.claude/config.json`: { "mcpServers": { "harmony-platform": { "url": "http://localhost:3500/api/mcp/platform" } } } **方式二：项目配置** 在项目根目录创建 `.claude.json`: { "mcpServers": { "harmony-platform": { "url": "http://localhost:3500/api/mcp/platform", "description": "HarmonyOS 恶意应用分析平台 MCP Server", "tools": [ "upsert_artifact", "get_artifacts", "update_static_data", "get_static_data", "create_assessment", "get_assessments", "get_developer_reputation", "update_developer_reputation" ] } } } ### 测试 MCP 连接 # 测试服务器状态 curl http://localhost:3500/api/mcp/status # 获取工具列表 curl http://localhost:3500/api/mcp/platform?action=list_tools # 测试工具调用 curl -X POST http://localhost:3500/api/mcp/platform \ -H "Content-Type: application/json" \ -d '{ "type": "call_tool", "tool": "get_static_data", "params": {"taskId": "TASK-2024-001"} }' ### 可用工具列表 **Tasks 模块** (仅 `/api/mcp`): - `list_tasks` - 获取任务列表 - `get_task` - 获取任务详情 - `search_tasks` - 搜索任务 - `update_task_status` - 更新任务状态 **Analysis 模块**: - `upsert_artifact` - 创建/更新分析过程数据 - `get_artifacts` - 获取分析过程数据 - `update_static_data` - 更新静态分析数据 - `get_static_data` - 获取静态分析数据 **Assessment 模块**: - `create_assessment` - 创建风险评估 - `get_assessments` - 获取风险评估 **Reputation 模块** (仅 `/api/mcp`): - `get_developer_reputation` - 获取开发者信誉 - `update_developer_reputation` - 更新开发者信誉 ## 开发指南 ### 项目结构 harmony-malware-analysis-platform2/ ├── apps/ │ └── web/ # Next.js Web 应用 │ ├── src/ │ │ ├── app/ # App Router │ │ │ ├── api/ # API 路由 │ │ │ └── (dashboard)/ # 页面 │ │ ├── components/ # React 组件 │ │ │ ├── ui/ # shadcn/ui 组件 │ │ │ ├── domain/ # 业务组件 │ │ │ └── layout/ # 布局组件 │ │ ├── hooks/ # 自定义 Hooks │ │ ├── lib/ # 工具库 │ │ │ ├── opencode/ # OpenCode 客户端 │ │ │ ├── db/ # 数据库 │ │ │ ├── mcp/ # MCP 适配器 │ │ │ └── resilience/ # 弹性层 │ │ └── types/ # 类型定义 │ └── prisma/ # 数据库 schema ├── packages/shared/ # 共享包 ├── tests/ # E2E 测试 ├── docs/ # 文档 └── CLAUDE.md # Claude Code 指南 ### 常用命令 # 开发 pnpm dev # 启动开发服务器 pnpm build # 构建生产版本 pnpm start # 启动生产服务器 pnpm lint # 代码检查 # 数据库 pnpm db:push # 推送 schema 变更 pnpm db:generate # 生成 Prisma Client pnpm db:studio # 打开 Prisma Studio pnpm db:migrate # 运行迁移 # 测试 cd tests && npm test # E2E 测试 pnpm test:connection # 测试 OpenCode 连接 ### 数据模型 #### 核心模型 | 模型 | 描述 | 关键字段 | |------|------|----------| | `Task` | 任务 | `taskId`, `status`, `riskScore` | | `AnalysisSession` | 分析会话 | `opencodeSessionId`, `taskId` | | `AnalysisMessage` | 消息记录 | `sessionId`, `role`, `content` | | `Report` | 分析报告 | `taskId`, `category`, `conclusion` | | `Experience` | 经验记录 | `taskId`, `sessionId`, `riskLevel` | | `User` | 用户 | `username`, `role`, `isActive` | | `TaskActivity` | 活动日志 | `taskId`, `userId`, `action` | | `AnalysisArtifact` | 过程数据 | `type`, `content`, `metadata` | | `AppStaticData` | 静态数据 | `permissions`, `sensitiveApis` | | `AppDynamicData` | 动态数据 | `apiCallSequence`, `networkTraffic` | | `RiskAssessment` | 风险评估 | `targetId`, `targetType`, `riskLevel` | **重要**: `opencodeSessionId` 不是唯一字段，查询时使用 `findFirst` 而非 `findUnique`。 ### 代码规范 - 使用 TypeScript 编写所有组件 - 遵循 ESLint 规则 - 组件使用函数式组件 + Hooks - API 路由返回 `NextResponse.json()` ## 部署 ### 一键部署（推荐） # 创建部署配置 .deploy.env cat > .deploy.env << EOF DEPLOY_HOST=192.168.11.140 DEPLOY_PORT=22 DEPLOY_USER=mind DEPLOY_PATH=/opt/harmony-platform/current EOF # 执行部署脚本 ./scripts/deploy.sh 脚本自动完成： - 本地构建（仅传输 .next 构建产物） - SSH/rsync 文件传输 - 远程依赖安装（使用共享缓存） - PM2 进程管理 - 健康检查验证 ### 开发环境部署 # 1. 启动 OpenCode 服务 # 注意：LLM 提供商配置请参考 OpenCode 官方文档 opencode serve # 运行在 http://localhost:1381 # 2. 启动 Web 应用 pnpm dev # 运行在 http://localhost:3500 ### 生产环境部署概览 **详细步骤请参考**: [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) #### 支持的部署方式 | 部署方式 | 说明 | 推荐场景 | |---------|------|---------| | **传统部署** | PM2 + Nginx | 通用服务器 | | **Docker** | Docker Compose | 容器化环境 | | **Kubernetes** | K8s YAML 配置 | 大规模集群 | | **云服务** | 阿里云/腾讯云/华为云 | 云端部署 | #### 快速部署（Docker） # 使用 Docker Compose 一键启动 docker-compose up -d # 查看日志 docker-compose logs -f # 停止服务 docker-compose down #### 环境变量配置 # apps/web/.env.production DATABASE_URL="postgresql://user:password@host:port/database" OPENCODE_SERVER_URL="http://your-opencode-server:1381" NODE_ENV="production" #### CI/CD 支持 - **GitHub Actions**: [部署配置示例](./docs/DEPLOYMENT.md#ci--cd-部署) - **GitLab CI**: [部署配置示例](./docs/DEPLOYMENT.md#gitlab-ci-示例) ### 更多部署文档 - [传统部署指南](./docs/DEPLOYMENT.md#方案一传统部署) - [Docker 部署](./docs/DEPLOYMENT.md#docker-部署) - [Kubernetes 部署](./docs/DEPLOYMENT.md#容器编排部署) - [云服务部署](./docs/DEPLOYMENT.md#云服务部署) - [备份策略](./docs/DEPLOYMENT.md#备份策略) - [故障排查](./docs/DEPLOYMENT.md#故障排查) ## 版本历史 | 版本 | 日期 | 更新内容 | |------|------|----------| | v0.5.0 | 2026-03-05 | MCP 管理微服务、12 个工具、9 个 API 端点、一键部署脚本 | | v0.4.0 | 2026-03-04 | Sidebar 导航优化、数据管理面板 | | v0.3.0 | 2026-03-04 | 数据管理架构、MCP 适配器 | | v0.2.0 | 2026-03-03 | 团队协作功能 | | v0.1.0 | 2026-03-02 | 初始版本 | ## 相关文档 - [CLAUDE.md](./CLAUDE.md) - Claude Code 开发指南 - [docs/MCP_GUIDE.md](./docs/MCP_GUIDE.md) - MCP 完整指南 - [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) - 部署指南 - [docs/OPENCODE_SDK_GUIDE.md](./docs/OPENCODE_SDK_GUIDE.md) - SDK 使用指南 - [tests/README.md](./tests/README.md) - 测试指南 ## 常见问题 **Q: OpenCode 服务连接失败** A: 检查服务是否运行在 localhost:1381，API Key 是否正确配置 **Q: 数据库错误** A: 运行 `pnpm db:push` 初始化数据库 **Q: 消息历史丢失** A: 确认使用 `opencodeSessionId` 进行路由，数据库中该字段不唯一 **Q: 生产环境构建失败** A: 检查 Node.js 版本（需要 18+），确保所有依赖正确安装 **Q: Sidebar 折叠不生效** A: 检查浏览器 localStorage 是否被禁用，清除缓存后重试 **Q: 移动端菜单按钮不显示** A: 确保页面路由使用 `src/app/(dashboard)/layout.tsx` 包装 ## 作者 Yonglun Yao ## License MIT

标签：AI 安全, AMSI绕过, App 安全, DAST, HarmonyOS, HTTPX, Next.js 15, Prisma 6, React 19, Ruby, 云安全监控, 反病毒, 团队协作, 威胁检测, 安全分析平台, 安全运营, 恶意应用检测, 恶意软件分析, 扫描框架, 测试用例, 目录枚举, 知识库, 移动安全, 网络安全, 自动化分析, 自动化攻击, 请求拦截, 跨站脚本, 隐私保护, 静态分析, 风险评分, 鸿蒙