# AgentMalDetector **Repository Path**: zhsij/agent-mal-detector ## Basic Information - **Project Name**: AgentMalDetector - **Description**: 课程小学期项目：面向大模型智能体和关键模块的恶意行为检测系统 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 3 - **Created**: 2026-07-06 - **Last Updated**: 2026-07-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AgentMalDetector 课程小学期项目：面向大模型智能体和关键模块的恶意行为检测系统。 ## 软件架构 ``` AgentMalDetector/ ├── backend/ # Python FastAPI 后端 │ ├── app/ │ │ ├── api/ │ │ │ ├── deps.py # FastAPI 依赖注入（DB、sandbox manager） │ │ │ └── routers/ │ │ │ ├── scan.py # 触发扫描任务接口 │ │ │ └── report.py # 查询/下载报告接口 │ │ │ │ │ ├── core/ │ │ │ ├── config.py # 全局配置（YARA路径、CVE缓存、LLM参数） │ │ │ ├── database.py # SQLite 任务状态数据库 │ │ │ └── sandbox_manager.py # 沙箱生命周期管理 │ │ │ │ │ ├── models/ │ │ │ ├── common.py # 全局数据契约（Sevseverity、ArtifactLocation、Finding） │ │ │ ├── finding.py # Finding re-export（兼容旧导入路径） │ │ │ ├── task_model.py # 扫描任务状态模型 │ │ │ └── report_model.py # 报告数据结构 │ │ │ │ │ ├── services/ │ │ │ └── orchestrator.py # 总控调度器：解析→静态→动态→报告 │ │ │ │ │ ├── modules/ │ │ │ ├── parser/ # 智能体组件识别与解析 │ │ │ │ ├── recognizer.py # 项目类型自动识别（Claude Skill / MCP Server / Agent Framework） │ │ │ │ ├── skill_parser.py # 提取 SKILL.md 及引用文件 │ │ │ │ ├── weight_parser.py # 识别 .bin/.safetensors 及 LoRA 适配器 │ │ │ │ ├── tool_parser.py # 解析工具调用链 │ │ │ │ ├── sbom_generator.py # 生成 AI-SBOM（pip/npm 依赖） │ │ │ │ ├── env_parser.py # 提取配置文件中的敏感变量名（不读值） │ │ │ │ └── __init__.py │ │ │ │ │ │ │ ├── static/ # 静态检测模块 │ │ │ │ ├── orchestrator.py # 静态检测总控（manifest→4子检测器→去重→报告） │ │ │ │ ├── manifest.py # Manifest 数据结构解析 │ │ │ │ ├── yara_scanner.py # YARA 规则扫描（危险函数/Base64/凭据泄露） │ │ │ │ ├── stego_detector.py # Unicode 隐写术检测（零宽字符/BOM混淆） │ │ │ │ ├── llm_semantic.py # LLM 语义一致性分析 │ │ │ │ ├── cve_checker.py # OSV API CVE 漏洞比对 │ │ │ │ ├── deduper.py # 检测结果去重与合并 │ │ │ │ └── rules/ │ │ │ │ └── agent_threats.yar # YARA 规则库 │ │ │ │ │ │ │ ├── dynamic/ # 动态验证模块 │ │ │ │ ├── orchestrator.py # 动态检测总控 │ │ │ │ ├── analyzer.py # 行为分析引擎 │ │ │ │ ├── verifier.py # 沙箱执行验证器 │ │ │ │ ├── sandbox_runner.py # 沙箱进程管理 │ │ │ │ ├── report.py # 动态报告生成 │ │ │ │ ├── monitor.py # 运行时行为监控入口 │ │ │ │ ├── rules.py # 动态检测规则 │ │ │ │ ├── models.py # 事件数据模型 │ │ │ │ ├── event_channel.py # 父子进程事件通道 │ │ │ │ ├── sensitive_flow.py # 敏感数据流监控 │ │ │ │ ├── taint_tracker.py # 污点追踪核心 │ │ │ │ └── hooks/ # 系统级 Hook 实现 │ │ │ │ ├── file_hook.py # 文件系统读写监控 │ │ │ │ ├── network_hook.py # 网络连接监控（C2 检测） │ │ │ │ ├── process_hook.py # 进程/Shell 执行监控 │ │ │ │ └── sensitive_hook.py # 敏感数据访问监控 │ │ │ │ │ │ │ └── reporter/ # 报告生成 │ │ │ ├── risk_evaluator.py # 综合风险评分（高危/中危/低危） │ │ │ └── report_generator.py # JSON + HTML 双格式报告 │ │ │ │ │ ├── utils/ │ │ │ ├── logger.py # 统一日志工具 │ │ │ └── file_utils.py # 文件操作工具 │ │ │ │ │ ├── tests/ # 单元测试（pytest，102 个用例全部通过） │ │ │ ├── conftest.py # pytest fixtures │ │ │ ├── test_models.py # 数据模型测试 │ │ │ ├── test_detectors.py # 各检测器单元测试 │ │ │ └── test_pipeline.py # 静态检测流程集成测试 │ │ │ │ │ ├── reports/ # 生成的检测报告输出目录 │ │ ├── uploads/ # 用户上传的压缩包临时目录 │ │ ├── requirements.txt # Python 依赖 │ │ └── main.py # FastAPI 服务启动入口 │ │ │ ├── frontend/ # 原生 HTML + CSS + JS 前端（ES6 模块化） │ │ ├── index.html # 页面入口 │ │ ├── css/ │ │ │ ├── base.css # 变量定义、样式重置、通用动画 │ │ │ ├── components.css # 卡片、按钮、表格、Tab 等 UI 组件 │ │ │ └── dashboard.css # 布局、风险总览、攻击树、响应式 │ │ └── js/ │ │ ├── main.js # 页面初始化入口，协调各模块 │ │ ├── api.js # fetch 封装（get/post/upload + 超时 + 错误处理） │ │ ├── upload.js # 拖拽上传、文件大小校验、进度回调 │ │ ├── task.js # 任务列表、轮询、状态管理 │ │ ├── progress.js # 扫描阶段进度条 │ │ ├── report.js # 报告渲染入口：数据标准化 → 分发至各组件 │ │ ├── components/ │ │ │ ├── riskCard.js # 风险总览 + 分类统计卡片 │ │ │ ├── findingList.js # Findings 列表 + 展开 + 误报标记 │ │ │ ├── mcpCard.js # MCP 工具卡片 + 详情折叠 │ │ │ ├── cveCard.js # CVE 漏洞卡片 + 详情折叠 │ │ │ └── attackTree.js # 攻击链/攻击面可视化 │ │ └── utils/ │ │ └── index.js # 统一导出：XSS 防护、格式化工具、全局常量 │ │ │ ├── configs/ │ │ ├── yara_rules/ # YARA 规则文件 │ │ └── cve_db/ # CVE 缓存数据库 │ │ │ └── test_project/ # 内置测试样例 └── README.md ``` ## 模块调用关系 ``` 用户上传项目 ↓ orchestrator.run_scan() ↓ [阶段1] parser 模块 ├─ detect_project_type() → 识别项目类型（Claude Skill / MCP Server / Agent Framework） ├─ extract_skill_files() → 提取所有 SKILL.md 及引用文件 ├─ extract_model_weights() → 识别模型权重文件（.bin / .safetensors / LoRA） ├─ extract_tool_definitions() → 提取工具调用链定义 ├─ generate_ai_sbom() → 解析 pip/npm 依赖清单 └─ extract_config_files() → 提取配置文件及敏感变量名（不读值） ↓ 生成 manifest.json ↓ [阶段2] static 模块 ├─ YARA 规则扫描 → 危险函数（exec/eval）、Base64、凭据泄露 ├─ Unicode 隐写检测 → 零宽字符、BOM 混淆 ├─ LLM 语义一致性分析 → SKILL.md 声明用途 vs 实际行为 ├─ CVE 漏洞比对 → OSV API 查询已知漏洞 └─ 去重 + 合并 → 减少重复告警 ↓ 生成 static_findings.json ↓ [阶段3] dynamic 模块 ├─ sandbox_runner → 沙箱进程启动与生命周期管理 ├─ analyzer → 行为分析引擎 ├─ verifier → 沙箱执行验证 ├─ hooks (file/net/proc/sensitive) → 系统级行为监控 ├─ sensitive_flow → 敏感数据流监控 ├─ taint_tracker → AST 插桩污点追踪 └─ build_chains → 时间窗口内证据链聚合 ↓ 生成 dynamic_findings.json ↓ [阶段4] reporter 模块 ├─ risk_evaluator → 综合评分（0-100，高危/中危/低危） └─ report_generator → final_report.json + final_report.html ``` ### 动态检测执行模式 当前 `sandbox_runner` 对 MCP 项目采用**静态发现 + 安全子集真实调用**： - **静态发现**：导入入口模块，扫描 AST / 运行时注册的工具与资源 - **安全测试**：只调用 `_is_safe_tool()` 判定为安全的工具；危险工具只记录能力分析，不真实执行 - **当前局限**：`_try_call_tool()` 对 `async def` 工具未执行 `await`，因此 `httpx` / `aiohttp` 这类异步 HTTP 库可能不会产生真实网络事件；`network_hook` 主要覆盖 `requests` / `urllib` / `socket`，不覆盖全部异步 HTTP 实现 若需做**端到端真实调用**（含异步网络/文件操作），需要额外配置 Claude Desktop 等宿主环境，并在宿主侧观测行为；本项目当前以**静态能力分析 + 有限动态行为采样**为主。 ## 前端架构 ``` 前端采用原生 HTML + CSS + JS，无任何第三方框架依赖。 数据流向： 后端 JSON 报告 ↓ report.js（数据标准化 + 分发） ↓ ┌─────────────┬─────────────┬─────────────┐ │ riskCard │ findingList │ mcpCard │ │ (风险总览) │ (Findings) │ (MCP工具) │ ├─────────────┼─────────────┼─────────────┤ │ cveCard │ attackTree │ progress │ │ (CVE漏洞) │ (攻击链) │ (进度条) │ └─────────────┴─────────────┴─────────────┘ ↓ utils/index.js（统一工具：XSS防护、格式化、常量） ``` ### 前端模块说明 | 文件 | 职责 | |------|------| | `main.js` | 页面初始化，协调所有子模块 | | `api.js` | 统一封装 fetch，支持 get/post/upload，30s 超时 | | `upload.js` | 拖拽上传、文件格式校验、进度百分比回调 | | `task.js` | 任务列表渲染、轮询状态、当前任务 ID 管理 | | `progress.js` | 5 阶段进度条（上传→解析→静态→动态→报告） | | `report.js` | 加载报告、数据标准化（normalizeReport）、分发给各组件 | | `components/riskCard.js` | 风险评分圆环图 + 分类统计卡片 | | `components/findingList.js` | Findings 列表 + 展开详情 + 误报标记 + 搜索过滤 | | `components/mcpCard.js` | MCP 工具能力卡片 + 置信度 + 折叠详情 | | `components/cveCard.js` | CVE 漏洞卡片 + 影响描述 + 修复建议 | | `components/attackTree.js` | 攻击链（后端提供路径）或攻击面降级展示 | | `utils/index.js` | 统一导出：`escapeHtml`（XSS防护）、格式化、常量映射 | ## 环境要求 - Python >= 3.9 - 建议使用 Conda 环境，参考路径：`D:\anaconda\python.exe` ## 安装与运行 ```powershell cd backend D:\anaconda\python.exe -m pip install -r requirements.txt # 启动服务 D:\anaconda\python.exe main.py # 或 D:\anaconda\python.exe -m uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` 打开浏览器访问：`http://127.0.0.1:8000/` 上传压缩包（支持 `.zip / .tar / .gz / .tgz / .rar / .7z`，单文件上限 100MB），扫描完成后查看 JSON/HTML 报告。 ## 配置项（环境变量） | 变量名 | 默认值 | 说明 | |--------|--------|------| | `LLM_API_KEY` | `""` | LLM API Key（不配置时走 Mock 模式） | | `LLM_BASE_URL` | `https://api.openai.com/v1` | LLM API 地址 | | `LLM_MODEL_NAME` | `gpt-4o-mini` | 模型名称 | | `CVE_CACHE_TTL_HOURS` | `24` | CVE 缓存有效期（小时） | | `LOG_LEVEL` | `INFO` | 日志级别 | | `YARA_MAX_FILE_SIZE` | `10485760` | YARA 单文件扫描上限（字节） |