AI导哈

实时安全过滤器

mcp-yoshi是一款实时安全过滤器，用于检查MCP工具通信中的数据，提供实时安全检查并阻止潜在威胁。

  • by aliksir
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 aliksir/mcp-yoshi

使用说明

日文版本： Readme.ja.md

mcp yoshi

用于MCP（模型上下文协议）工具通信的实时安全过滤器。作为Claude Code钩子运行，检查发送到MCP工具和从MCP工具接收的数据，以评估安全性。

为什么

  • 97%的MCP工具描述不充分，13%与实际实施不一致(研究论文)
  • 现有工具（mcp扫描、mcp漂移检测器）仅提供静态或预运行检查
  • 不存在实时通信过滤器

mcp-yoshi在通信时检查数据，并在检测到问题时立即阻止或发出警告。

特性

出站检查（数据发送到MCP服务器）

ID 检查 检测目标
OUT-001 API密钥模式 用于AWS、OpenAI、GitHub、Slack、Google、Stripe等的API密钥。
OUT-002 私钥 RSA/EC/DSA/OPENSSH私钥
OUT-003 高熵字符串 32+个字符的随机字符串
OUT-004 环境值模式 密码、机密、令牌等的环境变量值。
OUT-005 PII模式 电子邮件地址、电话号码、信用卡号码
OUT-006 大有效载荷 请求超过50KB的有效载荷（批量数据泄露）
OUT-007 路径遍历 敏感路径，如/etc/passwd、~/.ssh/、C:\Windows|

入站检查（从MCP服务器接收的数据）

ID 检查 检测目标
IN-001 提示注入 指令覆盖，如“忽略以前的指令”
IN-002 Shell命令嵌入 通过命令注入 $(...), ; rm, | bash等等。
IN-003 可疑URL/SSRF javascript:URI、URL缩短器、内部网络、云元数据（169.254.169.254等）
IN-004 脚本注入 <script>, eval(), document.cookie等等。
IN-005 工具定义篡改 工具描述中嵌入的隐藏指令（12种模式）
IN-006 ASCII走私 不可见的Unicode字符（U+E0000标签块，零宽度字符）
IN-007 Base64编码有效载荷 根据现有模式重新检查解码的Base64内容
IN-008 响应大小限制 响应超过512KB（上下文窗口中毒预防）
IN-009 隐藏字段 未声明字段，如 _hidden, $meta
IN-010 滥用激励 阻止凭据请求和命令执行提示
IN-011 取样注射 嵌入式LLM标记器([INST], <<SYS>>, <|im_start|>等等）
IN-012 记录泄漏 数据泄露说明（“将此数据发送到…”、“调用记录工具”等）
IN-013 对话标记 对话标记(Human:, Assistant:)在线路开始处注入
IN-014 响应中的凭据 stdout/stderr中的剩余凭据（AWS/OpenAI/GitHub密钥、承载令牌、私钥）
IN-015 参数覆盖 overrideConfig 关键共同发生 mcpServerConfig/NODE_OPTIONS/executablePath 用于允许列表绕过攻击（CVE-2026-40933相关）
IN-017 路径遍历 ../ 目录遍历+敏感路径引用 basePath/filePath/filename (/etc/, /root/, C:\Windows\, /proc/)
IN-018 查询注入 SQL/Cypher/NoSQL注入——块： UNION SELECT, DROP TABLE, MATCH...DELETE, ;-- /警告： ' OR ', sleep()
IN-019 沙盒逃逸 虚拟机/功能/全局访问(globalThis.process.mainModule.require, constructor.constructor() vm2逃逸等）
IN-020 标头欺骗 信任边界绕过(x-request-from: internal, x-forwarded-for: 127.0.0.1等等）
IN-021 浏览器启动RCE 木偶师/剧作家 executablePath 指向shell二进制文件(/bin/sh, /usr/bin/nc等等）

速率限制（通信模式）

ID 检查 检测目标
RATE-001 快速火灾探测 在60秒内调用同一工具10次以上时发出警告

Rug Pull检测（工具定义篡改）

ID 检查 检测目标
RUG-001 工具定义已更改 检测工具定义中的SHA-256哈希值更改
SHADOW-001 工具跟踪 检测来自不同服务器的同名工具注册

在第一次调用时，记录工具定义哈希值。后续检测到更改的调用将触发警告。哈希值将持久化在 ~/.mcp-yoshi/tool-hashes.json，实现跨会话检测。

NFKC标准化（反混淆）

NFKC标准化 在所有入站/出站检查之前应用。这通过全角字符透明地检测混淆（例如。， ignore 编码为全宽）和Unicode兼容字符。

三级判决

判决 行为
通过 未发现任何问题。执行正常进行
警告 警告被添加到克劳德的上下文中。执行继续
块 工具执行被阻止（出站）/显示警告（入站）

需求

  • Node.js 18+

安装

npm install -g mcp-yoshi

设置

# Automatically add hook configuration to Claude Code's settings.json
mcp-yoshi init

# For project-level configuration
mcp-yoshi init --project

这将自动配置以下挂钩：

  • PreToolUse：比赛 mcp__.* ->出境支票
  • PostToolUse：比赛 mcp__.* ->入境支票

用法

设置后，mcp-yoshi自动运行。每次调用MCP工具时都会运行检查。

查看日志

# Show the last 20 log entries
mcp-yoshi logs

# Show the last 50 entries at WARN level or above
mcp-yoshi logs --tail 50 --level warn

# Show BLOCK entries only
mcp-yoshi logs --level block

统计报告

# Show detection statistics for the past 7 days
mcp-yoshi stats

# Past 30 days
mcp-yoshi stats --days 30

查看配置

mcp-yoshi config

允许列表（受信任的服务器）

您可以将特定的MCP服务器注册为受信任的，以跳过检查。 这在以下情况下运行 你自己的责任，但日志记录仍在继续（严重程度：跳过）。

# Add a server to the allowlist (reason recommended)
mcp-yoshi allow memory --reason "Internal knowledge graph, trusted"

# Allow with expiry date
mcp-yoshi allow memory --reason "Temporary exception" --expires 2027-01-01

# Allow once only (auto-removed after first use)
mcp-yoshi allow memory --once --reason "One-time migration"

# List the allowlist
mcp-yoshi allow --list

# Remove from the allowlist
mcp-yoshi allow --remove memory

您还可以直接在中配置它 ~/.mcp-yoshi/config.json:

{
  "allowlist": [
    { "server": "memory", "reason": "Internal knowledge graph", "addedAt": "2026-03-12T00:00:00.000Z" },
    { "server": "temp-srv", "reason": "Migration", "expires": "2026-12-31", "allowOnce": true }
  ]
}

SIEM导出

以SIEM兼容格式导出被阻止的事件：

# JSONL format (Splunk, Datadog)
mcp-yoshi export --format jsonl --days 30

# CEF format (ArcSight, QRadar)
mcp-yoshi export --format cef

# ECS format (Elastic)
mcp-yoshi export --format ecs

项目级别严重性覆盖

创建 .mcp-yoshi.json 在项目根目录中覆盖每个项目的严重性：

{
  "severity": {
    "BLOCK": ["apiKeys", "privateKeys"],
    "WARN": ["highEntropy"]
  }
}

配置

创建 ~/.mcp-yoshi/config.json 以覆盖默认设置。

{
  "logLevel": "warn",
  "checks": {
    "outbound": {
      "highEntropy": false
    }
  },
  "servers": {
    "*": { "enabled": true },
    "memory": { "enabled": true },
    "trusted-server": { "enabled": false }
  },
  "severity": {
    "WARN": ["highEntropy", "pii", "suspiciousUrls", "base64Payload", "largePayload", "responseSizeLimit", "hiddenFields", "rapidFire"],
    "BLOCK": ["apiKeys", "privateKeys", "promptInjection", "shellCommands", "scriptInjection", "toolTampering", "envValues", "asciiSmuggling", "pathTraversal", "elicitationAbuse"]
  }
}

每台服务器配置

使用 servers 部分用于控制每个MCP服务器的过滤器打开/关闭和检查项目。

{
  "servers": {
    "*": { "enabled": true },
    "trusted-internal": { "enabled": false },
    "external-api": {
      "enabled": true,
      "checks": {
        "outbound": { "pii": false },
        "inbound": { "promptInjection": true }
      }
    }
  }
}
密钥 描述
"*" 默认设置（应用于未定义的服务器）
"<server-name>" 适用于工具匹配 mcp__<server-name>__*
  • enabled: false ->完全跳过对该服务器的检查
  • checks ->覆盖每台服务器的全局设置

配置参考

选项 默认值 描述
logDir ~/.mcp-yoshi/logs 日志输出目录
logLevel info info：记录所有内容， warn：警告及以上， none：无日志记录
checks.outbound.* true 启用/禁用单个出站检查
checks.inbound.* true 启用/禁用单个入站检查
servers {"*": {"enabled": true}} 每台服务器打开/关闭
severity.WARN ["highEntropy", "pii", "suspiciousUrls", ...] 检查分类为WARN的ID
severity.BLOCK ["apiKeys", "privateKeys", "promptInjection", ...] 检查分类为BLOCK的ID

卸载

# Remove hook configuration
mcp-yoshi uninstall

# Remove the package
npm uninstall -g mcp-yoshi

与现有工具的比较

工具 时间 范围
mcp扫描 预运行（静态检查） 工具定义安全
mcp漂移探测器 定期（变化检测） 工具定义篡改
mcp yoshi 实时（通信期间） 传输/接收数据的安全性

安全建议

关于 .mcp.json 在外部存储库中

克隆外部存储库时，MCP服务器在其 .mcp.json 应被视为 不可信的.恶意攻击 .mcp.json 已报告自动注册工具的文件。

  • 做 不 添加来自外部的服务器 .mcp.json 对排外主义者
  • 在启用mcp-yoshi检查的情况下使用它们
  • 检查可疑工具调用的日志

备注

  • 演出：钩子在每次MCP工具调用时运行，会增加轻微的延迟（大约几十毫秒）。如果这是一个问题，请更改 logLevel 到 "warn" 或将受信任的服务器设置为 enabled: false
  • 假阳性：高熵字符串和PII模式可能与合法数据匹配。如果经常出现误报，请禁用相关检查或将其严重性降级为警告
  • 探测范围：检测基于正则表达式模式匹配和NFKC规范化。高度模糊的攻击或未知模式可能无法被发现。我们建议将mcp-yoshi与其他安全工具（如mcp-scan）一起使用
  • 地毯拉力检测：工具定义哈希值保存在 ~/.mcp-yoshi/tool-hashes.json。如果文件损坏，它会自动从空状态重新启动

许可证

麻省理工学院

相关 MCP