README.md
1 # MCP-Scan 2 3 一个基于 AI Agent 的自动化代码扫描和漏洞检测工具，模仿 Claude Code / Gemini CLI 的工作方式。 4 5 ## ✨ 特性 6 7 - **🤖 智能 Agent 系统**: 多阶段自动化扫描流程（信息收集 → 代码审计 → 漏洞整理） 8 - **🔍 深度代码分析**: 自动识别项目结构、技术栈和潜在安全漏洞 9 - **🎯 专用模型配置**: 支持为不同任务配置专用 LLM（思考、编码、快速响应等） 10 - **📊 安全评分系统**: 自动计算项目安全评分和风险等级 11 - **🛠️ 可扩展工具系统**: 轻松添加自定义工具和功能 12 - **📝 详细日志记录**: 使用 loguru 记录完整的执行过程 13 - **🐛 Debug 模式**: 集成 Laminar 追踪功能，方便调试 14 - **🕵️ Agent Skill 审计**: 自动识别并审计 Agent Skill 项目的一致性（SKILL.md vs 代码实现） 15 16 ## 🚀 快速开始 17 18 ### 1. 克隆项目 19 20 ```bash 21 git clone <your-repo> 22 cd mcp-scan 23 ``` 24 25 ### 2. 安装依赖 26 27 推荐使用 `uv`（速度更快，自动管理虚拟环境）： 28 29 ```bash 30 uv sync 31 ``` 32 33 或使用 pip： 34 35 ```bash 36 pip install -r requirements.txt 37 ``` 38 39 ### 3. 配置环境变量 40 41 复制环境变量模板： 42 43 ```bash 44 cp env.example .env 45 ``` 46 47 编辑 `.env` 文件，至少设置以下必需的环境变量： 48 49 ```bash 50 # 必需：OpenRouter API Key 51 OPENROUTER_API_KEY=your-api-key-here 52 53 # 可选：自定义默认模型和 URL 54 DEFAULT_MODEL=deepseek/deepseek-v3.2-exp 55 DEFAULT_BASE_URL=https://openrouter.ai/api/v1 56 ``` 57 58 > **注意**: `.env` 文件会在程序启动时自动加载，无需手动 `source`。如果你使用系统环境变量，也会被自动识别。 59 60 ### 4. 运行扫描 61 62 扫描指定项目： 63 64 ```bash 65 python main.py --repo /path/to/your/project 66 ``` 67 68 使用自定义提示词： 69 70 ```bash 71 python main.py --repo /path/to/your/project --prompt "重点检查 SQL 注入漏洞" 72 ``` 73 74 ## 📖 使用方法 75 76 ### 基本命令 77 78 ```bash 79 python main.py --repo <项目路径> [选项] 80 ``` 81 82 ### 命令行参数 83 84 | 参数 | 简写 | 说明 | 默认值 | 85 |------|------|------|--------| 86 | `--repo` | - | **必需**。要扫描的项目路径 | - | 87 | `--prompt` | `-p` | 自定义扫描提示词 | "" | 88 | `--model` | `-m` | LLM 模型名称 | `deepseek/deepseek-v3.2-exp` | 89 | `--api_key` | `-k` | API Key | 从 `OPENROUTER_API_KEY` 读取 | 90 | `--base_url` | `-u` | API 基础 URL | `https://openrouter.ai/api/v1` | 91 | `--debug` | - | 启用 debug 模式（包括 Laminar 跟踪） | `False` | 92 | `--server_url` | - | 远程 MCP server URL (启用动态分析模式) | `None` | 93 | `--header` | - | 自定义 HTTP header (key:value)，可多次使用 | `[]` | 94 | `--language` | - | 输出语言 (zh/en) | `zh` | 95 96 ### 使用示例 97 98 ```bash 99 # 基础扫描 100 python main.py --repo ./myproject 101 102 # 使用特定模型 103 python main.py --repo ./myproject -m "anthropic/claude-3.5-sonnet" 104 105 # 使用自定义 API Key 106 python main.py --repo ./myproject -k "sk-or-v1-xxxxx" 107 108 # 启用 debug 模式 109 python main.py --repo ./myproject --debug 110 111 # 组合使用 112 python main.py --repo ./myproject \ 113 -m "google/gemini-2.5-pro" \ 114 -p "重点检查认证和授权相关的安全问题" \ 115 --debug 116 117 # 动态分析 (针对运行中的 MCP Server) 118 python main.py \ 119 --server_url "http://localhost:8000/sse" \ 120 --prompt "测试工具投毒漏洞" 121 ``` 122 123 ## ⚙️ 配置说明 124 125 ### 环境变量配置 126 127 所有配置都可以通过环境变量设置。创建 `.env` 文件或在系统中设置环境变量： 128 129 #### 主要 LLM 配置 130 131 ```bash 132 # OpenRouter API Key（必需） 133 OPENROUTER_API_KEY=your-api-key-here 134 135 # 默认模型 136 DEFAULT_MODEL=deepseek/deepseek-v3.2-exp 137 138 # API 基础 URL 139 DEFAULT_BASE_URL=https://openrouter.ai/api/v1 140 ``` 141 142 #### 专用 LLM 配置 143 144 为不同任务配置专用模型，每个模型可以有独立的 API Key 和 Base URL： 145 146 ```bash 147 # Thinking 模型（用于深度推理） 148 THINKING_MODEL=google/gemini-2.5-pro 149 THINKING_BASE_URL=https://openrouter.ai/api/v1 150 THINKING_API_KEY= # 可选，不设置则使用主 API Key 151 152 # Coding 模型（用于代码生成和分析） 153 CODING_MODEL=anthropic/claude-sonnet-4.5 154 CODING_BASE_URL=https://openrouter.ai/api/v1 155 CODING_API_KEY= # 可选，不设置则使用主 API Key 156 ``` 157 158 #### Debug 和日志配置 159 160 ```bash 161 # Laminar API Key（用于 debug 模式的追踪） 162 LAMINAR_API_KEY=your-laminar-api-key 163 164 # 日志级别 165 LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR 166 ``` 167 168 ### 配置优先级 169 170 配置的优先级从高到低： 171 172 1. 命令行参数（如 `-m`, `-k`, `-u`） 173 2. 环境变量 174 3. 代码中的默认值 175 176 ## 📁 项目结构 177 178 ``` 179 mcp-scan/ 180 ├── agent/ # Agent 核心实现 181 │ ├── agent.py # 主 Agent（多阶段扫描流程） 182 │ └── base_agent.py # 基础 Agent 类 183 ├── tools/ # 工具模块 184 │ ├── registry.py # 工具注册系统 185 │ ├── thinking/ # 思考工具 186 │ ├── finish/ # 完成工具 187 │ ├── file/ # 文件操作工具 188 │ └── execute/ # 代码执行工具 189 ├── utils/ # 工具函数 190 │ ├── config.py # 配置管理 191 │ ├── llm.py # LLM 基础封装 192 │ ├── llm_manager.py # LLM 管理器（多模型支持） 193 │ ├── loging.py # 日志配置 194 │ ├── parse.py # XML 解析 195 │ ├── project_analyzer.py # 项目分析工具 196 │ ├── extract_vuln.py # 漏洞提取工具 197 │ ├── tool_context.py # 工具上下文 198 │ └── aig_logger.py # 结构化日志记录 199 ├── prompt/ # 提示词模板 200 │ ├── system_prompt.md # 系统提示词 201 │ ├── agents/ # 各阶段 Agent 提示词 202 │ ├── project_summary.md # 信息收集（含 Skill 识别） 203 │ ├── code_audit.md # 代码审计（含 Skill 一致性审计） 204 │ └── vuln_review.md # 漏洞整理 205 ├── main.py # 主入口 206 ├── requirements.txt # 依赖列表 207 ├── env.example # 环境变量模板 208 └── README.md # 本文档 209 ``` 210 211 ## 🔧 工作原理 212 213 ### 扫描流程 214 215 MCP-Scan 采用多阶段自动化流程： 216 217 ``` 218 1. 信息收集 (Information Collection) 219 ├── 分析项目结构 220 ├── 识别技术栈 221 └── 识别项目类型 (普通项目 / Agent Skill) 222 223 2. 代码审计 (Code Audit) 224 ├── 深度代码分析 225 ├── 识别安全问题 226 └── 若为 Agent Skill，执行一致性审计 (Intent Alignment Check) 227 228 3. 漏洞整理 (Vulnerability Review) 229 ├── 整理发现的漏洞 230 ├── 评估风险等级 231 └── 生成详细报告 232 ``` 233 234 ### Agent Skill 审计 235 如果项目根目录下存在 `SKILL.md`，工具会自动触发 **Agent Skill 一致性审计**： 236 - **功能意图一致性**：对比 `SKILL.md` 的描述与 `scripts/` 下的代码实现。 237 - **隐形行为检测**：检查代码中是否存在未在描述中提及的隐藏功能。 238 - **输出格式验证**：验证代码输出是否符合描述的预期格式。 239 240 ## 🤝 开发指南 241 242 建议使用 `uv` 管理本地开发环境，并统一基于 Python 3.12 进行开发与验证。 243 初始化开发环境时，可执行： 244 245 ```bash 246 uv sync --extra dev --extra test 247 ``` 248 249 提交代码前，建议至少完成以下检查： 250 251 ```bash 252 uv run ruff check . --fix 253 uv run ruff format . 254 ``` 255 256 ### 运行测试 257 258 ```bash 259 uv run pytest 260 ``` 261 262 ### 日志查看 263 264 日志文件位于项目根目录，文件名格式为 `agent_YYYYMMDD_HHMMSS.log`。 265 266 ## 📄 License 267 268 MIT License 269 270 ## 🙏 致谢 271 272 本项目灵感来源于 Claude Code 和 Gemini CLI。 273 274 --- 275 276 **注意**: 本工具仅用于合法的安全测试和代码审计。请勿用于未授权的系统测试。