🚀 守護精靈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)
