MCP扫描器

Name: MCP扫描器
Author: cisco-ai-defense

作者：cisco-ai-defense642 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

MCP Scanner

一个用于扫描MCP（模型上下文协议）服务器和工具潜在安全问题的Python工具。MCP Scanner结合了Cisco AI Defense inspect API、YARA规则和LLM作为裁判来检测恶意MCP工具。

概述

MCP Scanner提供了一个全面的解决方案，用于扫描MCP服务器和工具的安全问题。它利用了三个强大的扫描引擎（Yara、LLM作为裁判、Cisco AI Defense），这些引擎可以一起使用或独立使用。

SDK设计易于使用，同时提供了强大的扫描能力、灵活的身份验证选项和自定义功能。

MCP Scanner

功能

多种模式： 作为独立的CLI工具运行或REST API服务器
多引擎安全分析： 根据需要使用所有三个扫描引擎或单独使用。
全面扫描： 扫描MCP工具、提示和资源以发现安全问题
明确的身份验证控制： 对身份验证进行细粒度控制，具有明确的Auth参数。
OAuth支持： 支持SSE和可流式传输HTTP连接的完整OAuth身份验证。
自定义端点： 配置API端点以支持任何Cisco AI Defense环境。
MCP服务器集成： 直接连接到MCP服务器以扫描工具、提示和资源，并具有灵活的身份验证。
可定制的YARA规则： 添加自己的YARA规则以检测特定模式。
全面报告： 关于检测到的安全问题的详细报告。

安装

先决条件

Python 3.11+
uv（Python包管理器）
有效的Cisco AI Defense API密钥（可选）
LLM提供商API密钥（可选）

从PyPI安装

uv venv -p <Python版本小于或等于3.13> /path/to/your/choice/of/venv/directory
source /path/to/your/choice/of/venv/directory/bin/activate
uv pip install cisco--ai-mcp-scanner

从源码安装

git clone https://github.com/cisco-ai-defense/mcp-scanner
cd mcp-scanner
# 使用uv安装（推荐）

uv venv -p <Python版本小于或等于3.13> /path/to/your/choice/of/venv/directory

source /path/to/your/choice/of/venv/directory/bin/activate

uv pip install .
# 或者在开发模式下安装
uv pip install -e .

快速开始

环境设置

核心API配置

Cisco AI Defense API（仅API分析器所需）
export MCP_SCANNER_API_KEY="your_cisco_api_key"
export MCP_SCANNER_ENDPOINT="https://us.api.inspect.aidefense.security.cisco.com/api/v1"
# 对于其他端点，请访问 https://developer.cisco.com/docs/ai-defense/getting-started/#base-url

LLM配置（用于LLM分析器）

测试过的LLMs： OpenAI GPT-4o 和 GPT-4.1

# 使用AWS Bedrock Claude和AWS凭证（配置文件）
export AWS_PROFILE="your-profile"
export AWS_REGION="us-east-1"
export MCP_SCANNER_LLM_MODEL="bedrock/anthropic.claude-sonnet-4-5-20250929-v2:0" # 任何AWS Bedrock支持的模型

# 使用AWS Bedrock Claude和API密钥（Bearer令牌）
export MCP_SCANNER_LLM_API_KEY="bedrock-api-key-..." # 通过Amazon Bedrock -> API Keys生成
export AWS_REGION="us-east-1"
export MCP_SCANNER_LLM_MODEL="bedrock/us.anthropic.claude-sonnet-4-5-20250929-v2:0" # 任何AWS Bedrock支持的模型

# LLM提供商API密钥（LLM分析器所需）
export MCP_SCANNER_LLM_API_KEY="your_llm_api_key"  # OpenAI

# LLM模型配置（可选 - 提供默认值）
export MCP_SCANNER_LLM_MODEL="gpt-4o"  # 任何LiteLLM支持的模型
export MCP_SCANNER_LLM_BASE_URL="https://api.openai.com/v1"  # 自定义LLM端点
export MCP_SCANNER_LLM_API_VERSION="2024-02-01"  # API版本（如果需要）

# 对于Azure OpenAI（示例）
export MCP_SCANNER_LLM_BASE_URL="https://your-resource.openai.azure.com/"
export MCP_SCANNER_LLM_API_VERSION="2024-02-01"
export MCP_SCANNER_LLM_MODEL="azure/gpt-4"

# 对于扩展思维模型（更长的超时时间）
export MCP_SCANNER_LLM_TIMEOUT=300

使用本地LLM（无需API密钥）

如果你正在使用本地LLM端点，如Ollama、vLLM或LocalAI， MCP_SCANNER_LLM_API_KEY变量仍然需要设置，但可以设置为任意值。

示例：

export MCP_SCANNER_LLM_API_KEY=test
export MCP_SCANNER_LLM_ENDPOINT=http://localhost:11434

快速开始示例

最快的方式是使用mcp-scanner CLI命令。全局标志（如--analyzers、--format等）必须放在子命令之前。

CLI用法

# 扫描本机上的已知客户端配置
mcp-scanner --scan-known-configs --analyzers yara --format summary

# Stdio服务器（示例使用uvx mcp-server-fetch）
mcp-scanner --stdio-command uvx --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch --analyzers yara --format summary

# 远程服务器（deepwiki示例）
mcp-scanner --server-url https://mcp.deepwki.com/mcp --analyzers yara --format summary

# MCP Scanner作为REST API
mcp-scanner-api --host 0.0.0.0 --port 8080

SDK用法

import asyncio
from mcpscanner import Config, Scanner
from mcpscanner.core.models import AnalyzerEnum

async def main():
    # 创建带有你的API密钥的配置
    config = Config(
        api_key="your_cisco_api_key",
        llm_provider_api_key="your_llm_api_key"
    )

    # 创建扫描器
    scanner = Scanner(config)

    # 扫描远程服务器上的所有工具
    tool_results = await scanner.scan_remote_server_tools(
        "https://mcp.deepwki.com/mcp",
        analyzers=[AnalyzerEnum.API, AnalyzerEnum.YARA, AnalyzerEnum.LLM]
    )

    # 打印工具结果
    for result in tool_results:
        print(f"工具: {result.tool_name}, 安全: {result.is_safe}")

    # 扫描服务器上的所有提示
    prompt_results = await scanner.scan_remote_server_prompts(
        "http://127.0.0.1:8000/mcp",
        analyzers=[AnalyzerEnum.LLM]
    )

    # 打印提示结果
    for result in prompt_results:
        print(f"提示: {result.prompt_name}, 安全: {result.is_safe}")

    # 扫描服务器上的所有资源
    resource_results = await scanner.scan_remote_server_resources(
        "http://127.0.0.1:8000/mcp",
        analyzers=[AnalyzerEnum.LLM],
        allowed_mime_types=["text/plain", "text/html"]
    )

    # 打印资源结果
    for result in resource_results:
        print(f"资源: {result.resource_name}, 安全: {result.is_safe}, 状态: {result.status}")

# 运行扫描器
asyncio.run(main())

子命令概述

remote： 扫描远程MCP服务器（SSE或可流式传输HTTP）。支持--server-url，可选--bearer-token。
stdio： 启动并扫描stdio MCP服务器。需要--stdio-command；接受--stdio-args，--stdio-env，可选--stdio-tool。
config： 从特定的MCP配置文件扫描服务器。需要--config-path；可选--bearer-token。
known-configs： 从本机上已知的客户端配置位置扫描服务器；可选--bearer-token。
prompts： 扫描MCP服务器上的提示。需要--server-url；可选--prompt-name，--bearer-token。
resources： 扫描MCP服务器上的资源。需要--server-url；可选--resource-uri，--mime-types，--bearer-token。

注意：顶级标志（例如--server-url，--stdio-*，--config-path，--scan-known-configs）在不使用子命令时仍受支持，但建议使用子命令。

额外示例

扫描已知的MCP配置路径（Windsurf，Cursor，Claude，VS Code）

# 使用已知配置位置中定义的所有服务器进行YARA扫描
mcp-scanner --scan-known-configs --analyzers yara --format summary

# 详细输出
mcp-scanner --scan-known-configs --analyzers yara --detailed

扫描特定的MCP配置文件

# 如果需要，请自行展开~
mcp-scanner --config-path "$HOME/.codeium/windsurf/mcp_config.json" \
 --analyzers yara --format by_tool

扫描stdio MCP服务器

# 使用重复的--stdio-arg以可靠传递参数
mcp-scanner --analyzers yara --format summary \
  stdio --stdio-command uvx \
  --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch

# 或列表形式（确保不会与后续标志冲突）
mcp-scanner --analyzers yara --detailed \
  stdio --stdio-command uvx \
  --stdio-args --from mcp-server-fetch mcp-server-fetch

# 仅扫描stdio服务器上的特定工具
mcp-scanner --analyzers yara --format summary \
  stdio --stdio-command uvx \
  --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch \
  --stdio-tool fetch

使用Bearer令牌与远程服务器（非OAuth）

# 直接远程服务器使用Bearer令牌
mcp-scanner --analyzers yara --format summary \
  remote --server-url https://your-mcp-server/sse --bearer-token "$TOKEN"

# 将Bearer令牌应用于从配置中发现的所有远程服务器
mcp-scanner --analyzers yara --detailed known-configs --bearer-token "$TOKEN"
mcp-scanner --analyzers yara --format by_tool \
  config --config-path "$HOME/.codeium/windsurf/mcp_config.json" --bearer-token "$TOKEN"

扫描提示

# 扫描MCP服务器上的所有提示
mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp

# 扫描所有提示并显示详细输出
mcp-scanner --analyzers llm --detailed prompts --server-url http://127.0.0.1:8000/mcp

# 扫描所有提示并显示表格格式
mcp-scanner --analyzers llm --format table prompts --server-url http://127.0.0.1:8000/mcp

# 扫描特定名称的提示
mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp --prompt-name "greet_user"

# 获取原始JSON输出
mcp-scanner --analyzers llm --raw prompts --server-url http://127.0.0.1:8000/mcp

扫描资源

# 扫描MCP服务器上的所有资源
mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp

# 扫描所有资源并显示详细输出
mcp-scanner --analyzers llm --detailed resources --server-url http://127.0.0.1:8000/mcp

# 扫描所有资源并显示表格格式
mcp-scanner --analyzers llm --format table resources --server-url http://127.0.0.1:8000/mcp

# 扫描特定URI的资源
mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  --resource-uri "file://test/document.txt"

# 使用自定义MIME类型过滤扫描
mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  --mime-types "text/plain,text/html,application/json"

API服务器用法

API服务器提供了MCP扫描器功能的REST接口，允许你将安全扫描集成到Web应用程序、CI/CD管道或其他服务中。它暴露了与CLI工具相同的扫描能力，但通过HTTP端点实现。

# 启动API服务器（从.env文件加载配置）
mcp-scanner-api --port 8000

# 或使用自定义主机和端口
mcp-scanner-api --host 0.0.0.0 --port 8080

# 开启开发模式自动重载
mcp-scanner-api --reload

一旦运行，API服务器提供了以下端点：

/scan-tool - 扫描MCP服务器上的特定工具
/scan-all-tools - 扫描MCP服务器上的所有工具
/scan-prompt - 扫描MCP服务器上的特定提示
/scan-all-prompts - 扫描MCP服务器上的所有提示
/scan-resource - 扫描MCP服务器上的特定资源
/scan-all-resources - 扫描MCP服务器上的所有资源
/health - 健康检查端点

文档可在docs/api-reference.md或在服务器运行时的交互式文档http://localhost:8000/docs中找到。

输出格式

扫描器支持多种输出格式：

summary：简洁概述，包含关键发现
detailed：全面分析，包含完整的发现分解
table：干净的表格格式
by_severity：按严重性级别分组的结果
raw：原始JSON输出

示例输出

详细格式

mcp-scanner --server-url http://127.0.0.1:8001/sse --format detailed

=== MCP Scanner Detailed Results ===

扫描目标: http://127.0.0.1:8001/sse

工具: execute_system_command
状态: 完成
安全: 否
分析器结果:
  • api_analyzer:
    - 严重性: 高
    - 威胁总结: 检测到1个威胁：安全违规
    - 威胁名称: 安全违规
    - 总发现数: 1
  • yara_analyzer:
    - 严重性: 高
    - 威胁总结: 检测到2个威胁：系统访问，命令注入
    - 威胁名称: 安全违规，可疑代码执行
    - 总发现数: 2
  • llm_analyzer:
    - 严重性: 高
    - 威胁总结: 检测到2个威胁：提示注入，工具中毒
    - 威胁名称: 提示注入，可疑代码执行
    - 总发现数: 2

表格格式

mcp-scanner --server-url http://127.0.0.1:8002/sse --format table

=== MCP Scanner Results Table ===

扫描目标: http://127.0.0.1:8002/sse

扫描目标                   工具名称     状态     API      YARA     LLM      严重性
-----------------------------------------------------------------------------------------
http://127.0.0.1:8002/sse     exec_secrets  不安全     高       高       高       高
http://127.0.0.1:8002/sse     safe_command  安全       安全     安全     安全     安全

文档

详细的文档见docs/目录：

架构 - 系统架构和组件
身份验证 - OAuth和安全配置
编程用法 - 编程用法示例和高级用法
API参考 - 完整的REST API文档
输出格式 - 详细的输出格式选项