Name: MCP安全扫描器
Author: GuardianMCP

使用说明

GuardianMCP

Security scanner for Model Context Protocol (MCP) servers
Detect vulnerabilities, enforce best practices, and protect your MCP infrastructure.

Quick Start • Security Rules • CLI Reference • Web Dashboard • API Reference • Contributing

什么是GuardianMCP？

GuardianMCP是一个开源安全扫描器，专为 模型上下文协议（MCP） 生态系统。它根据以下内容扫描MCP服务器代码库 OWASP MCP前10名 安全风险和已知的CVE模式。

它由三个部分组成：

组件	描述
`guardianmcp` 命令行界面	您在本地或CI中运行的快速Go二进制文件，用于扫描代码并生成报告
后端API	NestJS REST API，带有用于远程扫描、SSE流和数据持久性的BullMQ作业队列
网络仪表盘	React SPA让团队管理服务器、触发远程扫描、跟踪发现和监控安全态势

$ guardianmcp scan .

guardianmcp v0.1.0 — scanning .

  CRITICAL   [MCP-001] Hardcoded Secrets
             File: src/config.ts:12
             Code: const API_KEY = "sk-proj-abc123..."
             Fix:  Move to environment variable. Rotate immediately.

  HIGH       [MCP-003] Command Injection
             File: src/tools/exec.ts:28
             Code: exec(`git log --author=${req.body.author}`)
             Fix:  Use execFile() with an args array instead of exec().

  Results: 2 critical, 1 high, 0 medium, 0 low
  Files scanned: 18  |  Rules checked: 10  |  Score: 65/100

快速开始

使用CLI进行扫描（无需安装）

npx @guardianmcp/cli scan .

或全局安装

npm install -g @guardianmcp/cli
guardianmcp scan ./my-mcp-server

或从源代码构建

git clone https://github.com/guardianmcp/guardianmcp.git
cd guardianmcp/cli
go build -o guardianmcp .
./guardianmcp scan ./path-to-mcp-server

安全规则

GuardianMCP检查您的MCP服务器代码 10安全规则 与OWASP MCP Top 10保持一致：

ID	规则	严重性	它检测到什么
MCP-001	硬编码秘密	关键的	代码中提交的API密钥、密码、令牌、AWS凭据
MCP-002	缺少身份验证	高	MCP工具端点在没有身份验证中间件的情况下暴露
MCP-003	指令注入	关键的	`exec()` / `execSync()` 未经消毒的用户输入
MCP-004	路径遍历	高	使用用户控制路径的文件操作，无需验证
MCP-005.SSRF。高	对用户控制的URL的HTTP请求
MCP-006	SQL注入	高	SQL查询中的模板文字和字符串连接
MCP-007	OAuth注入	关键的	传递给的授权终结点 `exec()`/`open()` 未经验证
MCP-008	工具中毒	中等	MCP工具描述中的提示注入短语
MCP-009	网络绑定	中等	服务器绑定到 `0.0.0.0` 而不是 `127.0.0.1`
MCP-010	供应链	低临界值	易受攻击的依赖版本（例如。， `mcp-remote` < 1.0.5)

支持的语言

语言	扩展	规则覆盖率
TypeScript	`.ts`	全部10条规则
JavaScript	`.js`	全部10条规则
python `.py`	MCP-001、MCP-003、MCP-009
去吧	`.go`	MCP-001、MCP-002、MCP-003、MCP-004、MCP-005、MCP-009
Java `.java`	MCP-001、MCP-003
红宝石	`.rb`	MCP-001、MCP-003
配置文件	`.json` `.yaml` `.yml` `.env` `.toml` `.ini` `.conf`	MCP-001、MCP-008、MCP-009、MCP-010

安全评分

安全评分按100分制计算，每种严重程度的处罚上限为：

严重性	每次发现的处罚	上限
临界	-25	-50
高	-10	-30
中等	-3	-15
低	-1	-5

得分=100-总罚分 （最小值0）

范围	评级
80-100	优秀
60-79	很好
40-59	需要工作
0-39	严重

CLI参考

`guardianmcp scan [path]`

扫描目录或文件以查找安全漏洞。

# Scan current directory
guardianmcp scan .

# Scan with JSON output
guardianmcp scan ./src --format json

# Generate an HTML report
guardianmcp scan . --format html --output report.html

# Only show critical and high findings
guardianmcp scan . --severity high

# Run specific rules only
guardianmcp scan . --rules MCP-001,MCP-003,MCP-006

# Fail CI if critical findings exist
guardianmcp scan . --severity critical --exit-code

# Upload results to dashboard
guardianmcp scan . --api-key gmcp_live_xxx --server-id your-server-uuid

旗帜：

标志	默认值	描述
`--format`	`terminal`	输出格式： `terminal`, `json`, `html`
`--output`	--	报告输出的文件路径
`--severity`	`info`	最低严重程度： `info`, `low`, `medium`, `high`, `critical`
`--rules`	`all`	逗号分隔的规则ID或 `all`
`--ignore`	--	要忽略的逗号分隔的glob模式
`--exit-code`	`false`	如果发现超过严重性阈值，则以代码1退出
`--api-key`	-	用于上载结果的仪表板API键
`--server-id`	--	仪表板中的服务器ID
`--config`	`.guardianmcp.yml`	配置文件的路径
`--no-color`	`false`	禁用彩色输出
`--quiet`	`false`	抑制除错误外的所有输出

`guardianmcp init`

生成一个 .guardianmcp.yml 默认配置文件。

`guardianmcp version`

打印CLI版本。

配置文件

# .guardianmcp.yml
min-severity: LOW

ignore:
  - "node_modules/**"
  - "vendor/**"
  - "dist/**"
  - "**/*.test.*"

disable-rules: []

format: terminal

# Dashboard integration (optional)
# api-url: https://app.guardianmcp.dev
# api-key: gmcp_live_xxxxx
# server-id: your-server-uuid

CI/CD集成

# .github/workflows/security.yml
name: MCP Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @guardianmcp/cli scan . --severity high --exit-code

网络仪表盘

仪表板提供了一个面向团队的UI，用于管理整个组织的MCP服务器安全。

特性

特性	描述
仪表盘	安全态势概述，包括得分趋势、严重性分解图和主要风险
服务器	使用GitHub存储库URL注册MCP服务器，查看安全评分
远程扫描	直接从仪表板扫描GitHub仓库——选择分支，触发扫描，通过SSE查看实时进度
扫描	完整的扫描历史记录，包括分支、触发源（CLI/Dashboard）、持续时间和分数
研究结果	包含严重性、状态、代码片段、修正和OWASP引用的可筛选表
警报	新发现的电子邮件和Slack通知的可配置规则
报告	可下载的HTML安全报告
设置	团队管理、API密钥、计费和组织设置

扫描的工作原理

GuardianMCP支持两种扫描模式：

1.CLI扫描（本地）

guardianmcp scan ./my-mcp-server --api-key gmcp_live_xxx --server-id <uuid>

在本地或CI中运行CLI。结果通过以下方式上传到仪表板 /cli/upload 终点。

2.远程扫描（仪表板）

从服务器详细信息页面：

从下拉列表中选择分支（从GitHub API获取）
点击 立即扫描
后端将BullMQ作业排队，该作业：
- 克隆仓库(git clone --depth 1 --branch <branch>)
- 运行CLI扫描程序(guardianmcp scan <dir> --format json)
- 分析结果并将结果保存到数据库
- 通过服务器发送事件（SSE）实时传输进度
观看带有步数指示器和查找计数的实时进度面板

技术栈

层	技术
命令行界面	Go 1.24，眼镜蛇，唇彩
后端	NestJS 10、TypeORM、PostgreSQL 15、Redis 7、BullMQ
前端	React 19、TypeScript、Vite 5、顺风CSS、Zustand、React Query、Recharts
认证	JWT（访问+刷新）带Redis黑名单，API密钥认证
队列	BullMQ与Redis——SSE流式异步扫描作业处理
基础设施	Docker、GitHub操作CI/CD

本地运行

先决条件

Node.js >= 20
去 >= 1.22
PostgreSQL 15+
瑞迪斯 7+

1.克隆并安装

git clone https://github.com/guardianmcp/guardianmcp.git
cd guardianmcp

2.启动依赖关系

如果使用Docker：

docker-compose up -d

或者使用本地安装的Postgres和Redis。

3.设置后端

cd backend
cp .env.example .env
# Edit .env with your database credentials
npm install
npm run start:dev

API开始于 http://localhost:3001/api/v1.

4.启动前端

cd frontend
npm install
npm run dev

应用程序打开时间为 http://localhost:5173.

5.构建CLI

cd cli
go build -o guardianmcp .
./guardianmcp scan ./path-to-mcp-server

生成文件快捷方式

make dev-deps        # Start Postgres + Redis (Docker)
make backend         # Start NestJS in watch mode
make frontend        # Start Vite dev server
make cli-build       # Build CLI binary
make test-cli        # Run Go tests
make test-backend    # Run backend tests
make build-all       # Production build everything

API 参考

所有端点都以前缀 /api/v1.身份验证是通过 Authorization: Bearer <jwt> 或 X-API-Key 头球

认证

方法	端点	描述
`POST`	`/auth/register`	创建帐户+组织
`POST`	`/auth/login`	获取访问权限+刷新令牌
`POST`	`/auth/refresh`	旋转刷新令牌
`POST`	`/auth/logout`	黑名单刷新令牌

服务器

方法	端点	描述
`GET`	`/servers`	列出服务器（分页）
`POST`	`/servers`	创建服务器
`GET`	`/servers/:id`	获取服务器详细信息
`PATCH`	`/servers/:id`	更新服务器
`DELETE`	`/servers/:id`	软删除服务器
`GET`	`/servers/:id/branches`	列出服务器的GitHub分支
`POST`	`/servers/:id/scans`	触发远程扫描（接受 `{ branch }`)

扫描和发现

方法	端点	描述
`GET`	`/scans`	列表扫描（可按服务器ID、状态筛选）
`GET`	`/scans/:id`	扫描发现的详细信息
`GET`	`/scans/:id/stream`	SSE实时扫描进度
`GET`	`/findings`	列出调查结果（可按严重性、状态、服务器进行筛选）
`PATCH`	`/findings/:id`	更新查找状态
`POST`	`/findings/bulk`	批量更新结果

CLI上传

方法	端点	描述
`POST`	`/cli/upload`	从CLI上传扫描结果

其他

方法	端点	描述
`GET`	`/health`	健康检查
`POST`	`/alerts`	创建警报规则
`POST`	`/billing/checkout`	开始Stripe结账
`POST`	`/reports/:scanId/generate`	生成HTML报告

项目结构

guardianmcp/
├── cli/                           # Go CLI binary
│   ├── cmd/                       # Cobra commands (scan, init, version)
│   ├── internal/
│   │   ├── scanner/               # File walker + rule engine
│   │   │   └── rules/            # 10 OWASP MCP security rules
│   │   ├── reporter/              # Terminal, JSON, HTML output
│   │   ├── config/                # .guardianmcp.yml parser
│   │   └── uploader/              # Dashboard API client
│   └── templates/                 # HTML report template
├── backend/                       # NestJS API
│   └── src/
│       ├── auth/                  # JWT + API key authentication
│       ├── users/                 # User management
│       ├── organizations/         # Org + team + API keys
│       ├── servers/               # MCP server registry + GitHub branches
│       ├── scans/                 # Scan CRUD + SSE streaming
│       ├── queue/                 # BullMQ scan job processor
│       ├── findings/              # Vulnerability findings
│       ├── cli/                   # CLI upload endpoint
│       ├── alerts/                # Alert rules + notifications
│       ├── billing/               # Stripe integration
│       ├── reports/               # HTML report generation
│       └── common/                # Shared entities, DTOs, enums, utils
├── frontend/                      # React SPA
│   └── src/
│       ├── pages/                 # Page components (auth, dashboard, servers, scans, etc.)
│       ├── components/            # Layout, charts, BranchSelector, ScanProgressPanel
│       ├── hooks/                 # React Query hooks (useServers, useScans, useBranches, useScanSSE)
│       ├── stores/                # Zustand (auth, UI)
│       ├── lib/                   # Axios client, utils, constants
│       └── types/                 # TypeScript interfaces
├── guardianmcp-npm/               # NPM wrapper for npx support
├── docker-compose.yml             # Local dev (Postgres + Redis)
├── docker-compose.prod.yml        # Production compose
├── Makefile                       # Dev shortcuts
└── .github/workflows/             # CI + Release pipelines

贡献

欢迎投稿！以下是如何开始：

分叉存储库
创建分支 为您的功能(git checkout -b feat/my-feature)
进行更改 并添加测试

运行测试:

cd cli && go test ./...          # CLI tests
cd backend && npx tsc --noEmit   # Backend type check
cd frontend && npm run build     # Frontend build

提交拉取请求

添加新的安全规则

创建 cli/internal/scanner/rules/your_rule.go 实施 Rule 接口
创建 cli/internal/scanner/rules/your_rule_test.go 使用表驱动测试
在中注册 cli/internal/scanner/rules/registry.go

许可证

MIT许可证。看许可证了解详情。

GuardianMCP — Securing the MCP ecosystem, one scan at a time.