🚀 守护精灵MCP 🛡️
守护精灵MCP（GuardianMCP）是您可靠的安全伙伴，它能自动守护您的项目，抵御潜在的安全漏洞。它是一个基于MCP（模型上下文协议）的服务器，借助OSV.dev数据库扫描项目依赖，检测已知的安全漏洞。该工具可与Cursor、VS Code、Claude Desktop等支持MCP协议的集成开发环境（IDE）完美配合，为您的项目安全保驾护航。
✨ 主要特性
- 自动漏洞扫描：针对npm和Composer依赖进行自动扫描，及时发现潜在风险。
- 实时警报：针对严重和高危级别的安全问题，提供实时警报，让您第一时间掌握项目安全动态。
- 三种扫描模式：提供全面扫描、摘要扫描和仅扫描严重及高危漏洞三种模式，满足不同场景的需求。
- 自动触发支持：可通过IDE规则（如安装、提交、构建时）自动触发扫描，实现安全检测的自动化。
- 多语言关键词检测：支持英语、拉脱维亚语、法语、西班牙语、德语、俄语等多种语言的关键词检测，方便全球用户使用。
- Docker支持：支持容器化部署，便于在不同环境中快速搭建和使用。
- 详细报告：生成包含修复指导和CVE链接的详细报告，帮助您快速解决安全问题。
- 快速轻量：借助OSV.dev API，实现快速高效的扫描，且资源占用少。
- 设计安全：零漏洞，依赖极少，从设计层面保障自身安全。
🔒 安全状态
- 最新安全审核：已扫描所有依赖项，未发现漏洞。
- Node.js：使用最新的长期支持版本（22.x），并及时更新安全补丁。
- 定期更新：每周检查依赖项，每月进行安全审查，确保项目始终保持安全。
更多详细的安全策略和审核信息，请参阅SECURITY.md。
🚀 快速开始
您可以根据自己的需求选择以下安装方式：
选项1：使用npm安装（推荐大多数用户）
npm install -g guardian-mcp
选项2：从源代码安装
git clone https://github.com/Kalvisan/guardian-mcp.git
cd guardian-mcp
npm install
npm run build
选项3：使用Docker安装
docker pull kalmars/guardian-mcp:latest
docker-compose up -d
🛠️ IDE配置说明
点击对应的IDE名称，查看详细的配置说明：
Cursor编辑器（推荐）
Cursor配置步骤
Cursor原生支持MCP协议，按照以下步骤进行配置：
1. 安装守护精灵MCP
npm install -g guardian-mcp
2. 配置Cursor
打开Cursor设置文件：
- macOS/Linux：
~/.cursor/config.json 或通过 Cursor Settings > Features > MCP Servers 进行设置。
- Windows：
%APPDATA%\Cursor\config.json
添加守护精灵MCP配置：
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
如果是本地安装：
{
"mcpServers": {
"guardian-mcp": {
"command": "node",
"args": ["/绝对路径/to/guardian-mcp/dist/index.js"]
}
}
}
3. 启用自动扫描（可选）
在项目根目录下创建 .cursor/rules.md 文件：
# 安全规则
在处理此项目时：
- 在项目启动时检查严重及高危漏洞。
- 在执行npm install或composer update后自动扫描新漏洞。
- 在提交git代码之前检查是否存在严重漏洞。
使用check_vulnerabilities工具，扫描模式设置为 "critical-high-only"。
4. 重启Cursor
完全重启Cursor，使守护精灵MCP生效。
5. 测试配置
打开Cursor的AI聊天窗口，输入以下命令：
Check my project for security vulnerabilities
守护精灵MCP将自动扫描您的项目依赖！
Visual Studio Code
VS Code配置步骤
VS Code可通过扩展或配置使用MCP服务器。
方法1：使用Continue.dev扩展
- 安装 Continue.dev 扩展。
- 打开Continue设置文件（
.continue/config.json）。
- 添加MCP服务器配置：
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
方法2：直接配置
- 安装守护精灵MCP：
npm install -g guardian-mcp。
- 在VS Code设置文件（
.vscode/settings.json）中添加以下配置：
{
"mcp.servers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
3. 启用自动扫描
在项目根目录下创建 .vscode/rules.md 文件：
在以下情况下自动检查漏洞：
- 打开项目时。
- 执行npm install或composer update后。
- 提交git代码之前。
4. 重启VS Code
使用 Cmd/Ctrl + Shift + P 打开命令面板，选择 "Reload Window" 重新加载窗口。
Claude Desktop
Claude Desktop配置步骤
Claude Desktop内置支持MCP协议。
1. 安装守护精灵MCP
npm install -g guardian-mcp
2. 配置Claude Desktop
打开配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：
%APPDATA%\Claude\claude_desktop_config.json
- Linux：
~/.config/Claude/claude_desktop_config.json
添加守护精灵MCP配置：
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
如果是本地安装：
{
"mcpServers": {
"guardian-mcp": {
"command": "node",
"args": ["/Users/您的路径/to/guardian-mcp/dist/index.js"]
}
}
}
3. 配置自动扫描
在全局配置文件 ~/.claude/rules.md 或项目的 .claude/rules.md 文件中添加以下规则：
# 守护精灵MCP规则
在以下情况下自动扫描漏洞：
1. 用户提及：安全、漏洞、CVE、审核等关键词。
2. 安装新包之后。
3. 提交git代码之前。
自动扫描时使用扫描模式 "critical-high-only"。
4. 重启Claude Desktop
完全退出并重新打开Claude Desktop。
Windsurf编辑器
Windsurf配置步骤
Windsurf对MCP服务器的支持与Cursor类似。
1. 安装守护精灵MCP
npm install -g guardian-mcp
2. 配置Windsurf
打开Windsurf配置文件：
- 位置：
~/.windsurf/config.json
添加MCP服务器配置：
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
3. 创建项目规则
在项目根目录下添加 .windsurf/rules.md 文件：
在以下情况下自动扫描依赖项的漏洞：
- 项目初始化时。
- 执行npm或composer命令后。
- 提交git代码之前的检查。
4. 重启Windsurf
重新加载编辑器，使守护精灵MCP生效。
Zed编辑器
Zed配置步骤
Zed正在逐步添加对MCP协议的支持，请查看当前支持状态：
1. 安装守护精灵MCP
npm install -g guardian-mcp
2. 配置Zed
打开Zed设置文件：
- macOS：
~/.config/zed/settings.json
- Linux：
~/.config/zed/settings.json
添加配置信息：
{
"assistant": {
"mcp_servers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
}
3. 重启Zed
重新加载编辑器。
注意：Zed对MCP协议的支持可能还处于试验阶段，请查看 Zed文档 以获取最新状态。
Docker配置（适用于任何IDE）
Docker配置步骤
您可以在Docker容器中运行守护精灵MCP，并从任何IDE连接使用。
方法1：使用Docker Compose（推荐）
- 克隆仓库：
git clone https://github.com/Kalvisan/guardian-mcp.git
cd guardian-mcp
- 构建并运行：
docker-compose up -d
- 配置您的IDE：
在IDE的MCP配置中，使用以下配置：
{
"mcpServers": {
"guardian-mcp": {
"command": "docker",
"args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
}
}
}
方法2：使用Docker Run
- 构建镜像：
docker build -t kalmars/guardian-mcp:latest .
- 运行容器：
docker run -d --name guardian-mcp \
-v /您的项目路径:/projects:ro \
kalmars/guardian-mcp:latest
- 配置您的IDE：
{
"mcpServers": {
"guardian-mcp": {
"command": "docker",
"args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
}
}
}
针对Cursor使用Docker的配置
编辑 ~/.cursor/config.json 文件：
{
"mcpServers": {
"guardian-mcp": {
"command": "docker",
"args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
}
}
}
挂载卷
如果要扫描容器外部的项目，可以使用以下命令：
docker run -d --name guardian-mcp \
-v /Users/您的路径/projects:/projects:ro \
-v /Users/您的路径/work:/work:ro \
guardian-mcp:latest
然后使用以下命令进行扫描：
Scan /projects/my-app for vulnerabilities
Docker健康检查
docker ps --filter name=guardian-mcp
停止容器
docker-compose down
docker stop guardian-mcp && docker rm guardian-mcp
其他IDE / 自定义配置
通用MCP配置步骤
对于任何支持模型上下文协议的IDE，可按以下步骤配置：
1. 安装守护精灵MCP
npm install -g guardian-mcp
2. 查找IDE的MCP配置文件
常见位置如下：
~/.config/[IDE名称]/config.json~/.config/[IDE名称]/settings.json~/.[IDE名称]/mcp.json
3. 添加守护精灵MCP配置
{
"mcpServers": {
"guardian-mcp": {
"command": "npx",
"args": ["guardian-mcp"]
}
}
}
或者使用完整路径：
{
"mcpServers": {
"guardian-mcp": {
"command": "node",
"args": ["/完整路径/to/guardian-mcp/dist/index.js"]
}
}
}
4. 验证配置
通过向IDE的AI助手发送以下命令进行测试：
Use the check_vulnerabilities tool to scan my project
💻 使用示例
在IDE中安装守护精灵MCP后，您可以通过以下方式使用：
手动扫描
只需向AI助手发送以下命令：
Check my project for security vulnerabilities
Scan package.json for critical issues only
Give me a full security audit
自动扫描
在IDE的规则文件（如 .cursor/rules.md、.claude/rules.md 等）中配置规则：
# 安全自动化规则
当我提及：安全、漏洞、CVE、审核或利用等关键词时
→ 使用scan_mode="critical-high-only"模式运行check_vulnerabilities工具
在执行以下命令后：npm install、npm update、composer install、composer update
→ 自动扫描新漏洞
在提交git代码之前：
→ 检查是否存在严重漏洞，若存在则发出警告
🛠️ 工具参数
守护精灵MCP提供了 check_vulnerabilities 工具，支持以下参数：
| 参数 |
类型 |
选项 |
默认值 |
描述 |
project_path |
字符串 |
任意路径 |
当前目录 |
项目目录的路径 |
file_type |
字符串 |
package.json、composer.json、both |
both |
要扫描的文件类型 |
scan_mode |
字符串 |
full、summary、critical-high-only |
full |
输出详细程度 |
使用示例
全面扫描：
Check vulnerabilities with scan_mode="full"
快速摘要：
How many vulnerabilities are in my project? (uses scan_mode="summary")
自动扫描模式（推荐）：
Scan for critical vulnerabilities only (scan_mode="critical-high-only")
📖 扫描模式详解
full 模式
适用场景：手动安全审核、全面审查。
该模式会显示所有漏洞的完整详细信息：
- 包括严重、高危、中危和低危级别的漏洞。
- 提供详细的描述和修复步骤。
- 包含参考链接和CVE编号。
- 为每个受影响的包提供更新命令。
示例输出：
## 🔴 express@4.17.1
**漏洞ID**：GHSA-rv95-896h-c2vc
**严重程度**：CRITICAL
### ⚠️ 严重风险！
**描述**：Express.js接受格式错误的URL编码请求。
**立即行动**：
1. 更新包：npm update express
2. 验证是否使用了受影响的功能
...
summary 模式
适用场景：快速健康检查、CI/CD仪表盘。
该模式仅显示漏洞数量：
- 提供快速概览。
- 不显示详细描述。
- 按严重程度统计总数。
示例输出：
## 📊 摘要
- 🔴 严重：2
- 🟠 高危：5
- 🟡 中危：12
- 🟢 低危：3
**总数**：22个漏洞
使用scan_mode="full"模式查看详细信息。
critical-high-only 模式
适用场景：自动扫描、自动化监控（推荐用于规则配置）。
该模式仅显示严重和高危漏洞的详细信息，其他漏洞仅显示数量：
- 减少无关信息干扰。
- 突出可操作的问题。
- 非常适合自动扫描。
- 隐藏中危和低危漏洞的详细信息。
示例输出：
## 🔴 lodash@4.17.20
**严重程度**：HIGH
**问题**：原型污染漏洞
**建议**：npm update lodash
---
## 📊 摘要
- 🔴 严重：1
- 🟠 高危：2
_还发现8个中危/低危问题（已隐藏）。_
_使用scan_mode="full"模式查看所有信息。_
⚠️ 严重级别说明
| 级别 |
图标 |
操作建议 |
示例 |
| CRITICAL |
🔴 |
立即更新 |
远程代码执行（RCE）、身份验证绕过、权限提升等 |
| HIGH |
🟠 |
尽快更新 |
SQL注入、跨站脚本攻击（XSS）、跨站请求伪造（CSRF）等 |
| MODERATE |
🟡 |
计划更新 |
拒绝服务（DoS）、信息泄露等 |
| LOW |
🟢 |
考虑更新 |
弃用的包、小问题等 |
📄 示例规则文件
您可以在 目录中找到现成的模板：
claude-rules.md - 包含所有场景的综合模板。project-rules.md - 项目特定的配置示例。global-rules.md - 适用于所有项目的用户级配置。
将这些文件复制到以下位置：
- Cursor：
.cursor/rules.md
- Claude Desktop：
.claude/rules.md
- VS Code：
.vscode/rules.md（使用Continue.dev扩展时）
🛡️ 支持的生态系统
| 生态系统 |
文件 |
支持状态 |
| npm (Node.js) |
package.json |
✅ 支持 |
| Composer (PHP) |
composer.json |
✅ 支持 |
| PyPI (Python) |
requirements.txt |
🔄 计划支持 |
| Go Modules |
go.mod |
🔄 计划支持 |
| Maven (Java) |
pom.xml |
🔄 计划支持 |
| NuGet (.NET) |
*.csproj |
🔄 计划支持 |
| RubyGems |
Gemfile |
🔄 计划支持 |
| Cargo (Rust) |
Cargo.toml |
🔄 计划支持 |
🐞 故障排除
守护精灵MCP未在IDE中显示
- 验证安装：
npx guardian-mcp --version
which guardian-mcp
- 检查配置文件路径是否为绝对路径：
- ❌
"args": ["dist/index.js"]
- ✅
"args": ["/Users/您的路径/guardian-mcp/dist/index.js"]
-
完全重启IDE（不要仅重新加载窗口）。
-
检查IDE日志：
- Cursor：打开开发者工具（Help > Toggle Developer Tools）。
- VS Code：输出面板 > 扩展主机。
- Claude Desktop：View > Developer > Toggle Developer Tools。
- 手动测试：
node /路径/to/guardian-mcp/dist/index.js
自动扫描功能不起作用
- 验证规则文件是否存在：
cat .cursor/rules.md
cat .claude/rules.md
- 检查规则中是否提及工具名称：
- 必须引用
check_vulnerabilities 工具。
- 自动扫描时使用
scan_mode="critical-high-only" 模式。
- 使用关键词测试：
- 尝试输入 "security" 或 "vulnerability" 等关键词，应触发自动扫描。
- 检查IDE是否支持规则：
- Cursor：✅ 内置支持。
- Claude Desktop：✅ 内置支持。
- VS Code：取决于扩展。
Docker容器无法启动
- 查看日志：
docker logs guardian-mcp
- 验证构建是否成功：
docker build -t kalmars/guardian-mcp:latest .
- 手动测试：
docker run -it kalmars/guardian-mcp:latest
- 检查健康状态：
docker ps --filter name=guardian-mcp
OSV.dev API错误
- 检查网络连接。
- 验证API是否可访问：
curl https://api.osv.dev/v1/query
- 速率限制：OSV.dev有速率限制
- 防火墙：确保允许出站HTTPS请求。
🤝 贡献指南
我们欢迎各界贡献者共同改进守护精灵MCP！以下是一些可以改进的方向：
- 支持更多的生态系统（如Python、Go、Rust等）。
- 优化版本范围解析功能。
- 实现缓存机制，减少API调用次数。
- 针对不同IDE进行优化。
- 提高测试覆盖率。
- 完善文档内容。
📄 许可证
本项目采用MIT许可证，详情请参阅 LICENSE 文件。
📚 参考资源
⚠️ 安全提示
守护精灵MCP可以帮助您识别已知的安全漏洞，但它不能替代以下安全措施：
- 全面的安全审计。
- 渗透测试。
- 安全的编码实践。
- 定期更新依赖项。
- 安全培训。
在将依赖项更新部署到生产环境之前，请务必进行审查和测试。
由守护精灵MCP团队用心打造 🛡️
报告问题 ·
请求新功能 ·
在GitHub上给项目加星
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
