使用说明

监护人MCP🛡️

您警惕的安全伙伴，自动保护您的项目免受漏洞攻击。

GuardianMCP是一个MCP（模型上下文协议）服务器，它使用OSV.dev数据库扫描项目依赖关系以查找已知的安全漏洞。适用于光标, VS Code, 克劳德桌面以及其他与MCP兼容的IDE。

特性

自动漏洞扫描 用于npm和Composer依赖关系
实时警报 用于关键和高度严重的问题
三种扫描模式：完整、总结、仅临界高
自动触发支持 通过IDE规则（安装、提交、构建）
多语言关键字检测 （英语、拉脱维亚语、法语、西班牙语、德语、俄语等）
Docker支持 用于集装箱化部署
详细报告 带有补救指导和CVE链接
快速轻便 使用OSV.dev API
设计安全 -0个漏洞，依赖性最小

安全状态

最新安全审计： 已扫描所有依赖项，发现0个漏洞 Node.js： 带有安全更新的最新LTS（22.x） 定期更新： 每周依赖性检查和每月安全审查

看安全.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
# or
docker-compose up -d

IDE设置说明

单击IDE查看设置说明：

Cursor Editor (Recommended)

光标设置

Cursor具有本机MCP支持。请按照以下步骤操作：

1.安装GuardianMCP

npm install -g guardian-mcp
# or use local installation (see Quick Start)

2.配置光标

打开光标设置：

macOS/Linux: ~/.cursor/config.json 或 Cursor Settings > Features > MCP Servers
视窗: %APPDATA%\Cursor\config.json

添加GuardianMCP配置：

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": ["guardian-mcp"]
    }
  }
}

或者，如果在本地安装：

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/guardian-mcp/dist/index.js"]
    }
  }
}

3.启用自动扫描（可选）

创建 .cursor/rules.md 在您的项目中：

# Security Rules

When working in this project:
- Check for CRITICAL/HIGH vulnerabilities on project start
- Scan after npm install or composer update
- Verify no critical issues before git commits

Use check_vulnerabilities tool with scan_mode="critical-high-only".

4.重新启动游标

完全重新启动Cursor以加载GuardianMCP。

5.测试它

打开Cursor的AI聊天并键入：

Check my project for security vulnerabilities

GuardianMCP将自动扫描您的依赖关系！

Visual Studio Code

VS代码设置

VS Code可以通过扩展或配置使用MCP服务器。

方法1：使用Continue.dev扩展

安装 Continue.dev 扩展
打开继续设置(.continue/config.json)
添加MCP服务器配置：

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": ["guardian-mcp"]
    }
  }
}

方法2：直接配置

安装GuardianMCP： npm install -g guardian-mcp
添加到VS代码设置(.vscode/settings.json):

{
  "mcp.servers": {
    "guardian-mcp": {
      "command": "npx",
      "args": ["guardian-mcp"]
    }
  }
}

3.启用自动扫描

创建 .vscode/rules.md:

Automatically check for vulnerabilities when:
- Opening the project
- After running npm install/composer update
- Before creating commits

4.重新启动VS代码

重新加载窗口： Cmd/Ctrl + Shift + P → “重新加载窗口”

Claude Desktop

Claude桌面设置

Claude Desktop内置了MCP支持。

1.安装GuardianMCP

npm install -g guardian-mcp

2.配置克劳德桌面

打开配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %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/you/path/to/guardian-mcp/dist/index.js"]
    }
  }
}

3.配置自动扫描

增添 ~/.claude/rules.md （全球）或项目 .claude/rules.md:

# GuardianMCP Rules

Automatically scan for vulnerabilities when:
1. User mentions: security, vulnerability, CVE, audit
2. After package installations
3. Before git commits

Use scan_mode="critical-high-only" for auto-scans.

4.重新启动克劳德桌面

完全退出并重新打开Claude Desktop。

Windsurf Editor

风帆设置

Windsurf支持与Cursor类似的MCP服务器。

1.安装GuardianMCP

npm install -g guardian-mcp

2.配置Windsurf

打开Windsurf配置：

位置: ~/.windsurf/config.json

添加MCP服务器：

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": ["guardian-mcp"]
    }
  }
}

3.创建项目规则

添加 .windsurf/rules.md 对于您的项目：

Auto-scan dependencies for vulnerabilities on:
- Project initialization
- npm/composer commands
- Pre-commit checks

4.重新启动Windsurf

重新加载编辑器以激活GuardianMCP。

Zed Editor

Zed设置

Zed正在添加MCP支持。检查当前状态：

1.安装GuardianMCP

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 Setup (Any IDE)

Docker设置

在Docker容器中运行GuardianMCP，并从任何IDE连接。

方法一：使用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运行

塑造形象：

docker build -t kalmars/guardian-mcp:latest .

运行容器：

docker run -d --name guardian-mcp \
  -v /path/to/your/projects:/projects:ro \
  kalmars/guardian-mcp:latest

配置IDE：

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"]
    }
  }
}

对于使用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/you/projects:/projects:ro \
  -v /Users/you/work:/work:ro \
  guardian-mcp:latest

然后扫描：

Scan /projects/my-app for vulnerabilities

Docker健康检查

docker ps --filter name=guardian-mcp
# Should show "healthy" status

停止容器

docker-compose down
# or
docker stop guardian-mcp && docker rm guardian-mcp

Other IDEs / Custom Setup

通用MCP设置

对于支持模型上下文协议的任何IDE：

1.安装GuardianMCP

npm install -g guardian-mcp

2.查找IDE的MCP配置

常见位置：

~/.config/[IDE_NAME]/config.json
~/.config/[IDE_NAME]/settings.json
~/.[IDE_NAME]/mcp.json

3.添加GuardianMCP

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": ["guardian-mcp"]
    }
  }
}

或者使用完整路径：

{
  "mcpServers": {
    "guardian-mcp": {
      "command": "node",
      "args": ["/full/path/to/guardian-mcp/dist/index.js"]
    }
  }
}

4.验证设置

通过询问IDE的AI助手进行测试：

Use the check_vulnerabilities tool to scan my project

用法

在IDE中安装GuardianMCP后，您可以：

手动扫描

只需询问您的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等等）：

# Security Automation

When I mention: security, vulnerability, CVE, audit, or exploit
→ Run check_vulnerabilities with scan_mode="critical-high-only"

After running: npm install, npm update, composer install, composer update
→ Automatically scan for new vulnerabilities

Before creating git commits:
→ Check for CRITICAL vulnerabilities and warn if found

刀具参数

GuardianMCP提供 check_vulnerabilities 具有以下参数的工具：

参数	类型	选项	默认值	描述
`project_path`	string	任意路径	当前目录	项目目录路径
`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 ID
更新每个包的命令

输出示例：

## 🔴 express@4.17.1
**Vulnerability ID:** GHSA-rv95-896h-c2vc
**Severity:** CRITICAL

### ⚠️ CRITICAL RISK!
**Description:** Express.js accepts requests with malformed URL encoding

**IMMEDIATE ACTION REQUIRED:**
1. Update package: npm update express
2. Verify no vulnerable functionality is used
...

`summary` 模式

最适合： 快速健康检查、CI/CD仪表板

仅显示漏洞计数：

快速概览
无详细说明
按严重程度分类的总计数

输出示例：

## 📊 Summary
- 🔴 Critical: 2
- 🟠 High: 5
- 🟡 Moderate: 12
- 🟢 Low: 3

**Total: 22 vulnerabilities**
Run with scan_mode="full" for details.

`critical-high-only` 模式

最适合： 自动扫描、自动监控（建议用于规则）

显示CRITICAL/HIGH的详细信息，统计其他信息：

降低噪音
突出可操作的问题
非常适合自动扫描
隐藏中等/低细节

输出示例：

## 🔴 lodash@4.17.20
**Severity:** HIGH
**Issue:** Prototype pollution vulnerability
**Recommendation:** npm update lodash

---

## 📊 Summary
- 🔴 Critical: 1
- 🟠 High: 2

_Also found 8 moderate/low issues (hidden)._
_Run with scan_mode="full" to see all._

严重级别

级别	图标	动作	示例
关键的	🔴	立即更新	RCE、绕过授权、特权升级
高	🟠	尽快更新	SQL注入、XSS、CSRF
适度	🟡	计划更新	DoS，信息泄露
低	🟢	考虑更新	弃用的软件包，小问题

示例规则文件

看 examples/ 对于即用型模板：

claude-rules.md -包含所有场景的综合模板
project-rules.md -项目特定配置示例
global-rules.md -所有项目的用户范围配置

将这些复制到：

光标： .cursor/rules.md
克劳德桌面： .claude/rules.md
VS代码： .vscode/rules.md （使用Continue.dev）

支持的生态系统

生态系统	文件	状态
npm （Node.js）	`package.json`	✅ 支持
作曲家（PHP）	`composer.json`	✅ 支持
PyPI（Python）	`requirements.txt`	🔄 计划中
Go模块	`go.mod`	🔄 计划中
Maven（Java）	`pom.xml`	🔄 计划中
NuGet（.NET）	`*.csproj`	🔄 计划中
RubyGems	`Gemfile`	🔄 计划中
货物（生锈）	`Cargo.toml`	🔄 计划中

故障排除

GuardianMCP not showing up in IDE

验证安装：

npx guardian-mcp --version
# or
which guardian-mcp

检查配置文件路径是否为绝对路径：
- ❌ "args": ["dist/index.js"]
- ✅ "args": ["/Users/you/guardian-mcp/dist/index.js"]
完全重新启动IDE （不要只是重新加载窗口）
检查IDE日志：
- 光标：打开DevTools（帮助>切换开发工具）
- VS代码：输出面板>扩展主机
- 克劳德桌面：查看>开发人员>切换开发人员工具

手动测试：

node /path/to/guardian-mcp/dist/index.js
# Should not crash

Auto-scanning not working

验证规则文件是否存在：

cat .cursor/rules.md
# or
cat .claude/rules.md

检查规则中提到的工具名称：
- 必须引用 check_vulnerabilities
- 使用 scan_mode="critical-high-only" 用于自动扫描
使用关键字进行测试：
- 试着说“安全”或“漏洞”
- 应触发自动扫描
检查IDE支持的规则：
- 光标：✅ 内建支持
- 克劳德桌面：✅ 内建支持
- VS代码：取决于扩展名

Docker container not starting

检查日志：
```
docker logs guardian-mcp
```

验证构建成功：

docker build -t kalmars/guardian-mcp:latest .

手动测试：

docker run -it kalmars/guardian-mcp:latest

检查健康状况：

docker ps --filter name=guardian-mcp
# Status should be "healthy"

OSV.dev API errors

检查互联网连接
验证API是否可访问：
```
curl https://api.osv.dev/v1/query
```
速率限制： OSV.dev有速率限制
- 等几分钟
- 降低扫描频率
防火墙： 确保允许出站HTTPS

贡献

欢迎投稿！需要改进的地方：

额外的生态系统支持（Python、Go、Rust等）
更好的版本范围解析
缓存以减少API调用
IDE特定优化
测试覆盖率
文档改进

许可证

麻省理工学院-参见许可证文件

资源

安全说明

GuardianMCP有助于识别已知漏洞，但 不能替代:

全面的安全审计
渗透测试
安全编码实践
定期更新依赖关系
安全培训

在部署到生产环境之前，始终检查和测试依赖性更新。

Made with 🛡️ by the GuardianMCP team

Report Bug · Request Feature · Star on GitHub

使用说明

监护人MCP🛡️

特性

安全状态

快速开始

选项1:npm（推荐给大多数用户）

选项2：来源

选项3:Docker

IDE设置说明

光标设置

1.安装GuardianMCP

2.配置光标

3.启用自动扫描（可选）

4.重新启动游标

5.测试它

VS代码设置

方法1：使用Continue.dev扩展

方法2：直接配置

3.启用自动扫描

4.重新启动VS代码

Claude桌面设置

1.安装GuardianMCP

2.配置克劳德桌面

3.配置自动扫描

4.重新启动克劳德桌面

风帆设置

1.安装GuardianMCP

2.配置Windsurf

3.创建项目规则

4.重新启动Windsurf

Zed设置

1.安装GuardianMCP

2.配置Zed

3.重新启动Zed

Docker设置

方法一：使用Docker Compose（推荐）

方法2：Docker运行

对于使用Docker的游标：

数据载体安装

Docker健康检查

停止容器

通用MCP设置

1.安装GuardianMCP

2.查找IDE的MCP配置

3.添加GuardianMCP

4.验证设置

用法

手动扫描

自动扫描

刀具参数

示例

扫描模式说明

full 模式

summary 模式

critical-high-only 模式

严重级别

示例规则文件

支持的生态系统

故障排除

贡献

许可证

资源

安全说明

相关 MCP

代码安全扫描工具

MCP代理服务器

JADX APK逆向分析MCP插件

AI代理组件安全扫描器

Nmap 网络扫描 MCP 服务器

嵌入数据库服务器

`full` 模式

`summary` 模式

`critical-high-only` 模式