AI代理工具安全扫描器

mcp-shark

Security scanner for AI agent tools — built for security and platform engineers working with MCP in the IDE.

Run a local static scan over MCP IDE configs and embedded tool metadata: 41 rules (including AAuth visibility), toxic-flow heuristics, and SARIF / HTML / JSON reports. There is no hosted config-scan backend.

Add an optional local HTTP proxy with an in-browser dashboard so live traffic, findings, AAuth signals, and playground checks stay in one place—without sending your configs to a vendor.

You can

• Use Traffic for live JSON-RPC capture, filters, export, and AAuth posture chips
• Run Local Analysis for OWASP-style findings over captured traffic
• Run YARA Detection for traffic pattern rules (native engine when installed, regex fallback otherwise)
• Open AAuth Explorer for a graph of agents, missions, resources, and signing / access signals
• Use MCP Playground to call tools, prompts, and resources through the proxy
• Optionally run Smart Scan (AI-backed; uses your API token when enabled)
• Use Server setup to detect configs, convert format, and route the editor through the proxy

Privacy: static scans need no cloud and send no telemetry. Refreshing rule catalogs is opt-in HTTPS (update-rules).

仪表板概览

这些照片来自现场 仪表盘 和 实际捕获的流量 （虚拟MCP或您自己的上游）。开始 npx @mcp-shark/mcp-shark serve --open. 智能扫描 下面没有显示-它取决于可选的远程API令牌。 MCP游乐场 一旦您至少配置了一个MCP上游（Playground捕获使用加载了工具的演示服务器），就会出现。

实时流量捕获

IDE和每个MCP上游之间的每一个JSON-RPC帧都被捕获了完整的报头、正文、时序和AAuth姿态芯片。按方法、状态、服务器、会话、AAuth代理/任务/姿态过滤。

MCP游乐场

选择上游，装载 工具, 提示，以及 资源 从该服务器，然后调用工具或通过代理读取资源——这对于在行为到达IDE之前进行验证非常有用。下面的视图显示了已配置演示MCP的工具列表。

AAuth浏览器

在捕获的流量中观察到的每个代理/任务/资源/签名算法/访问模式的强制知识图。使用 生成样本数据 获取快速演示图，或通过代理捕获真实的AAuth形状的流量。

局部分析

基于离线规则的扫描仪对捕获的流量进行扫描。这 AAuth姿势 该卡总结了签名/aauth感知/承载/无身份验证分布；这 有毒流量（代理流量） 面板根据观察到的结果推断跨服务器配对 tools/list 响应。如果数据包已在数据库中，请使用 从DB回放 （当没有连接活动MCP时），然后 分析 填充结果——下面的视图是在运行之后。

YARA 检测

相同 局部分析 选项卡：切换到 YARA 检测 对于交通规则引擎——引擎状态，八个预定义规则（切换、编辑、删除），以及 新规则 为了你自己的模式。当原住民 yara 模块未安装，扫描仍使用内置的正则表达式回退运行（请参阅 docs/local-analysis.md).

新规则 使用启动器模板（meta， strings，以及 condition).编辑规则文本，然后 保存规则 将其作为自定义模式添加到内置组件旁边。

服务器设置

自动检测Cursor/Copyx/Windsurf配置，将其转换为mcp-shark格式，并在启动时修补IDE以通过代理进行路由。

为什么选择mcp鲨鱼？

MCP设置通常将秘密、广泛的工具访问和多个服务器混合在一个代理上下文中；如果不检查配置，很容易错过问题。请参阅 OWASP MCP前10名 以结构化的方式查看可能出错的地方。

mcp-shark在您的机器上运行-没有API密钥或托管扫描后端。安装时使用 npx 并在当地审查调查结果。

有毒物质流动分析

扫描仪模拟MCP服务器的运行方式 在代理上下文中编写 并标记风险能力配对（例如，秘密访问与外部出口相结合）：

  ▲ HIGH  notify-server → repo-server
    Untrusted content in one tool’s channel could lead the agent to
    take a destructive action in another (e.g. push code).

  ▲ MEDIUM  browser-server → filesystem-server
    Web-sourced context could be chained into local file operations.

将mcp-shark的发现作为您自己的威胁模型的输入，而不是作为完整的审计。

特性

快速开始

# Scan your MCP setup (default command)
npx @mcp-shark/mcp-shark

# Auto-fix issues (with interactive confirmation)
npx @mcp-shark/mcp-shark scan --fix

# See full attack chain narratives
npx @mcp-shark/mcp-shark scan --walkthrough

# Pin tool definitions (lockfile) to spot unexpected changes
npx @mcp-shark/mcp-shark lock

# Check environment health
npx @mcp-shark/mcp-shark doctor

# Show all detected servers
npx @mcp-shark/mcp-shark list

# Download latest rule packs (OWASP, Agentic Security)
npx @mcp-shark/mcp-shark update-rules

# Watch for config changes
npx @mcp-shark/mcp-shark watch

# Interactive terminal UI
npx @mcp-shark/mcp-shark tui

# Generate HTML report
npx @mcp-shark/mcp-shark scan --format html --output report.html

# CI mode (exits 1 on critical/high)
npx @mcp-shark/mcp-shark scan --ci --format sarif

命令

CLI标志

scan （默认命令）

其他命令

如何 scan 作品

CLI scan 命令是 静态：它从IDE配置文件中读取MCP条目（请参阅 支持的IDE 和可选项目 ./mcp.json)并分析 那里写着什么确实如此 不 连接到正在运行的MCP服务器或调用 tools/list.

• 始终扫描： 每个服务器块的 command, args, env, url，以及相关字段（机密 env、不安全的生成模式、HTTP URL等）。
• 工具级别规则 （声明性包、命令注入启发式、工具中的有毒流分类 名字等）仅在该服务器条目包括嵌入式 tools 数组（名称、描述、模式）。如果 tools 省略了——通常用于 command/stdio-只有配置--扫描可能会报告 已检查0个工具 即使Cursor正在正常运行服务器。

要在CI或测试仓库中执行完整的规则覆盖，请将工具元数据嵌入到扫描程序读取的同一JSON中，或使用项目本地 mcp.json 线束（参见 --ide Project).

它涵盖了什么

mcp鲨鱼瞄准 磁盘上已有的配置和元数据 （加上可选的本地监控）。它有助于捕捉常见的错误配置和风险组合；将输出视为您自己审核的输入，而不是保证没有任何错误。

规则可扩展性

可下载的规则包（JSON）

规范 注册表 （清单、包文件、验证CI和模式注释）位于 **mcp鲨鱼/规则包**npm包嵌入了副本； update-rules 将相同的工件拉入 .mcp-shark/rule-packs/.

mcp-shark附带了30条声明性规则作为JSON包（OWASP mcp、代理安全倡议、通用安全、AAuth可见性），以及 toxic-flow-heuristics 包装(toxic_flow_rules 用于跨服务器组合）。新的漏洞目录可以添加为 .json 文件——没有JavaScript，没有代码更改。

# Fetch latest rule packs from the registry
npx @mcp-shark/mcp-shark update-rules

# Use a custom/enterprise registry
npx @mcp-shark/mcp-shark update-rules --source https://internal.corp/rules/manifest.json

下载的包缓存在 .mcp-shark/rule-packs/ 并在每次扫描时与内置规则合并。

{
  "id": "owasp-mcp-2027",
  "name": "OWASP MCP Top 10 (2027)",
  "version": "1.0.0",
  "rules": [
    {
      "id": "MCP01-token-mismanagement",
      "name": "Token Mismanagement",
      "severity": "critical",
      "framework": "OWASP-MCP",
      "description": "Detects hardcoded tokens in MCP configs",
      "patterns": [
        { "regex": "(api[_-]?key|token)\\s*[:=]", "flags": "i", "label": "API key pattern" }
      ],
      "scope": ["tool", "prompt", "resource", "packet"],
      "exclude_patterns": [{ "regex": "\\$\\{|process\\.env" }],
      "match_mode": "any"
    }
  ]
}

自定义YAML规则（每个项目）

创建 .mcp-shark/rules/ 在您的项目中添加轻量级自定义规则：

# .mcp-shark/rules/no-production-keys.yaml
id: custom-no-prod-keys
name: No Production Keys
severity: critical
description: Detects production API keys in MCP configs
match:
  env_pattern: "^(PROD_|PRODUCTION_)"
  value_pattern: "^sk-live|^pk-live"
message: "Production key detected in {key} — use staging keys for development"

YAML规则和JSON包在扫描时都会自动加载。通过提交文件夹与您的团队共享。

用户可重写数据(.mcp-shark/)

每个内置数据源都可以通过项目根目录中的YAML文件进行扩展或覆盖：

用户数据在扫描时与内置数据合并。无需重建。

GitHub行动

# .github/workflows/mcp-security.yml
name: MCP Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mcp-shark/scan-action@v1
        with:
          format: sarif
          fail-on: high
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp-shark-results.sarif

支持的IDE

安全规则（41）

浏览器仪表板

MCP鲨鱼船 浏览器内仪表板 在本地代理上进行实时MCP流量、分析和探索：

npx @mcp-shark/mcp-shark serve --open

与旧快捷方式相同（否 serve 子命令）：

npx @mcp-shark/mcp-shark --open

仪表板提供：

• 多服务器聚合和实时流量捕获（过滤器、导出、AAuth姿态芯片）
• MCP游乐场 --通过代理对选定的上游调用工具、提示和资源
• 局部分析 --对捕获的流量进行OWASP式静态扫描； YARA 检测 用于流量模式规则（安装时为本机引擎，否则为正则表达式回退）
• AAuth浏览器 --在流量中观察到的代理/任务/资源/签名/访问信号图
• 智能扫描 -可选的AI支持扫描（需要配置API令牌）
• In-app API文档、服务器设置、日志和优雅的关闭

零接触式第一双靴子

仪表板在您第一次在新机器上启动时会自动启动——无需单击安装向导：

1. 如果 ~/.mcp-shark/mcps.json 已经声明上游（例如，来自之前的运行、手动编辑或 testbed:up)，代理直接从该配置开始。
2. 否则，在全新安装时（否 ~/.mcp-shark MCP Shark扫描以寻找真正的编辑器MCP配置(~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.codex/config.toml).如果发现一个具有实际上游，它会自动导入它们，写道 ~/.mcp-shark/mcps.json，启动代理，并修补编辑器配置，以便编辑器通过代理路由。
3. 如果两条路径都不适用，则UI将以仅监视模式启动，设置面板仍可用于手动配置。

要在计算机上重新触发首次启动行为，请删除 ~/.mcp-shark/ 并重新启动UI。

建筑

┌────────────────────────────────────────────────────┐
│  CLI (Commander.js)                                │
│  scan · lock · diff · doctor · list · watch · tui  │
│  update-rules · serve                              │
├──────────────┬──────────────┬──────────────────────┤
│  ConfigScanner│  ScanService  │  StaticRulesService  │
│  15 IDEs      │  orchestrator │  41 rules            │
├──────────────┴──────────────┴──────────────────────┤
│  Data layer (JSON + user YAML/JSON overrides)      │
│  ┌────────────┬──────────────┬───────────────────┐ │
│  │ rule-packs │ secret-      │ tool-             │ │
│  │ (30 rules) │ patterns.json│ classifications   │ │
│  ├────────────┼──────────────┼───────────────────┤ │
│  │ toxic-flow │ rule-        │ .mcp-shark/*.yaml │ │
│  │ rules.json │ sources.json │ (user overrides)  │ │
│  └────────────┴──────────────┴───────────────────┘ │
├────────────────────────────────────────────────────┤
│  JS plugins (11 rules needing algorithmic logic)   │
│  + DeclarativeRuleEngine (30 pattern-based rules)  │
└────────────────────────────────────────────────────┘

设计原则：

• 数据优先 --声明性规则、秘密模式、工具分类和有毒流默认值以JSON形式提供； 30 的 41 规则是模式包，您可以在不分叉这些定义的情况下扩展或覆盖它们。
• 用户可重写 --内置数据可以通过以下方式扩展 .mcp-shark/*.yaml （以及JSON包删除），如上所述。
• 混合规则引擎 --另一个 11 规则是JS插件，启发式需要代码。两个源在扫描时合并。
• 零配置扫描 — npx 然后走。自动检测以下IDE路径以及项目本地路径 mcp.json 变体。

文档

• 规则包注册表 --官方 manifest.json JSON包被 update-rules
• 入门指南 --安装和设置
• 特性 --详细的功能文档
• 用户指南 --完整的使用指南
• 配置 --配置文件和环境变量
• 局部分析 --静态安全分析和YARA交通规则
• AAuth可见性 --RFC 9421/AAuth可观察性
• 建筑 --系统设计
• 数据库体系结构 --SQLite模式参考
• API 参考 -API端点
• 故障排除 --常见问题和修复
• 发展 --贡献和项目惯例
• 包裹检查 --npm包布局

需求

• Node.js：20.0.0或更高
• 操作系统：macOS、Windows或Linux

许可证

来源可用非商业许可证

• ✅ 查看、分叉、修改、运行以供个人、教育或公司内部使用
• ❌ 未经书面许可，销售、转售或整合到付费产品/服务中

看 许可证 完整条款。

CLI演示

与同一衬垫 快速开始 （默认值 scan).终端输出取决于您的配置：

npx @mcp-shark/mcp-shark

支持

• 问题: GitHub 问题
• 网站: 麦普沙克.sh