MCP-Bastion

MCP-Bastion

README · Documentation · Demos · Dashboard / Observability · Multi-language · Benchmark · License · Security

Current release: 5.1.0 · Docker v5.1.0 · 26 PyPI packages · CHANGELOG

前往	链接
文档 / 演示	https://vaquarkhan.github.io/MCP-Bastion/ · 产品介绍视频 · 集成
基准测试 / 安全演示文稿（PDF）	MCP-Security-Deck-v3.pdf · 原始文件下载
文档手册	https://vaquarkhan.github.io/MCP-Bastion/guide/handbook.html
演示（攻击、仪表板、有效载荷，所有语言）	https://vaquarkhan.github.io/MCP-Bastion/guide/demos.html
仪表板与可观测性（OTEL 可选）	https://vaquarkhan.github.io/MCP-Bastion/guide/observability.html
多语言套件	https://vaquarkhan.github.io/MCP-Bastion/guide/multi-language.html · 套件仓库
MCP Test Harness（姊妹产品——MCP 服务的 CI 门禁）	https://github.com/vaquarkhan/mcp-test-harness · 与 Bastion E2E 搭配使用
文档中心	https://vaquarkhan.github.io/MCP-Bastion/guide/
实测基准测试（可复现）	docs/BENCHMARKS.md

面向 MCP Agent 的零信任控制平面。 你的 Agent 可以调用数据库、API 和 shell 工具。一个恶意提示词就可能泄露 PII；一个失控循环可能在几分钟内耗尽你的 API 预算；同一服务上的三个 Agent 若没有身份边界，就可能引发混淆代理事件。MCP-Bastion 为你的 MCP 服务加上本地防护措施：Agent IAM、供应链校验和、注入拦截、PII 脱敏和防止钱包耗尽的限额，开销低于 5ms，无需第三方安全 API。

指导原则： 坚持做一个零基础设施、即插即用的库——充当可与任何网关组合使用的防护大脑，而不是网关本身。策略：docs/ZERO_INFRA_STRATEGY.md。

实测证明（离线、可复现）

演示文稿（可分享给评估人员）： MCP-Security-Deck-v3.pdf — 安全 + FinOps 证明材料包（直接下载）。

门禁	结果	复现方法
注入启发式检测	在已发布语料库中，攻击拦截率 100% · 良性误报率 0%	pytest tests/test_injection_efficacy.py · docs/BENCHMARKS.md
工具目录扫描	注入 / 密钥 / 同形异义字符 / 影子工具 / 嵌套弱模式	mcp-bastion scan examples/fixtures/tools-poisoned.json
FinOps	输出预算最多节省 ~99.7% · 发现令牌减少 ~85%	docs/BENCHMARKS.md
有毒流污点检测	会话中的 PII/密钥 → 带 URL/email 参数的出站工具会在进程内被拦截	bastion.yaml 中的 toxic_flow · docs/THREAT_MODEL.md

扫描 → 测试 → 强制执行（没有其他工具具备这三项能力）

阶段	内容	命令
扫描	部署前的静态工具定义检查（注入、密钥、同形异义字符、指纹漂移、模式前置条件）	mcp-bastion scan tools.json
审计	本地 MCP 客户端配置风险报告（权限过宽的工具、长期有效的凭据、文件系统服务）	mcp-bastion audit
测试	针对 bastion.yaml 的集成式红队测试 + 在 CI 中搭配 MCP Test Harness 使用	mcp-bastion redteam · docs/BASTION_AND_TEST_HARNESS.md
强制执行	在每个 MCP 方法上运行时中间件	secure_fastmcp(mcp) 或 bastion.yaml
scan 与 audit——输入不同，关注的问题也不同

	mcp-bastion scan	mcp-bastion audit
检查对象	工具目录（tools.json / tools/list 导出）	磁盘上的 MCP 客户端配置（mcp.json、Claude Desktop 配置等）
关注问题	“这些工具元数据是否遭到投毒或发生偏移？”	“Agent 已经能访问这台机器上的哪些内容？”
发现问题	描述中的注入、架构中的机密、同形异义字符、指纹偏移、脆弱或不受限的 inputSchema 结构	过度宽泛的工具授权（*）、env 中的长期凭据、文件系统服务提示
适用时机	部署或接入某个服务的工具之前（CI / 部署前）	收紧笔记本或工作区策略之前（本地卫生检查）

两者相辅相成：先对主机表面进行 audit，再对接入的工具进行 scan。二者都不能取代运行时 enforce。

mcp-bastion scan 还支持通过 --skills DIR 离线检查 Agent 技能文件。依赖项 CVE：运行 mcp-bastion osv-refresh，然后运行 mcp-bastion osv-scan（默认使用本地数据库；可选择启用 --online，失败时放行）。

# 1. Scan a tools/list export (or hand-authored catalog) - client-side, no cloud
mcp-bastion scan examples/fixtures/tools-poisoned.json
mcp-bastion fingerprint tools.json -o baseline.json
mcp-bastion scan tools.json --baseline baseline.json --format json -o report.json
mcp-bastion scan --skills ./skills/

# 1b. Audit local MCP client configs (what agents can already reach)
mcp-bastion audit --root .
mcp-bastion audit --format json -o risk-audit.json --fail-on none

# 2. Test policy effectiveness
mcp-bastion redteam --config bastion.yaml

# 3. Enforce at runtime (filesystem path guards when agents can read local files)
#    merge examples/bastion-filesystem-guards.yaml into bastion.yaml
mcp-bastion validate --config bastion.yaml

_{mcp-bastion scan——客户端静态扫描器；无需云服务，也无需下载 ML}

_{mcp-bastion audit——在执行策略前梳理本地 MCP 表面；无需网络，无需保险库}

_{架构 · 技能 · OSV——默认离线；无需登录服务；不会主动向外发送数据}

_功能介绍

_{仪表板演示}

实时安全态势 + 运行时仪表板——仅限本地运行，零基础设施。mcp-bastion dashboard --demo · 仪表板文档 · 较早的 Vimeo 演示

混合有状态 / 无状态 MCP（3.2.0） - 可选择启用 mcp_transport，为 SEP-2575 做好准备，同时不影响旧版会话。架构 · 教程

为什么选择 MCP-Bastion？（解决 2026 年 MCP 安全危机）

正如 NSA 最近发布的 MCP 安全网络安全信息表和 OWASP MCP Top 10 所指出的，传统 AppSec 工具无法保护 Agent 工作流。问题在于运行时治理和混淆代理问题：多个 AI Agent 共用一个 MCP 服务，却没有原生的身份边界。公共注册表中的拼写抢注和未经验证的服务，已使供应链验证成为董事会层面的关注事项。

MCP-Bastion 充当 Agent 的零信任控制平面，解决最棘手的生产环境问题：

1. 混淆代理问题（Agent IAM）： 身份感知路由将 API 令牌绑定到Agent 身份，并严格执行逐工具 RBAC。客户支持机器人可以调用 search_docs，但不能调用 delete_user。
2. 供应链与拼写抢注防御： 加密 SHA-256 清单验证会在 MCP 服务制品与已签署批准的校验和不一致时阻止流量。
3. 数据外泄与注入防护： PromptGuard 启发式规则与 ML 会在本地拦截越狱攻击；Presidio 会在出站 PII 进入模型上下文窗口之前将其清除。

定义 Agent 策略（bastion.yaml）

# Stop the Confused Deputy Problem  -  Identity-Aware Routing
agent_iam:
  enabled: true
  token_metadata_key: bastion_agent_token
  agents:
    - id: customer_support_bot
      token_env: BASTION_TOKEN_SUPPORT
      allowed_tools: ["search_docs", "get_ticket_status"]
      blocked_tools: ["execute_sql", "delete_user"]
      rate_limit:
        max_iterations: 5

# Supply-chain checksums before any tool executes
server_verification:
  enabled: true
  on_mismatch: block
  base_path: .
  manifest_path: mcp-server.manifest.json

在可信构建后生成清单：mcp-bastion manifest server.py pyproject.toml -o mcp-server.manifest.json

深入了解：docs/RUNTIME_GOVERNANCE.md · docs/ENTERPRISE_RUNTIME_CONTROLS.md（3.0 支柱）

Runtime 治理支柱（3.0.0+，当前版本 5.1.0）

面向生产 MCP 运行时的企业级可选控制。默认全部关闭，因此在启用前，行为与 2.x 保持不变。

支柱	配置	功能
外泄金丝雀	canary_goallock	在上下文中加入会话令牌；阻止回显该令牌的工具参数（-32025）
ATR YAML 规则	atr_rules	将社区威胁规则合并到 content_filter 中（-32027）
本地大模型扫描器	llm_scanner	在启发式检查后添加可选的 Ollama 层；故障时放行（-32026）
威胁情报源	threat_feeds	在后台刷新远程正则表达式模式
自动重置	auto_repave	基于阈值进行遏制（轮换金丝雀、重置范围）
机密信息脱敏	secrets.redact_patterns	对工具输出执行 replace / hash / mask / remove
观察模式	mode: observe	记录 would_block，但不拒绝请求

mode: enforce

canary_goallock:
  enabled: true

atr_rules:
  enabled: true
  rules_dir: ./atr-rules

secrets:
  redact_patterns:
    - rule: "sk-[A-Za-z0-9]{20,}"
      strategy: mask

CLI 合规证据：mcp-bastion report --framework soc2 --audit ./audit.jsonl

完整 MCP 接口面与水平扩展（2.0.0）

此前，大多数支柱仅在 tools/call 上运行。2.0.0 将处理管线扩展到了 resources/read、prompts/get、sampling/createMessage 和 elicitation/create，从而弥补了 MCP 其他接口面上的外泄和注入漏洞。

对于多副本部署，请启用 state_backend.type: redis，使速率限制、重放随机数、成本预算和会话工具范围可在各个 Pod 之间共享（默认值 memory 仅适用于单进程）。

state_backend:
  type: redis
  redis_url: redis://127.0.0.1:6379/0

pip install mcp-bastion-python[redis] · 深入了解：docs/MCP_SURFACE_AND_SCALE.md

2.0.0 中采用的生产环境加固措施

将 MCP 网关生态中经过实战检验的模式接入中间件栈：

功能	效果
JSONPath 参数防护	在执行前，按工具 glob + JSONPath + 正则表达式阻止或脱敏工具参数（可识别 argv 数组规避行为）。pip install mcp-bastion-python[policy]
RBAC fnmatch glob	支持 read_* / files_* 等角色权限，并进行基于特异性的匹配
审计 JSONL + mcp-bastion tail	仅追加的合规日志；在配置中设置 audit.jsonl_path，或运行 mcp-bastion tail -p audit.jsonl
成本检查点	可选择在磁盘上持久化会话总成本，以便在重启后保留（cost_tracker.checkpoint_path，仅限 memory 后端）
成本感知策略（cost_policy）	实时支出规则：降级模型、强制启用发现过滤器、要求审批；阻止高成本调用链
治理证明	mcp-bastion attest export --session … - 带签名的会话包，包含策略哈希和触发的控制措施
边界模式	每个请求都必须进行代理身份验证（boundary_mode + edge_auth / agent_iam） - GATEWAY_BOUNDARY.md
无门控 PromptGuard	prompt_guard.use_ungated_default: true → ProtectAI DeBERTa 分类器（无需 HF 门控）

cost_policy:
  enabled: true
  rules:
    - when: { session_spend_pct_gte: 80 }
      action: degrade_model
      target_model: gpt-4o-mini
    - when: { session_spend_pct_gte: 95 }
      action: require_approval
  expensive_chain:
    enabled: true
    max_projected_cost_usd: 1.0

governance:
  attestation_enabled: true

boundary_mode:
  enabled: true   # requires edge_auth or agent_iam

argument_guards:
  enabled: true
  rules:
    - name: block_shell
      match: "run_*"
      arg: "$.command"
      pattern: "(rm\\s+-rf|curl\\s+.*\\|.*sh)"
      action: block

audit:
  jsonl_path: .bastion/audit.jsonl

cost_tracker:
  checkpoint_path: .bastion/cost-checkpoint.json

### 开发者为何采用它

你需要……	MCP-Bastion 为你提供……
无需重写即可添加防护措施	即插即用的中间件：secure_fastmcp(mcp) 或一个 bastion.yaml
法律团队认可的隐私保护	PromptGuard + Presidio 在你的进程内运行；数据留在你的网络中
阻止失控的 Agent 和预算超支	**默认启用：**每个会话 15 次工具调用、60s 超时、50k 令牌预算。**可选：**单工具上限、按美元计算的会话/每日限额、响应卸载
缩小上下文并降低令牌开销	**选择启用：**发现过滤器（减少 tools/list 中的工具数量）、输出预算 + 会话卸载（对超大工具输出最多可减少约 99%）、词汇相似度缓存 - 实测基准
今天就能交付的方案	PyPI、npm、GHCR 上的 Docker、FastMCP、TypeScript 封装、CI 验证、实时仪表盘
团队可审查的策略	Git 中的 bastion.yaml、热重载、符合 OWASP 的控制措施（文档）

FinOps 与滥用防护（拒绝钱包服务攻击）

Agent 可能会不断调用高成本工具（搜索、大模型调用、付费 API），直到账单飙升。Bastion 会在每次 tools/call 之前，于 MCP 边界强制执行会话级 FinOps：

攻击模式	Bastion 的处理方式	默认状态
无限工具循环	达到每个会话的最大迭代次数后阻止	启用（15 次调用）
滥用长时间运行的会话	会话超时	启用（60s）
令牌 / 上下文预算消耗	每个会话的令牌预算；可选输出卸载	启用（50k 令牌）；卸载需选择启用
反复调用同一工具	单工具调用上限（max_per_tool）	选择启用
付费 API 开销失控	通过成本跟踪器设置美元限额	选择启用
不稳定或恶意工具级联	失败后熔断器打开	示例配置中选择启用
单个会话中的工具泛滥	限制每个会话中不同工具的数量	选择启用

被阻止的调用会返回标准错误（RateLimitExceededError -32002、TokenBudgetExceededError -32003、CostBudgetExceededError -32009），并显示在仪表盘和审计日志中。请参阅 docs/ATTACK_PREVENTION.md。

Token 减少与成本节省

Bastion 不仅会拦截失控的开支，还会减少每轮传递给模型的工具输出和工具目录 Token 数量（不会减少用户 LLM 提示文本本身）：

节省方式	作用	默认状态
发现过滤器	从 tools/list 中隐藏未使用的工具，让 Agent 在上下文中携带更小的工具目录（在 基准测试 中，工具从 20 个减少到 3 个时，目录 Token 数量减少约 85%）	可选启用
输出预算 + 转存	截断过大的工具响应；将其余内容存储在会话中，供 bastion_get_offloaded 使用（对于 50k Token 的转储，最多可减少约 99.7%；已低于预算时为 0%）	可选启用
词法相似度缓存	查询几乎相同时跳过重复的工具调用（基于 Jaccard 词语重叠度——不是基于嵌入的“语义”搜索）	可选启用
Token 预算上限	在会话 Token 消耗超过限额前强制停止	已启用（50k Token）
美元会话/每日限额	通过成本跟踪器设置金额上限	可选启用

没有可信的单一“提示词减少 X%”数据——节省幅度取决于输入。可查看 docs/BENCHMARKS.md，了解可复现的 pytest 基准测试和实时数据。

_{复现：PYTHONPATH=src python -m pytest tests/test_benchmarks_finops_rbac.py -v · 重新生成报告：python scripts/generate_benchmark_report.py}

每轮减少工具输出和目录噪声，意味着更低的 LLM 输入成本——而且无需将提示词发送给第三方优化 API。

简而言之： MCP 一夜之间让每个服务都变成了 Agent 网关。Bastion 是防火墙，让这个网关能够安全地投入生产——只需三行代码或一个配置文件。

OWASP MCP Top 10 + 生产环境攻击

所有 10 项 OWASP MCP Top 10 风险都在 MCP 边界得到缓解（请参阅下方的控制措施）。Bastion 还会拦截 OWASP 未单独列出的 FinOps 和滥用模式。

OWASP MCP Top 10（均已处理）

ID	风险	Bastion 控制措施
MCP01	令牌 / 密钥泄露	PII 脱敏、审计跟踪、出站响应扫描
MCP02	权限提升	RBAC、Agent IAM、速率限制、成本上限、会话工具范围
MCP03	工具投毒	提示词防护、内容过滤器、响应扫描、元数据防护、依据验证防护
MCP04	供应链	熔断器、server_verification 校验和、doctor CLI、mcp-bastion manifest、审计
MCP05	命令注入	提示词防护、内容过滤器、架构验证
MCP06	意图颠覆	速率限制、重放防护、单工具上限、语义防火墙
MCP07	身份验证薄弱	RBAC、边缘身份验证、Agent IAM（每个 Agent 使用独立令牌）
MCP08	审计与遥测	审计日志、仪表板、Prometheus、OTEL、告警
MCP09	影子 MCP 服务	集中式 bastion.yaml 策略、指标、发现过滤器
MCP10	上下文注入	PII 脱敏、响应扫描、输出预算、发现过滤器

FinOps 与滥用攻击（OWASP 未涵盖）

攻击	控制措施
钱包耗尽攻击	迭代上限、令牌预算、成本跟踪器、输出预算
工具失控循环	会话超时、速率限制器、熔断器
针对单个工具的高频调用	max_per_tool 会话上限
API 支出失控	USD 会话 / 日上限
会话工具泛滥	每个会话的不同工具数量上限
重放滥用	重放防护 + nonce

令牌缩减与成本节省

手段	控制措施	基准测试
减少上下文中的工具目录	对 tools/list 使用发现过滤器	目录令牌约减少 ~85%（20→3 个工具） - BENCHMARKS.md
减少每轮对话中的工具输出	输出预算、会话卸载、bastion_get_offloaded	超大输出最多减少约 99.7%；低于预算时减少 0%
减少冗余调用	词法相似度缓存（Jaccard 重叠度）	完全重复时命中；相似度为 0.9 时，改写内容未命中
让支出可预测	令牌预算上限、USD 会话 / 日上限	默认启用会话上限

深入了解映射与集成钩子：docs/SECURITY_OBSERVABILITY.md · docs/ATTACK_PREVENTION.md

用 3 行代码保护你的 MCP 服务（FastMCP）

pip install mcp mcp-bastion-fastmcp

from mcp.server.fastmcp import FastMCP
from mcp_bastion_fastmcp import secure_fastmcp

mcp = FastMCP("My Server")
secure_fastmcp(mcp)  # wires prompt guard, PII redaction, rate limits into tools/call

更倾向于策略即代码？ 将 bastion.yaml.example 复制为 bastion.yaml，然后运行 pip install mcp-bastion-python[policy]：

from mcp_bastion import build_middleware_from_config

middleware = build_middleware_from_config()  # loads bastion.yaml

更多方式（TypeScript、CI 验证、Docker）：docs/QUICK_START.md · docs/README.md · 网站

• 提示词注入防御： 开箱即用的启发式越狱拦截；配置 Hugging Face 访问后可使用 Meta PromptGuard ML。
• PII 脱敏： Presidio 会对出站内容中的 SSN、电子邮件地址和电话号码进行掩码处理。
• 防止钱包耗尽： 令牌桶、迭代上限、令牌预算、成本跟踪。
• 响应扫描： 拦截出站工具 / 资源文本中的越狱模式。
• 输出预算与依据验证防护： 可选的响应截断与路径验证（选择启用）。

工作原理

MCP-Bastion 在进程内运行于你的 MCP 服务中，并在每次 tools/call 到达数据库、API 或 Shell 工具之前进行检查 - 随后在返回时对敏感数据进行脱敏。

flowchart LR
  Agent["AI agent / LLM client"]
  Server["Your MCP server"]
  Bastion["MCP-Bastion<br/>middleware"]
  Tools["Tools & upstream APIs"]

  Agent -->|"JSON-RPC"| Server
  Server --> Bastion
  Bastion -->|"✓ allow / ✗ block"| Tools
  Tools -->|"raw result"| Bastion
  Bastion -->|"PII masked · audited"| Server
  Server --> Agent

三种采用方式

flowchart TB
  Start(["Protect my MCP server"])
  Start --> FastMCP["FastMCP · Python<br/><code>secure_fastmcp(mcp)</code>"]
  Start --> Policy["Policy-as-code<br/><code>build_middleware_from_config()</code>"]
  Start --> TS["TypeScript<br/><code>wrapWithMcpBastion(server)</code>"]
  FastMCP --> Docs["docs/QUICK_START.md · path A"]
  Policy --> Yaml["bastion.yaml + CI validate"]
  TS --> Sidecar["Rate limit in-process · ML via sidecar"]

发布版本： npm、PyPI，以及 GHCR 上预构建的 Docker 镜像——请参阅 DOCKER.md。社区： SUPPORT.md · CONTRIBUTING.md · FUNDING.md · 安全： SECURITY.md。

---

核心功能

零点击提示注入防护

在本地集成 Meta 的 PromptGuard 模型，在恶意载荷、越狱攻击和对抗性分词到达外部工具之前，检测并拦截它们。

PII 脱敏

Microsoft Presidio 会扫描发出的工具结果，并对 PII 进行掩码处理（脱敏、替换、泛化）。

无限循环与费用失控防护

实现有状态的循环检测和可配置的 FinOps 令牌桶算法，自动终止失控的 Agent，防止 API 账单大幅超支。

100% 本地执行（数据隐私）

所有安全分类和数据脱敏均完全在服务的本地内存空间中完成。敏感数据绝不会离开企业网络，交由第三方进行安全评估。

低延迟

即插即用的中间件，额外开销低于 5ms。

框架集成

通过标准中间件接入 MCP SDK（TypeScript、Python）和 FastMCP。无需更改业务逻辑。

完整功能目录

支柱定义： 安全控制、bastion.yaml 部分，以及它们与仪表板健康状态行的对应关系，详见 docs/PILLARS.md（权威参考；避免“支柱总数”含义模糊）。同一页面还列出了在 1.0.16+ 中恢复的扩展功能（语义防火墙、敏感信息分类器、外部策略、边缘认证、工具允许列表、会话范围、工具元数据防护、多租户、审计哈希链、定价钩子、遥测接收器、红队和诊断 CLI 等）、在 1.0.17+ 中新增的 FinOps/上下文支柱（输出预算、发现过滤器、响应扫描、事实依据防护），以及运行时治理（Agent IAM、服务验证——在 1.0.18+ 中引入，并于 2.0.0 发布）。

深入了解： docs/SECURITY_OBSERVABILITY.md——OWASP MCP Top 10 对齐情况、攻击场景，以及 SIEM/日志集成。框架附加组件（LangChain、OpenAI、Bedrock 等）列于下文的框架集成部分。

威胁防护与内容安全

功能	功能说明
提示注入防御	Meta PromptGuard 会为工具参数评分；恶意/越狱类载荷可在执行前被拦截（本地推理，无需第三方 API）。
内容过滤器	拦截 shell/代码执行模式、敏感文件路径和 URL；可选的允许列表/拒绝列表正则表达式或子字符串规则。
PII 脱敏	Microsoft Presidio 可在发出的工具/资源文本中检测多种实体类型（SSN、电子邮件、电话、银行卡、护照、IBAN、驾照等——请参阅 Presidio 文档）。

访问控制、完整性与滥用防护

功能	提供内容
Agent IAM（混淆代理）	将 API 令牌绑定到 Agent 身份；为每个 Agent 设置 allowed_tools / blocked_tools、资源 URI允许/阻止列表，以及可选的速率限制 - 防止支持机器人调用管理员工具或读取机密资源。参见 docs/RUNTIME_GOVERNANCE.md。
完整 MCP 接口防护（2.0.0）	resources/read、prompts/get、sampling/createMessage、elicitation/create - 与工具调用采用相同的入站/出站防护原则（不只是 tools/call）。docs/MCP_SURFACE_AND_SCALE.md
分布式状态（2.0.0）	state_backend: redis - 在多个副本间共享速率限制、重放随机数、成本上限和会话范围。pip install mcp-bastion-python[redis]
行为指纹（3.3.0，可选启用）	behavior_fingerprint.enabled - 检测每个 Agent 的工具基线偏移和速率激增；默认关闭。docs/BEHAVIOR_FINGERPRINT.md
混合 MCP 传输（可选启用）	mcp_transport - 有状态会话和无状态显式状态句柄；每个请求均可指定协议版本；代理发现卡片；Agent 稳定性监控。docs/HYBRID_MCP_TRANSPORT.md
服务验证（供应链）	在启动时及每次 tools/call 时验证 SHA-256 清单校验和；mcp-bastion manifest 可在构建审核通过后生成可信清单。
RBAC	按角色（来自请求元数据）进行工具级允许/拒绝；bastion.yaml 中使用 fnmatch 通配模式（read_*），并按特异性进行匹配。与 Agent IAM 或边缘认证搭配使用 - 单独使用时，角色的可信度取决于设置 metadata["role"] 的机制。实时矩阵 →
参数防护（2.0.0）	在 schema 验证前，针对 tools/call 参数使用 JSONPath + 正则表达式进行阻止/脱敏 - 防止类 argv 载荷中的 Shell 注入和机密数据外泄。
Schema 验证	在工具运行前，根据 JSON Schema 验证 tools/call 参数（阻止格式错误或试图绕过防护的请求）。
重放防护	跟踪 随机数以拒绝重放请求（可配置 require_nonce）。
速率限制	令牌桶式限制：每个会话的最大迭代次数、超时、令牌预算 - 防止循环失控和暴力破解行为。
熔断器	停止调用反复失败的工具（限制故障上游或被投毒工具的影响范围）。

FinOps 与性能

功能	提供内容
成本跟踪器	设置每个会话及可选的每日美元上限；超出预算时阻止请求。可选的磁盘检查点可在重启后保留累计值（内存后端）。
语义缓存（词法）	可选的 Jaccard 词语重叠度缓存，用于缓存近似相同的工具查询 - 并非基于嵌入；参见 基准测试。
低开销	在热路径上运行的中间件，目标是典型开销 <5 ms（参见 docs/METRICS.md）。

审计、指标与告警

功能	你将获得什么
审计日志	结构化记录 允许/拒绝 决策，包含 reason、tool、tenant_id、trace_id、request_id，可供 SOC / 合规使用。可选 JSONL 文件接收器 + mcp-bastion tail。
告警接收器	Slack 传入 Webhook；通用 HTTP Webhook（PagerDuty、Teams、自定义 API）；多个 URL；在 bastion.yaml 中配置 重试、退避、超时。
内存指标	全局 MetricsStore：请求、拦截、PII 计数、成本、按工具统计、延迟样本、滚动 时间序列存储桶。
实时仪表板	本地 Web UI（新增面板）：部署前安全态势评级 + 来自 .bastion/scan/ 的 Sonar 风格预验证、PMD 风格问题指南（原因 / 修复方法 / OWASP）、OWASP ASI + MCP + LLM 热力图、实时攻击矩阵、合规证据 + 带日期的报告、日期筛选器、观察模式横幅、Agent / 趋势 / 入门引导、包含原因/支柱/追踪信息的取证分析、FinOps 成本消耗（实际值与未拦截时的预估值、节省的 Token + 拦截避免的成本、图表），以及经典 KPI。API： /api/metrics、/api/posture、/api/prevalidate、/api/issue-guide、/api/taxonomy、/api/attack-matrix、/api/compliance。支持深色/浅色主题。参见 dashboard/README.md。
OpenTelemetry	可选 OTLP Span 导出 - pip install mcp-bastion-python[otel] - docs/OTEL.md。

策略、打包与开发者体验

功能	你将获得什么
策略即代码	单一的 bastion.yaml：为所有请求路径控制项以及审计、告警和热重载提供开关（docs/PILLARS.md）；通过 load_config / build_middleware_from_config 加载。
热重载	可选 在 bastion.yaml 变更时重新加载，无需重启 MCP 服务（docs/POLICY_AS_CODE.md）。
可组合中间件	compose_middleware 排序；MCPBastionMiddleware 为每个支柱提供开关。
CLI	mcp-bastion scan、audit、validate、redteam、manifest、attest export、serve、dashboard、doctor、tail - docs/CLI.md。
Python + 多语言支持	PyPI 上的 mcp-bastion-python（引擎）。对于 TypeScript / Java / Go / .NET / Kotlin / Rust 适配器及共享的 bastion.yaml，请使用 mcp-bastion-suite — 参见 docs/MULTI_LANGUAGE_SUITE.md。可选的仓库内 TypeScript 包：@mcp-bastion/core。
容器	Dockerfile、docker-compose 配置文件（代理 + 可选仪表板）- DOCKER.md。预构建镜像（GHCR）： mcp-bastion-proxy、mcp-bastion-dashboard - 每个 v* 标签发布一次（publish-docker.yml）。

实时仪表板和警报

仪表板是可选且本地运行的——只读查看运行时指标 + 本地扫描/审计产物。无需登录服务器，也无需云数据库（请参阅 docs/ZERO_INFRA_STRATEGY.md）。

**功能演示（GIF）：**安全态势 + 修复方法 → OWASP → 攻击矩阵 → 合规性 → RBAC/治理 → 取证 → Agent → 安全态势漂移 → 令牌和成本节省 → 流量。

_功能演示

_{仪表板操作演示}

_{重新生成截图：mcp-bastion dashboard --demo，然后运行 python scripts/capture_dashboard_demo.py · 种子数据：--demo}

#### 仪表板上的内容

区域	面板 / 操作
部署前态势	目录扫描、技能扫描、OSV、风险审计的 A–F 等级 + 综合等级（读取 .bastion/scan/*.json）
静态预验证	基于同一份本地 JSON 的 Sonar 风格问题列表——并非 SonarQube 服务（/api/prevalidate）
问题指南	每项发现均提供 PMD 风格的原因 / 修复方法 / Bastion 配置项 / OWASP 参考（/api/issue-guide）
OWASP 覆盖情况	ASI Top 10、MCP Top 10、LLM Top 10 标签页——绿色 / 琥珀色 / 灰色热力图，显示发现项 + 拦截压力
实时攻击矩阵	受攻击压力影响的类别，包含强度、占比、热门工具、OWASP 标签、样例 / 追踪详情
合规 / 报告	证明文件 + 策略哈希；生成 SOC2 / GDPR / ISO27001 / NIST AI RMF / ASI 证据或压缩包（按日期筛选）
运行时	KPI、治理、警报 + SSE、洞察、取证（原因 + 详情）、Agent / 趋势 / 入门引导、流量 / 延迟 / PII 图表
FinOps	实际支出 / 令牌用量与原本可能产生的支出 / 令牌用量对比；FinOps 节省的令牌；拦截所避免的令牌 / 美元支出；图表 + 已拦截问题表格
筛选器	日期范围 + 预设（取证、趋势、攻击矩阵、报告）

mcp-bastion dashboard --port 7000 --demo
# or: PYTHONPATH=src python dashboard/app.py

URL	返回内容
http://localhost:7000/	完整 UI（态势、预验证、OWASP、攻击矩阵、FinOps、取证，……）
http://localhost:7000/api/metrics	运行时 JSON（cost_reduction：已使用 / 已节省 / 已避免的支出 + 原本可能产生的支出）
http://localhost:7000/api/posture	本地 JSON 中的扫描 / 技能 / OSV / 风险审计等级
http://localhost:7000/api/prevalidate	Sonar 风格的问题列表 + 等级（本地扫描套件）
http://localhost:7000/api/issue-guide?check=weak_schema	PMD 风格规则卡片（或 ?id=ASI02）
http://localhost:7000/api/taxonomy	?framework=asi|mcp|llm 热力图
http://localhost:7000/api/attack-matrix	实时攻击类别（+ 日期筛选）
http://localhost:7000/api/compliance/report	证据 Markdown（framework、date_from、date_to）
http://localhost:7000/api/health	构建信息 / ui_revision
http://localhost:7000/metrics	Prometheus 文本

_{供 Grafana、Datadog 或自定义轮询器使用的 /api/metrics JSON}

将扫描 / 审计产物提供给态势面板：

mkdir -p .bastion/scan
mcp-bastion scan tools.json --format json -o .bastion/scan/catalog.json
mcp-bastion scan --skills ./skills --format json -o .bastion/scan/skills.json
mcp-bastion osv-scan --format json -o .bastion/scan/osv.json
mcp-bastion audit --format json -o .bastion/scan/risk-audit.json

• 警报： Slack webhook 和成本阈值警报。完整 UI 参考：dashboard/README.md。

文档：用例、攻击、指标、教程

采用路径（从头到尾）：

目标	按顺序阅读
端到端手册	docs/USER_GUIDE.md → 已发布的文档
文档手册（GIF + 仪表板）	docs/DOCUMENTATION_HANDBOOK.md → 在线手册
功能深入介绍 + 攻击演示	docs/FEATURE_DEEP_DIVE.md → docs/ATTACK_DEMOS.md
Java / TypeScript / Go / .NET / Kotlin / Rust	docs/MULTI_LANGUAGE_SUITE.md → mcp-bastion-suite
策略即代码（bastion.yaml）	docs/PILLARS.md → docs/POLICY_AS_CODE.md → bastion.yaml.example → docs/CLI.md（validate）
大模型客户端（OpenAI、Claude、Gemini，……）	docs/LLM_INTEGRATION.md → docs/INTEGRATION_MODELS.md → examples/（llm_*.py）
FastMCP / TypeScript / 第三方 MCP	docs/TUTORIALS.md → docs/DETAILED_TUTORIAL.md
批量部署 bastion.yaml + SIEM / SOC 审计	docs/SECURITY_OBSERVABILITY.md → docs/POLICY_AS_CODE.md
最简“hello world” + CI / 注册表	docs/QUICK_START.md → examples/ci/README.md → docs/DISCOVERY.md

完整索引：docs/README.md · 手册网站：文档指南 · 快速入门：docs/QUICK_START.md · 发现：docs/DISCOVERY.md · 贡献：CONTRIBUTING.md。

文档	描述
docs/USER_GUIDE.md	端到端用户指南（概念 → 安装 → 代理 → 保险库 → 运维）；发布于 /guide/
docs/DOCUMENTATION_HANDBOOK.md	系统手册：攻击 GIF、仪表板导览、功能地图、多语言
docs/FEATURE_DEEP_DIVE.md	逐项深入介绍功能：问题、Bastion 如何解决、优势（包括仪表板）
docs/ATTACK_DEMOS.md	可运行的攻击 → 防御演示（避免在此 README 中加入冗长的演练内容）
docs/MULTI_LANGUAGE_SUITE.md	通过 mcp-bastion-suite 提供的多语言连接器
docs/index.md	Markdown 文档主页（源文档中心）
docs/POLICY_AS_CODE.md	bastion.yaml 参考：键、示例、热重载、警报
docs/LLM_INTEGRATION.md	大模型集成：OpenAI、Claude、Gemini、Mistral、Grok（stdio + HTTP 配置）
docs/DETAILED_TUTORIAL.md	面向新团队的分步实施教程
docs/USE_CASES.md	实际用例：企业网关、大模型产品、内部工具、SaaS、合规
docs/ATTACK_PREVENTION.md	展示 MCP-Bastion 如何防止真实攻击的示例（注入、PII 泄露、速率耗尽、路径遍历、RBAC、重放）
docs/PILLARS.md	权威支柱数量：18 项请求路径功能（10 项核心 + 8 项扩展）、14 行仪表板 pillar_health、20+ 个 bastion.yaml 顶级区域——范围详见文档
docs/SUPPLY_CHAIN.md	CI 合并门禁、发布、npm 来源证明、PyPI Trusted Publishing、CycloneDX SBOM
docs/CRA_COMPLIANCE.md	CRA / OpenSSF 维护者立场（第 14 条 + SBOM；不更改运行时）
docs/CRA_SBOM_TUTORIAL.md	生成并下载 CycloneDX bom.json
docs/PII_VAULT.md	可选启用、可逆的 PII 令牌化（抽象化 + 还原）
docs/INTEGRATION_MODELS.md	中间件 + bastion.yaml 与“更改基础 URL”；适用于 Python、TS、Desktop、HTTP 和集成的桥接方案
examples/ci/README.md	可复制粘贴的 GitHub Actions 代码段，用于对策略文件运行 mcp-bastion validate
docs/BENCHMARKS.md	实测数据 RBAC 矩阵、输出预算缩减（大型工具输出最多约 99%）、发现过滤器、词法缓存——pytest + 报告生成器
docs/REDTEAM.md	解读测试框架 / 红队评分；应启用哪些 bastion.yaml 支柱；Node 与 Python 的范围（packages/core/README.md）
docs/SECURITY_OBSERVABILITY.md	OWASP MCP Top 10、集成钩子、大规模部署 bastion.yaml、SIEM / SOC 审计模式
docs/METRICS.md	性能开销（<5ms）和有效性指标（仪表板、Prometheus、OTEL）
docs/TUTORIALS.md	教程：与 FastMCP、TypeScript、GitHub MCP 和开源 MCP 服务集成
docs/CYBER_EXTENSIONS_CORE.md	TypeScript 扩展 A/E/F（语义出口、结果来源证明、审计）
docs/GITHUB_PAGES.md	从同一仓库将文档发布为 GitHub Pages 网站
docs/QUICK_START.md	精简的 FastMCP / bastion.yaml / CI 代码段（快速实现价值）
docs/DISCOVERY.md	注册表和生态系统发现清单
docs/ENTERPRISE_RUNTIME_CONTROLS.md	**3.0 运行时治理：**金丝雀、ATR 规则、大模型扫描器、威胁情报源、自动重建、密钥脱敏、观察模式
docs/ROADMAP.md	产品路线图：成本感知治理、安全深度、可发现性
docs/COMPARISON.md	与无防护的 MCP、轻量代理、完整 AI/MCP 网关的对比
docs/ENGINEERING_10_10.md	在注入防护深度、工具投毒、网关成熟度、FinOps 指标和项目成熟度方面达到 10/10 的战略路径
CONTRIBUTING.md	贡献者指南和 good first issue 想法

一行 Docker

预构建镜像（首次运行 publish-docker 后，通常在 v* 发布标签上）：

docker pull ghcr.io/vaquarkhan/mcp-bastion-proxy:latest
docker run -p 8080:8080 ghcr.io/vaquarkhan/mcp-bastion-proxy:latest
# Dashboard (optional, port 7000):
# docker pull ghcr.io/vaquarkhan/mcp-bastion-dashboard:latest
# docker run -p 7000:7000 ghcr.io/vaquarkhan/mcp-bastion-dashboard:latest
# Pin a release: ghcr.io/vaquarkhan/mcp-bastion-proxy:vX.Y.Z (published on each v* tag)

本地构建（任意修订版本）：

docker build -t mcp-bastion/proxy .
docker run -p 8080:8080 mcp-bastion/proxy

MCP 端点：http://localhost:8080/mcp。使用 docker-compose up -d 启动代理；添加 --profile with-dashboard 可启用仪表板。参阅 DOCKER.md（其中包含 GHCR 拉取命令，以及分叉仓库的 package 链接：在镜像路径中将 vaquarkhan 替换为你的组织或用户名）。

策略即代码（bastion.yaml）

单个配置文件控制策略（支柱定义请参阅 docs/PILLARS.md）。将 bastion.yaml.example 复制为 bastion.yaml，然后：

from mcp_bastion import build_middleware_from_config
middleware = build_middleware_from_config()

参阅 docs/POLICY_AS_CODE.md。

提示：使用 build_middleware_from_config() 时，在 bastion.yaml 中设置 hot_reload.enabled: true，即可应用策略变更，而无需重启 MCP 服务。

面向开发者的 CLI

mcp-bastion audit                 # local MCP client-config risk report
mcp-bastion scan tools.json       # static tool-definition scan
mcp-bastion validate              # validate bastion.yaml
mcp-bastion serve --http 8080     # run MCP server with config
mcp-bastion dashboard --port 7000 # run metrics dashboard

参阅 docs/CLI.md。

持续集成（本仓库）

每次拉取请求和推送到 main 时，.github/workflows/ci.yml 都会运行：

1. pip install -e ".[dev,policy,dashboard]" - 安装 Python 包，以及测试、YAML 策略加载和用于仪表板测试的 FastAPI。
2. mcp-bastion validate --config bastion.yaml.example - 确保示例策略文件可以加载。
3. python -m pytest --cov=mcp_bastion --cov-fail-under=92 - 运行完整的 Python 测试套件，并确保 src/mcp_bastion 的行覆盖率**≥92%**（测量路径和阈值请参阅 pyproject.toml 中的 [tool.coverage.*]）。
4. npm ci 和 npm test - 运行 TypeScript 工作区测试。

如需在 CI 中验证你自己的仓库的 bastion.yaml，而不克隆 MCP-Bastion，请参阅 examples/ci/README.md。

OpenTelemetry

设置 OTEL_EXPORTER_OTLP_ENDPOINT，即可将工具调用跨度导出到 OTLP。安装可选依赖项：pip install mcp-bastion-python[otel]。参阅 docs/OTEL.md。

Webhook 告警与外部日志记录

可使用 Slack（slack_webhook / SLACK_WEBHOOK_URL）、通用 HTTP webhook（webhook_url / BASTION_WEBHOOK_URL）或多个 URL（bastion.yaml 中的 alerts.webhooks）。POST 请求可用于驱动 PagerDuty、Microsoft Teams、Datadog Events，或 SIEM 提供的任意 HTTP 收集器。在 bastion.yaml 中配置重试/退避（retry_attempts、retry_backoff_seconds、retry_backoff_max_seconds、timeout_seconds）。

**指标与追踪：**抓取仪表板的 /metrics（Prometheus）或轮询 /api/metrics（JSON），以供 Grafana、Datadog 或自定义轮询器使用。设置 OTEL_EXPORTER_OTLP_ENDPOINT，即可将追踪数据发送到 Jaeger、Honeycomb、AWS ADOT 等（pip install mcp-bastion-python[otel]）。通过 Fluent Bit、Vector 或 CloudWatch agent 路由 Python 日志（包括 LoggingAlertSink），并将其发送到 Splunk / Elastic / CloudWatch Logs。

完整的集成表格和与 OWASP MCP Top 10 的对应关系，请参阅 docs/SECURITY_OBSERVABILITY.md。

---

## 为什么选择 MCP-Bastion

• 主动强制执行 - 拦截 MCP 工具流量，确保策略（提示词注入检查、PII 处理、内容规则、RBAC 等）在工具执行前运行，并在敏感结果传播前生效。
• 优先本地分类 - PromptGuard 和 Presidio 在你的环境中运行；你无需将提示词发送到第三方 API 进行护栏评分。
• 有状态护栏 - 通过会话级速率限制、迭代上限、令牌预算和成本跟踪，减少循环失控和意外开支。
• 可组合集成 - 使用 bastion.yaml 配合 build_middleware_from_config()，或在 Python 或 TypeScript 中接入 MCPBastionMiddleware / wrapWithMcpBastion。若要在独立进程中置于上游 MCP 服务前，请使用你控制的包装器或代理；参见 docs/INTEGRATION_MODELS.md。

---

结构

路径	说明
src/mcp_bastion/	Python 包：PromptGuard、Presidio、速率限制、RBAC 等。
packages/core/	TypeScript 包：进程内实现速率限制 + 来源追溯 + 审计；提示词/PII/语义/结果通过边车（MCP_BASTION_URL）实现
examples/	Python 示例（examples/README.md）
dashboard/	实时仪表板 UI 和指标 API（dashboard/README.md）
bastion.yaml.example	策略即代码示例；复制为 bastion.yaml（docs/POLICY_AS_CODE.md）
scripts/validate_checklist.py	企业级验证运行器
VALIDATION_CHECKLIST.md	验证指南和 MCP Inspector 步骤
SETUP_GUIDE.md	设置、配置和验证
DOCKER.md	Docker 单行运行和 compose

示例文件

文件	用途
examples/python_server_example.py	最简中间件链
examples/full_demo.py	多支柱堆栈（核心开关：速率限制、PII、RBAC、… - 参见 docs/PILLARS.md）
examples/llm_server.py	面向大模型客户端的共享 MCP 服务
examples/llm_openai_example.py	OpenAI
examples/llm_claude_example.py	Claude
examples/llm_gemini_example.py	Gemini
examples/llm_mistral_example.py	Mistral
examples/llm_grok_example.py	Grok (xAI)
examples/server_with_config.py	策略即代码（bastion.yaml）

安装

Python

uv add mcp-bastion-python
# or
pip install mcp-bastion-python
# pin a specific release (optional)
pip install mcp-bastion-python==5.1.0

先决条件（推荐）

• PII 脱敏： Presidio 需要 spaCy 英语模型。安装后运行：
  python -m spacy download en_core_web_sm
  若缺少该模型，PII 分析可能在运行时失败。
• 策略即代码（bastion.yaml）： 安装 YAML 支持：
  pip install mcp-bastion-python[policy]
  （会添加 pyyaml；否则加载策略文件时可能会出现 ImportError。）
• 提示词注入（PromptGuard）： 分为两层：
  1. 正则启发式规则（始终启用）会拦截明显的越狱字符串，例如 “ignore previous instructions” - 无需下载模型。
  2. ML 分类器（默认无需授权）： 通过 use_ungated_default: true 使用 ProtectAI/deberta-v3-base-prompt-injection-v2（无需登录 Hugging Face）。可选的受限访问升级：设置 use_ungated_default: false，并在运行 huggingface-cli login 后使用 meta-llama/Llama-Prompt-Guard-2-86M。当 fail_open: false（默认值）时，未经验证的载荷会被拦截。运行 mcp-bastion doctor 以验证 ML 是否可用。

PyPI wheel 包含完整的 mcp_bastion 目录树（包括 config、cli、otel、仪表板指标和告警接收器）。如果你使用的旧版 wheel 缺少模块，请升级到当前版本。

TypeScript

npm install @mcp-bastion/core

npm

框架集成

为你喜欢的大模型框架提供即插即用的安全防护。每个包都会自动安装 mcp-bastion-python。版本和下载量列使用 ecosystem-downloads.json 中的实时徽章（通过 PePy 统计累计总量）。趋势： pypistats.org。 One-place totals: Integrations download dashboard · ecosystem-downloads.json (sum of all 26 packages, refreshed daily).

Package	Protects	Version	Downloads
mcp-bastion-python	Core middleware		· pypistats
mcp-bastion-langchain	LangChain		· pypistats
mcp-bastion-openai	OpenAI GPT		· pypistats
mcp-bastion-anthropic	Anthropic Claude		· pypistats
mcp-bastion-bedrock	AWS Bedrock		· pypistats
mcp-bastion-gemini	Google Gemini		· pypistats
mcp-bastion-crewai	CrewAI		· pypistats
mcp-bastion-llamaindex	LlamaIndex		· pypistats
mcp-bastion-groq	Groq		· pypistats
mcp-bastion-mistral	Mistral AI		· pypistats
mcp-bastion-cohere	Cohere		· pypistats
mcp-bastion-azure	Azure OpenAI		· pypistats
mcp-bastion-vertexai	Vertex AI		· pypistats
mcp-bastion-huggingface	Hugging Face		· pypistats
mcp-bastion-deepseek	DeepSeek AI		· pypistats
mcp-bastion-together	Together AI		· pypistats
mcp-bastion-fireworks	Fireworks AI		· pypistats
mcp-bastion-litellm	LiteLLM (100+ providers)		· pypistats
mcp-bastion-ollama	Ollama local models		· pypistats
mcp-bastion-openrouter	OpenRouter gateway		· pypistats
mcp-bastion-xai	xAI Grok		· pypistats
mcp-bastion-autogen	Microsoft AutoGen		· pypistats
mcp-bastion-langgraph	LangGraph		· pypistats
mcp-bastion-pydantic-ai	Pydantic AI		· pypistats
mcp-bastion-openai-agents	OpenAI Agents SDK		· pypistats
mcp-bastion-fastmcp	FastMCP servers		· pypistats

pip install mcp-bastion-langchain      # LangChain agents and tools
pip install mcp-bastion-openai         # OpenAI GPT API calls
pip install mcp-bastion-anthropic      # Anthropic Claude API calls
pip install mcp-bastion-bedrock        # AWS Bedrock runtime
pip install mcp-bastion-gemini         # Google Gemini
pip install mcp-bastion-crewai         # CrewAI agent crews
pip install mcp-bastion-llamaindex     # LlamaIndex RAG pipelines
pip install mcp-bastion-groq           # Groq inference
pip install mcp-bastion-mistral        # Mistral AI
pip install mcp-bastion-cohere         # Cohere
pip install mcp-bastion-azure          # Azure OpenAI Service
pip install mcp-bastion-vertexai       # Google Cloud Vertex AI
pip install mcp-bastion-huggingface    # Hugging Face Inference
pip install mcp-bastion-deepseek       # DeepSeek AI
pip install mcp-bastion-together       # Together AI
pip install mcp-bastion-fireworks      # Fireworks AI
pip install mcp-bastion-litellm        # LiteLLM (100+ providers)
pip install mcp-bastion-ollama         # Ollama local models
pip install mcp-bastion-openrouter     # OpenRouter gateway
pip install mcp-bastion-xai            # xAI Grok
pip install mcp-bastion-autogen        # Microsoft AutoGen
pip install mcp-bastion-langgraph      # LangGraph
pip install mcp-bastion-pydantic-ai    # Pydantic AI
pip install mcp-bastion-openai-agents  # OpenAI Agents SDK
pip install mcp-bastion-fastmcp        # FastMCP servers

逐个发布：请参阅 integrations/PUBLISH.md。

发布（PyPI / npm）

• PyPI： python -m build && twine upload dist/*（或在 tag 上使用 GitHub Actions）。
• npm： 在仓库根目录运行 cd packages/core && npm publish --access public（或使用 Trusted Publishers）。
• 版本号分别设置在 pyproject.toml（Python）、packages/core/package.json（npm）和 server.json（MCP 注册表）中。发布前请升级版本号。

开发者指南

Python 和 TypeScript 集成示例。完整的贡献者文档和功能文档：

文档	说明
docs/DEVELOPER_GUIDE.md	仓库结构、本地开发、测试、发布
docs/FEATURES.md	所有安全支柱的使用方法，包括 3.0 运行时治理
docs/RBAC.md	RBAC 角色、fnmatch 通配模式、Agent IAM 配对
CONTRIBUTING.md	PR 检查清单和适合新手的问题
SUPPORT.md · FUNDING.md	帮助与赞助

---

快速开始（Python）

分三步将 MCP-Bastion 添加到现有 MCP 服务：

from mcp_bastion import MCPBastionMiddleware, compose_middleware

# 1. Create the security middleware
bastion = MCPBastionMiddleware(
    enable_prompt_guard=True,
    enable_pii_redaction=True,
    enable_rate_limit=True,
)

# 2. Compose with your middleware chain (Bastion runs first)
middleware = compose_middleware(bastion)

# 3. Pass the composed middleware to your MCP server
# (integration depends on your server framework)

示例：

示例	说明
examples/python_server_example.py	基础中间件链
examples/full_demo.py	完整中间件栈：添加、PII、速率限制、提示词注入等。
examples/llm_openai_example.py	用于 OpenAI 的 MCP 服务
examples/llm_claude_example.py	用于 Claude 的 MCP 服务
examples/llm_gemini_example.py	用于 Gemini 的 MCP 服务
examples/llm_mistral_example.py	用于 Mistral 的 MCP 服务
examples/llm_grok_example.py	用于 Grok 的 MCP 服务（xAI，仅限 HTTP）

# Windows: $env:PYTHONPATH="src"; python examples/full_demo.py
# Linux/Mac: PYTHONPATH=src python examples/full_demo.py

大模型集成： 请参阅 docs/LLM_INTEGRATION.md，获取适用于 OpenAI、Claude、Gemini、Mistral 和 Grok 的可直接复制粘贴的配置。

企业验证：

PYTHONPATH=src python scripts/validate_checklist.py

请参阅 VALIDATION_CHECKLIST.md 和 SETUP_GUIDE.md。

---

Python 教程：FastMCP 服务

通过 secure_fastmcp 将 MCP-Bastion 集成到 FastMCP 服务中（会修补工具分发机制——请参阅 integrations/mcp-bastion-fastmcp/README.md）。

步骤 1：安装依赖项

pip install mcp mcp-bastion-fastmcp

步骤 2：创建服务文件（server.py）

from mcp.server.fastmcp import FastMCP
from mcp_bastion_fastmcp import secure_fastmcp

mcp = FastMCP("My Secure Server")
secure_fastmcp(mcp)  # call right after FastMCP(), before mcp.run()

@mcp.tool()
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city}: 22C, sunny"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

步骤 3：运行服务

python server.py

MCP-Bastion（通过 secure_fastmcp）：

• 在执行前扫描工具参数中的提示词注入
• 在返回工具结果时对其中的 PII 进行脱敏
• 强制执行默认速率限制（每个会话 15 次调用，超时 60s——请参阅 TokenBucketRateLimiter）

如需使用完整的 bastion.yaml 策略，或对资源（resources/read）进行 PII 脱敏，请使用底层 MCP Server 和 build_middleware_from_config()——请参阅 docs/QUICK_START.md 中的路径 B。

替代方案：策略即代码

使用 bastion.yaml，而非代码。将 bastion.yaml.example 复制为 bastion.yaml，然后：

from mcp_bastion import build_middleware_from_config
middleware = build_middleware_from_config()

请参阅 docs/POLICY_AS_CODE.md 和 examples/server_with_config.py。

---

Python：自定义速率限制

自定义配置示例：

from mcp_bastion import MCPBastionMiddleware
from mcp_bastion.pillars.rate_limit import TokenBucketRateLimiter
from mcp_bastion.pillars.prompt_guard import PromptGuardEngine

# Stricter limits
rate_limiter = TokenBucketRateLimiter(
    max_iterations=10,
    timeout_seconds=30,
    token_budget=25_000,
)

# Higher threshold = fewer blocks, more risk
prompt_guard = PromptGuardEngine(threshold=0.92)

bastion = MCPBastionMiddleware(
    prompt_guard=prompt_guard,
    rate_limiter=rate_limiter,
    enable_prompt_guard=True,
    enable_pii_redaction=True,
    enable_rate_limit=True,
)

# Disable PII redaction if your data has no PII
bastion_no_pii = MCPBastionMiddleware(enable_pii_redaction=False)

---

Python：自定义中间件

扩展 Middleware 以添加日志记录、指标或自定义逻辑：

from mcp_bastion import MCPBastionMiddleware
from mcp_bastion.base import Middleware, MiddlewareContext, compose_middleware

class LoggingMiddleware(Middleware):
    async def on_message(self, context, call_next):
        result = await call_next(context)
        # log method, elapsed, etc.
        return result

bastion = MCPBastionMiddleware()  # or use the configured instance from above
middleware = compose_middleware(bastion, LoggingMiddleware())

完整示例请参阅 examples/full_demo.py。

---

TypeScript：包装 MCP 服务

步骤 1：安装依赖项

npm install @modelcontextprotocol/sdk @mcp-bastion/core

步骤 2：创建服务（server.ts）

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  wrapWithMcpBastion,
} from "@mcp-bastion/core";

const server = new Server({ name: "my-mcp-server", version: "1.0.0" });

// Wrap the server with MCP-Bastion (rate limiting only by default)
// For prompt injection, PII, semantic egress, and result guard, run the Python sidecar
wrapWithMcpBastion(server, {
  enableRateLimit: true,
  maxIterations: 15,
  timeoutMs: 60_000,
  // Optional: enable ML / semantic features via Python sidecar
  sidecarUrl: process.env.MCP_BASTION_SIDECAR || "",
  enablePromptGuard: !!process.env.MCP_BASTION_SIDECAR,
  enablePiiRedaction: !!process.env.MCP_BASTION_SIDECAR,
  // Opt-in cyber extensions — see docs/CYBER_EXTENSIONS_CORE.md
  enableSemanticEgress: true,
  semanticEgressMode: "detect",
  semanticEgressTools: ["create_pull_request", "send_email"],
  tagResultProvenance: true,
  enableAudit: true,
});

// Register tools (handlers are automatically wrapped)
server.setRequestHandler("tools/call" as any, async (request) => {
  if (request.params?.name === "get_weather") {
    return {
      content: [{ type: "text", text: "Sunny, 22C" }],
      isError: false,
    };
  }
  throw new Error("Unknown tool");
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main();

步骤 3：仅启用速率限制运行

npx tsx server.ts

步骤 4：启用完整机器学习功能运行（Python sidecar）

如需提示词注入防护、PII 脱敏、语义出站检查和结果防护，请运行一个提供 /prompt-guard、/pii-redact、/semantic-egress 和 /result-guard 的 Python HTTP 服务（请参阅 docs/CYBER_EXTENSIONS_CORE.md）。然后：

# Start the Python sidecar, then the TypeScript server (sidecarUrl or MCP_BASTION_URL)
MCP_BASTION_SIDECAR=http://localhost:8000 npx tsx server.ts

**中介前提条件：**包装器只能处理经 MCP 中介的工具调用。带外 shell/git 操作不在范围内。

---

TypeScript：包装单个处理程序

仅包装指定的处理程序：

import {
  wrapCallToolHandler,
  wrapReadResourceHandler,
} from "@mcp-bastion/core";
import {
  CallToolRequestSchema,
  ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

// Wrap only the tool handler
const safeToolHandler = wrapCallToolHandler(
  async (request) => {
    // Your tool logic
    return { content: [{ type: "text", text: "OK" }], isError: false };
  },
  { enableRateLimit: true, maxIterations: 10 }
);

// Wrap only the resource handler (for PII redaction)
const safeResourceHandler = wrapReadResourceHandler(
  async (request) => {
    const contents = await fetchResource(request.params.uri);
    return { contents };
  },
  { sidecarUrl: "http://localhost:8000", enablePiiRedaction: true }
);

server.setRequestHandler(CallToolRequestSchema, safeToolHandler);
server.setRequestHandler(ReadResourceRequestSchema, safeResourceHandler);

---

配置参考

选项	Python	TypeScript	默认值	描述
enable_prompt_guard	是	是	True（Python）/ False（TS）	通过 PromptGuard 拦截恶意提示词
enable_pii_redaction	是	是	True（Python）/ False（TS）	遮蔽外发内容中的 PII
enable_rate_limit	是	是	True	限制迭代次数和超时时间
max_iterations	通过 TokenBucketRateLimiter	是	15	每个会话的最大工具调用次数
timeout_seconds / timeoutMs	通过 TokenBucketRateLimiter	是	60	会话超时时间
token_budget	通过 TokenBucketRateLimiter	-	50,000	每个请求的 FinOps 令牌上限
sidecarUrl	-	是	""	用于 ML / 语义功能的 Python sidecar URL
enableSemanticEgress	-	是	false	通过 /semantic-egress 检查允许列表中的出站工具
semanticEgressMode	-	是	detect	detect | quarantine（失败时默认拒绝）
semanticEgressTools	-	是	[]	要检查的工具名称
tagResultProvenance	-	是	false	将结果文本包装在不可信标记中
enableResultGuard	-	是	false	通过 /result-guard 扫描结果
resultGuardMode	-	是	detect	detect | strict（失败时默认拒绝）
enableAudit / onAudit	-	是	false	哈希链式审计 + 可选接收端
threshold	通过 PromptGuardEngine	-	0.85	恶意概率阈值
setLogLevel	-	是	"info"	TypeScript："debug" | "info" | "warn" | "error"

---

错误处理

当 MCP-Bastion 拦截请求时，会返回标准 MCP/JSON-RPC 错误：

代码	异常	触发条件
-32001	PromptInjectionError	工具参数包含越狱/注入内容
-32002	RateLimitExceededError	会话超出迭代次数或超时时间限制
-32003	TokenBudgetExceededError	会话超出令牌预算
-32004	CircuitBreakerOpenError	工具的熔断器在发生故障后处于开启状态
-32005	ContentFilterError	内容过滤器匹配到被拦截的模式
-32006	RBACError	调用方无权使用此工具
-32007	SchemaValidationError	工具参数未通过架构验证
-32008	ReplayAttackError	检测到重复 nonce / 重放攻击
-32009	CostBudgetExceededError	会话超出成本预算
-32010	SemanticFirewallError	工具序列 / 参数模式未通过语义防火墙检查
-32011	ExternalPolicyDeniedError	OPA/Cedar（或其他外部）策略拒绝了请求
-32012	SensitiveContentError	敏感业务分类器的分数高于阈值
-32013	AuthenticationError	边缘 / 网关身份验证（元数据令牌）失败
-32014	ToolNotAllowedError	工具不在允许列表中
-32015	SessionScopeExceededError	每个会话中的不同工具过多（范围扩张）
-32016	ToolMetadataPoisoningError	工具列表 / 元数据未通过安全检查
-32017	GroundingViolationError	工具输出中包含缺乏依据的文件引用
-32018	PromptGuardUnavailableError	PromptGuard ML 不可用且采用失败时默认拒绝策略（或启发式检查已禁用）
-32019	AgentAccessDeniedError	已通过身份验证的 Agent 尝试使用其 IAM 策略之外的工具
-32020	ServerVerificationError	MCP 服务文件校验和与受信任清单不匹配

# Python: exceptions
from mcp_bastion.errors import (
    PromptInjectionError,
    RateLimitExceededError,
    TokenBudgetExceededError,
    CircuitBreakerOpenError,
    ContentFilterError,
    RBACError,
    SchemaValidationError,
    ReplayAttackError,
    CostBudgetExceededError,
    SemanticFirewallError,
    ExternalPolicyDeniedError,
    SensitiveContentError,
    AuthenticationError,
    ToolNotAllowedError,
    SessionScopeExceededError,
    ToolMetadataPoisoningError,
    GroundingViolationError,
    PromptGuardUnavailableError,
    AgentAccessDeniedError,
    ServerVerificationError,
)
import logging
logger = logging.getLogger(__name__)

try:
    result = await middleware(context, call_next)
except (
    PromptInjectionError,
    RateLimitExceededError,
    TokenBudgetExceededError,
    CircuitBreakerOpenError,
    ContentFilterError,
    RBACError,
    SchemaValidationError,
    ReplayAttackError,
    CostBudgetExceededError,
    SemanticFirewallError,
    ExternalPolicyDeniedError,
    SensitiveContentError,
    AuthenticationError,
    ToolNotAllowedError,
    SessionScopeExceededError,
    ToolMetadataPoisoningError,
    GroundingViolationError,
    PromptGuardUnavailableError,
    AgentAccessDeniedError,
    ServerVerificationError,
) as e:
    logger.warning("blocked: %s", e.to_mcp_error())

// TypeScript: handlers return isError: true
import { logger, setLogLevel } from "@mcp-bastion/core";
setLogLevel("debug");  // optional: "debug" | "info" | "warn" | "error"
const result = await guardedHandler(request);
if (result.isError) {
  logger.error("blocked", result.content);
}

---

测试

MCP Inspector：

# Start your guarded server
python server.py   # or: npx tsx server.ts

# In another terminal, launch the Inspector
npx -y @modelcontextprotocol/inspector

通过 HTTP（http://localhost:8000/mcp）或 stdio 连接，然后：

1. 列出工具，并使用无害参数调用其中一个（应成功）
2. 使用“忽略之前的指令”调用一个工具（应被拦截）
3. 在一个会话中触发 16 次或更多工具调用（应触发速率限制）

---

测试

# Python (PYTHONPATH=src on Windows: $env:PYTHONPATH="src")
python -m pytest tests/ -v

# TypeScript
npm run test --workspace=@mcp-bastion/core

# Full validation checklist (build, pillars, latency)
PYTHONPATH=src python scripts/validate_checklist.py

# MCP Inspector (manual)
npx -y @modelcontextprotocol/inspector

第三方组件

许可证信息请参阅 NOTICE。MCP-Bastion 使用 Meta Llama Prompt Guard 2（Llama 4 Community License）和 Microsoft Presidio。有关与 OWASP 相关的缓解措施和依赖项审计，请参阅 docs/SECURITY.md。如需私下报告漏洞，请参阅 SECURITY.md。

许可证

MCP-Bastion 根据 MCP-Bastion Community and Commercial License (LICENSE) 发布。

• 非商业用途可免费使用，但须注明 MCP-Bastion 并保留版权声明（参阅 CITATION.cff；你可以将你自己的姓名、团队或组织列为作者或软件使用者，但仍须在致谢中注明项目和代码仓库）。
• 版权予以保留。请勿删除许可证或版权文本，也不得在未满足许可证条款的情况下，将本作品的副本作为无关软件重新发布。
• 商业用途（按许可证中的定义）可能仍需另行签订书面协议 - 请参阅 COMMERCIAL_LICENSE.md。

另请参阅：

• LICENSE
• COMMERCIAL_LICENSE.md
• FUNDING.md - 赞助与可持续发展
• SUPPORT.md - 文档、问题及响应预期
• CITATION.cff

---

产品概览与安全演示文稿

演示文稿	适用场景
MCP-Security-Deck-v3.pdf	首选 — 面向购买者、安全审查以及 LinkedIn / 销售分享的安全 / FinOps / 基准测试证明材料（原始文件）
docs/mcp-bastian-features-deck.pdf	面向深入了解的相关方，提供更详尽的功能介绍 / 核心支柱概览

演示文稿背后可复现的数据：docs/BENCHMARKS.md · 威胁模型：docs/THREAT_MODEL.md。