MCP Watch 🔍

MCP Watch 🔍

一款全面的 Model Context Protocol（MCP）服务安全扫描器，可检测 MCP 实现中的漏洞和安全问题。

功能

• 🔑 凭证检测 - 查找硬编码的 API 密钥、令牌和不安全的凭证存储
• 🧪 工具投毒 - 检测工具描述中的隐藏恶意指令
• 🎯 参数注入 - 识别可提取敏感 AI 上下文的特殊参数
• 💉 提示词注入 - 扫描提示词操纵和注入攻击
• 🔄 工具变更 - 检测动态工具变更和 rug pull 风险
• 💬 对话窃取 - 查找窃取对话历史记录的触发条件
• 🎨 ANSI 注入 - 检测利用转义序列的隐写攻击
• 📋 协议违规 - 识别 MCP 协议安全违规
• 🛡️ 输入验证 - 查找命令注入、SSRF 和路径遍历问题
• 🎭 服务仿冒 - 检测冒充热门服务的服务
• 🌊 有害流 - 识别危险的数据流模式
• 🔐 权限问题 - 查找权限过度和访问控制问题

快速开始 🚀

选项 1：NPM 包（推荐）

# Install globally
npm install -g mcp-watch

# Scan any GitHub MCP repository
mcp-watch scan https://github.com/user/mcp-server

# Scan your local MCP project
mcp-watch scan-local /path/to/your/mcp-project

选项 2：从 GitHub 源码开始

# Clone and use immediately
git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch
npm install
npm run build

# Scan GitHub repos
npm run scan:github https://github.com/user/mcp-server

# Scan local projects  
npm run scan:local /path/to/your/mcp-project

选项 3：Docker（无需安装）

# Scan without installing anything
docker run --rm mcp-watch scan https://github.com/user/mcp-server
docker run --rm -v $(pwd):/workspace mcp-watch scan-local /workspace

安装

全局安装

npm install -g mcp-watch

本地安装

npm install mcp-watch

从源码安装

git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch
npm install
npm run build

Docker 安装 🐳

使用 Docker 快速开始

# Build and run locally
docker build -t mcp-watch .
docker run --rm mcp-watch scan https://github.com/user/mcp-server

# Build from source
git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch
docker build -t mcp-watch .

Docker Compose（推荐用于生产环境）

# Build and run with Docker Compose
docker compose build
docker compose up mcp-watch

# Or run a one-off scan
docker compose run --rm mcp-watch scan https://github.com/user/repo

Docker 功能

• 🔒 安全：使用非 root 用户，最大限度缩小攻击面
• 📦 优化：多阶段构建，以 Alpine Linux 为基础镜像
• 🚀 生产就绪：可用于部署和 CI/CD
• 🧹 简化：一个经过优化的 Dockerfile 适用于所有使用场景

使用方法

命令行

扫描 GitHub 仓库

# Scan a GitHub repository
mcp-watch scan https://github.com/user/mcp-server

# Scan with JSON output
mcp-watch scan https://github.com/user/mcp-server --format json

# Filter by severity
mcp-watch scan https://github.com/user/mcp-server --severity high

# Filter by category
mcp-watch scan https://github.com/user/mcp-server --category credential-leak

扫描本地项目

# Scan current directory
mcp-watch scan-local .

# Scan specific directory (absolute path)
mcp-watch scan-local /path/to/your/mcp-project

# Scan specific directory (relative path)
mcp-watch scan-local ../my-mcp-server

# Local scan with JSON output
mcp-watch scan-local . --format json

# Local scan with severity filter
mcp-watch scan-local . --severity high

不同安装方式的使用方法

使用 NPM 包

# Global installation (recommended)
npm install -g mcp-watch
mcp-watch scan https://github.com/user/mcp-server
mcp-watch scan-local /path/to/project

使用 GitHub 源码

# Clone and build
git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch
npm install
npm run build

# Use built version
node dist/main.js scan https://github.com/user/mcp-server
node dist/main.js scan-local /path/to/project

# Or use npm scripts
npm run scan https://github.com/user/mcp-server
npm run scan-local /path/to/project

Docker 使用方法 🐳

# Production container
docker run --rm mcp-watch scan https://github.com/user/mcp-server
docker run --rm mcp-watch scan https://github.com/user/mcp-server --format json --severity high

# Docker Compose
docker compose run --rm mcp-watch scan https://github.com/user/repo
docker compose run --rm mcp-watch scan https://github.com/user/repo --format json

# Interactive container
docker run -it --rm mcp-watch sh

选项

• --format <type> - 输出格式：console（默认）或 json
• --severity <level> - 最低严重程度：low、medium、high、critical
• --category <cat> - 按漏洞类别筛选

类别

• credential-leak - 硬编码凭证和不安全的存储
• tool-poisoning - 恶意工具描述
• data-exfiltration - 数据窃取和参数注入
• prompt-injection - 提示词操纵攻击
• tool-mutation - 动态工具变更
• steganographic-attack - 转义序列中的隐藏内容
• protocol-violation - MCP 协议安全问题
• input-validation - 命令注入、SSRF、路径遍历
• server-spoofing - 服务仿冒
• toxic-flow - 危险的数据流
• access-control - 权限和访问问题

输出示例

🔍 Scanning repository: https://github.com/user/mcp-server
📊 Based on vulnerablemcp.info, HiddenLayer, Invariant Labs, and Trail of Bits research

🔑 Scanning for credential vulnerabilities...
🧪 Scanning for tool poisoning vulnerabilities...
🎯 Scanning for parameter injection vulnerabilities...
💉 Scanning for prompt injection vulnerabilities...

📊 MCP SECURITY SCAN RESULTS
===============================

📈 Summary by Severity:
  🚨 CRITICAL: 2
  ⚠️ HIGH: 1
  ⚡ MEDIUM: 3

🔍 Detailed Results:
--------------------

1. 🚨 Hardcoded credentials detected
   📋 ID: HARDCODED_CREDENTIALS
   🎯 Severity: CRITICAL
   📂 Category: credential-leak
   📍 Location: src/config.ts:15
   🔍 Evidence: const apiKey = "sk-***REDACTED***"

开发

项目结构

mcp-watch/
├── main.ts                          # CLI entry point
├── types/
│   └── Vulnerability.ts             # Type definitions
├── scanner/
│   ├── MCPScanner.ts               # Main scanner orchestrator
│   ├── BaseScanner.ts              # Base scanner utilities
│   └── scanners/                   # Individual vulnerability scanners
│       ├── CredentialScanner.ts
│       ├── ParameterInjectionScanner.ts
│       └── ...
├── utils/
│   └── reportFormatter.ts          # Report formatting
└── Docker/                          # Containerization
    ├── Dockerfile                   # Production image
    ├── docker-compose.yml           # Multi-service orchestration (Docker Compose v2)
    └── .dockerignore                # Build optimization

开发脚本

# Build the project
npm run build

# Run in development mode
npm run dev scan https://github.com/user/repo

# Quick scan during development
npm run scan https://github.com/user/repo

# Clean build artifacts
npm run clean

# Type checking
npm run type-check

开发工作流 🚀

本地开发（推荐）

# Install dependencies
npm install

# Run development server
npm run dev

# Run scans during development
npm run scan https://github.com/user/repo

# Type checking
npm run type-check

Docker 开发 🐳

# Build Docker image
docker compose build

# Test the image
docker run --rm mcp-watch scan https://github.com/user/repo

# Test Docker Compose
docker compose run --rm mcp-watch scan --help

添加新的扫描器

1. 在 scanner/scanners/ 中创建新的扫描器
2. 扩展 AbstractScanner
3. 实现 scan() 方法
4. 添加到 MCPScanner.ts

示例：

import { AbstractScanner } from "../BaseScanner";
import { Vulnerability } from "../../types/Vulnerability";

export class MyScanner extends AbstractScanner {
  async scan(projectPath: string): Promise<Vulnerability[]> {
    console.log("🔍 Scanning for my vulnerability type...");
    
    const vulnerabilities: Vulnerability[] = [];
    // Your scanning logic here
    
    return vulnerabilities;
  }
}

安全研究

此工具基于 AI 和网络安全领域领先机构的安全研究成果，可识别 MCP 环境特有的新型攻击向量，包括：

• 参数注入攻击，可提取敏感的 AI 上下文
• 工具投毒，植入隐藏的恶意指令
• 使用触发短语进行对话窃取
• 通过 ANSI 转义序列进行的隐写攻击
• 跨仓库边界的有害 Agent 流

研究资料

• VulnerableMCP Database（vulnerablemcp.info）

  • 全面的 MCP 漏洞数据库
  • 真实世界的攻击模式和示例
  • 定期更新新型攻击途径

• HiddenLayer Research（利用 MCP 工具参数）

  • 可提取敏感数据的参数注入攻击
  • 工具调用历史和对话窃取
  • 系统提示词提取漏洞
  • 思维链操纵
  • 模型名称泄露风险

• Invariant Labs Research（GitHub MCP 漏洞）

  • 工具投毒检测
  • 有害 Agent 流程
  • 跨代码库安全问题
  • 工具功能中的 Rug-pull 更新
  • 防止服务仿冒

• Trail of Bits Research（MCP 安全研究）

  • 对话窃取方法
  • ANSI 注入攻击
  • 协议层漏洞
  • 不安全的凭据存储模式
  • 跨服务影子攻击

• PromptHub Analysis（5 种 MCP 安全漏洞）

  • 命令注入模式（43% 的公开 MCP 服务受影响）
  • SSRF 漏洞统计（30% 允许获取任意 URL）
  • 路径遍历攻击途径（22% 会泄露预期目录之外的文件）
  • 检索 Agent 欺骗（RADE）攻击
  • 工具投毒防范策略

退出代码

• 0 - 未发现严重或高危漏洞
• 1 - 检测到严重或高危漏洞
• 1 - 扫描出错

参与贡献

1. Fork 此代码库
2. 创建功能分支
3. 使用 npm run type-check 运行类型检查
4. 手动测试更改
5. 提交 pull request

GitHub Actions 🚀

此代码库使用自动化工作流进行 CI/CD、安全扫描和依赖项管理：

• CI：每次推送或提交 PR 时自动进行测试和 Docker 验证
• 安全扫描：每日进行安全审计和漏洞检查
• 依赖项更新：每周维护依赖项并修复安全问题
• 发布：自动创建发布资源
• Docker 测试：针对 Docker 的测试和验证

Dependabot 🤖

使用自动化方式管理依赖项：

• npm：每周更新，次要版本和补丁版本自动合并
• GitHub Actions：自动更新 Action
• Docker：更新基础镜像

详细的工作流文档请参阅 GITHUB_ACTIONS.md。

Docker 开发工作流 🐳

# Clone and setup
git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch

# Build Docker image
docker compose build

# Test the image
docker run --rm mcp-watch --help

# Run a scan
docker compose run --rm mcp-watch scan https://github.com/user/repo

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

• 创建 issue 报告 Bug 或提出功能请求
• 创建新 issue 前，请先检查现有 issue
• 报告问题时，请附上扫描输出和代码库详情

Docker 支持 🐳

• 文档：详细的 Docker 使用说明请参阅 DOCKER.md
• 问题：报告问题时，请附上 Docker 版本和 Docker Compose 版本
• 测试：使用生产和开发容器进行测试

---

⚠️ 安全声明：此工具用于识别潜在的安全问题，但不应作为唯一的安全措施。请始终进行人工安全审查并遵循安全最佳实践。