shield

Name: shield
Author: bolyra

本地服务

github.com/bolyra安全04 天前更新

代码仓库

关于 shield

@bolyra/shield 是 stdio 认证代理，可封装 MCP 服务并按工具执行权限策略，无需修改服务代码。它验证 Agent 凭证、防止证明重放，并生成审计回执。

主要功能

01以子进程方式封装 MCP 服务
02验证工具调用中的凭证
03按工具执行权限策略
04通过随机数跟踪防止重放
05根据已发现工具生成策略
06向 stderr 输出审计回执

适用场景

01为本地 MCP 服务添加认证
02按权限级别限制工具调用
03根据服务工具列表生成默认拒绝策略

MCP 相关

Shield 通过 stdio 位于 MCP 客户端与服务之间。它转发初始化和工具列表请求，并在转发工具调用前验证凭证与策略。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "bolyra-shield": {
      "command": "npx",
      "args": [
        "-y",
        "@bolyra/shield"
      ]
    }
  }
}

启动命令npx -y @bolyra/shield

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@bolyra/shield0.1.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@bolyra/shield

Stdio MCP 身份验证代理。为任意 MCP 服务添加按工具执行的权限控制、防重放保护和审计收据。无需修改服务代码。

快速入门

npx @bolyra/shield --server "npx @modelcontextprotocol/server-filesystem /tmp" --dev

Shield 会将目标服务作为子进程启动，拦截 tools/call 请求，验证 Agent 凭据，并在转发之前执行工具策略。

配置

创建 shield.yaml：

devMode: true
defaultDeny: true

nonce:
  store: memory
  maxProofAge: 300

receipts:
  enabled: true
  output: stderr

tools:
  read_file:
    requireBitmask: 1    # READ_DATA
  write_file:
    requireBitmask: 2    # WRITE_DATA
  delete_file:
    requireBitmask: 2    # WRITE_DATA

然后：

npx @bolyra/shield --server "node my-server.js" --config shield.yaml

默认拒绝

默认情况下，没有策略条目的工具会被放行（只检查身份验证）。设置 defaultDeny: true，即可拒绝针对 tools: 映射中未列出工具名称的任何 tools/call 请求。

学习模式

无需手动编写配置——从服务自身的工具列表生成安全的起始配置：

npx @bolyra/shield --learn --server "node my-server.js"

学习模式会启动服务，执行 MCP 握手（initialize → notifications/initialized → tools/list，并遵循分页），然后写入 shield.yaml（或 --config 指定的路径），其中包含：

defaultDeny: true — 服务之后新增的任何工具都会被拒绝，直到你明确允许
每个发现的工具均设置为 requireBitmask: 1（READ_DATA）——最低权限基线
_generated 来源信息块（源命令 + 时间戳）

它不会覆盖已有配置文件，分页上限为 50 页，并会在 30 秒后超时。生成的配置只是起点：正式使用前请检查每个工具，并提高其 requireBitmask（例如，将 write_file 设为 2）。

工作原理

Agent ←stdin/stdout→ Shield ←stdin/stdout→ MCP Server
                       │
                 verifyBundle()
                 checkToolPolicy()
                 nonceStore.markIfFresh()
                 emitReceipt()

initialize、tools/list、ping — 无需身份验证，直接转发
tools/call — 从 params._meta.bolyra 提取证明并进行验证、检查策略，然后转发或拒绝
收据输出到 stderr（stdout 是 MCP 传输通道）

权限位掩码

位	权限
0	READ_DATA
1	WRITE_DATA
2	FINANCIAL_SMALL
3	FINANCIAL_MEDIUM
4	FINANCIAL_UNLIMITED
5	SIGN_ON_BEHALF
6	SUB_DELEGATE
7	ACCESS_PII

Shield 与 Gateway

	Shield	Gateway
传输方式	stdio	HTTP
使用场景	本地 MCP 服务（Claude Desktop、Cursor）	远程／联网 MCP 服务
封装方式	启动子进程	反向代理
证明来源	`params._meta.bolyra`	`Authorization: Bolyra <base64>` 标头
收据	stderr	stdout／文件／webhook

两者都使用来自 @bolyra/mcp 的相同 verifyBundle() 和 checkToolPolicy()。

库用法

import { createShield, loadShieldConfig } from '@bolyra/shield';

const config = loadShieldConfig('./shield.yaml');
const { child, stop } = createShield(config);