TikyParkinson/mcp-agent-guardrails-spring-boot-starter
GitHub: TikyParkinson/mcp-agent-guardrails-spring-boot-starter
为 Java/Spring Boot 应用中 MCP 智能体的工具调用提供审计、授权、提示注入检测、速率限制等安全护栏的零配置 Spring Boot Starter。
Stars: 2 | Forks: 0
# MCP Agent Guardrails
[](https://central.sonatype.com/artifact/io.github.tikyparkinson/mcp-guardrails-spring-boot-starter)
[](https://github.com/TikyParkinson/mcp-agent-guardrails-spring-boot-starter/actions/workflows/ci.yml)
[](https://github.com/TikyParkinson/mcp-agent-guardrails-spring-boot-starter/actions/workflows/codeql.yml)
[](LICENSE)
MCP Agent Guardrails 帮助您在 Java / Spring Boot 应用中以极其简单的方式围绕
[MCP](https://modelcontextprotocol.io) 工具调用建立安全与治理控制。每次工具调用在执行前都会经过一系列护栏链条 —— 包括审计、
授权、prompt 注入检测和速率限制。
当您将 MCP 工具暴露给 LLM 代理时，“客户端”是一个自行决定调用什么以及使用哪些参数的模型。本项目填补了由此产生的四个缺口。
我们的主要目标是：
* **零配置**即可运行：只需添加一个依赖，所有四个护栏就会启用，并带有合理的内存默认值。
* 坚持己见，但不碍事：每个存储、策略源和规则集都是一个端口（port）——
只需暴露您自己的 bean，默认配置就会自动让步。
* **默认拒绝（Fail closed）**：损坏的护栏或审计存储绝不会默默放行任何调用。
* 绝不持久化工具参数（存在 PII/敏感信息泄露风险）—— 审计跟踪仅携带元数据。
## 模块
| 模块 | 描述 |
|---|---|
| [guardrails-core](guardrails-core) | 共享模型、`Guardrail` 和 `ResultGuardrail` SPI、入站和出站链条，以及 MCP 工具调用拦截器 |
| [guardrails-audit](guardrails-audit) | 工具调用的审计跟踪 + 其他护栏使用的审计总线 |
| [guardrails-authz](guardrails-authz) | 声明式代理→工具授权策略（首次匹配优先规则） |
| [guardrails-injection-guard](guardrails-injection-guard) | 基于规则对工具参数进行 prompt 注入检测 |
| [guardrails-ratelimit](guardrails-ratelimit) | 针对（代理，工具）对的固定窗口速率限制 |
| [guardrails-tool-integrity](guardrails-tool-integrity) | 对每个工具定义采用首次使用信任（Trust-on-first-use）的指纹记录，阻止工具投毒（tool-poisoning）式的暗中替换 |
| [guardrails-credential-leak-guard](guardrails-credential-leak-guard) | 检测工具参数中的凭据，并对工具返回的凭据进行脱敏 |
| [guardrails-egress-control](guardrails-egress-control) | 针对具备网络能力的工具的出站目标允许列表，默认为空 |
| [guardrails-anomaly-detector](guardrails-anomaly-detector) | 如果代理的近期历史记录看起来像是在循环，或者在其从未使用过的工具中进行扫描，则对其进行升级处理 |
| [guardrails-approval-gate](guardrails-approval-gate) | 暂挂升级后的调用，直到人员批准或拒绝；保持沉默等同于拒绝 |
| [guardrails-trifecta-correlator](guardrails-trifecta-correlator) | 当私密数据、不受信任的内容和出站通信三者在一个会话中交汇时，对该会话进行升级处理 |
| [spring-boot-starter](spring-boot-starter) | 将所有内容组装在一起的自动配置 —— 即您需要导入的构件 |
## 安装与入门
添加该 starter —— 这就是您需要做的全部操作：
```
io.github.tikyparkinson
mcp-guardrails-spring-boot-starter
0.2.0
```
您的 MCP 服务器中的任何 `SyncToolSpecification` bean 都会被自动装饰；您无需更改
注册工具的方式。被拒绝的调用将返回一个 `isError` 的 MCP 结果，并且工具永远不会运行。
### 开箱即用
在无任何配置的情况下，全部十一个模块都会加载，并且它们中的每一个都处于允许状态：那些
需要策略的护栏会从一个空策略开始，因此升级版本绝不会开始拒绝您之前已经成功进行的调用。您将立即获得审计跟踪、工具定义基准和异常历史记录；
随着您声明工具的具体功能，其余的护栏也会开始为您保驾护航。
有两件事值得特意开启，因为它们正是整个链条大部分推理的基础：
- **哪些工具会与外部通信**，针对 `egress-control`
- **每个工具能做什么**，针对 `trifecta-correlator`
### 配置模块
每个模块都有其自己的前缀和 `enabled` 标志。请注意，有三个前缀比模块名称短：`egress`、`anomaly` 和 `trifecta`。
```
mcp:
guardrails:
enabled: true # master switch; false disables everything
authz: # who may call what
default-effect: DENY
rules:
- { agent: "prod-agent", tool: "*", effect: ALLOW }
- { agent: "*", tool: "drop_database", effect: ESCALATE }
tool-integrity: # trust on first use; blocks rug-pulls
on-mismatch: DENY
on-unknown-definition: ALLOW
injection-guard: # prompt injection in tool arguments
built-in-rules-enabled: true
credential-leak: # secrets in arguments, and in what tools return
on-confirmed-input: DENY
on-suspected-input: ESCALATE
on-output-text: REDACT
egress: # where tools are allowed to send data
on-violation: DENY
allowed-destinations: ["api.internal.example.com"]
tools:
- { name: "http_post", destination-arguments: ["url"] }
anomaly: # loops and sweeps in recent history
window: PT1M
repeat-threshold: 5
novel-tool-threshold: 3
trifecta: # private data + untrusted content + egress in one session
session-idle-timeout: PT30M
session-max-duration: PT2H
tools:
- { name: "read_customer", capabilities: [PRIVATE_DATA] }
- { name: "fetch_page", capabilities: [UNTRUSTED_CONTENT] }
- { name: "send_email", capabilities: [EXTERNAL_COMMS] }
approval: # holds an escalated call until a person decides
timeout: PT2M
max-pending: 20
ratelimit:
max-invocations: 60
window: PT1M
audit:
in-memory-max-events: 1000
```
将模块的 `enabled: false` 设置为 false 会将其护栏从链条中移除，并保持其余部分
继续运行。每个模块的 README 文档都记录了其完整的属性列表及其可插拔的端口。
### 调用如何被评估
护栏以固定的顺序运行，并且**它们全部始终参与评估**，因此即使第一个护栏已经拒绝了调用，您也能获得完整的决策跟踪：
```
audit → tool-integrity → authz → injection-guard → credential-leak
→ egress-control → anomaly-detector → trifecta-correlator → ratelimit
```
`audit` 最先运行，因此被拒绝的调用仍会被记录；`ratelimit` 最后运行，因此较早被拒绝的调用不会消耗配额。判定的优先级组合规则为 `Deny > Escalate > Allow`。
工具返回后，第二条链条会检查响应 —— 目前 `credential-leak` 会对工具放在其自身输出中的机密信息进行脱敏。
### 升级处理需要去向
`Escalate`（升级）判定并不是一种拒绝：它是一个请求人工决策的申请。
[guardrails-approval-gate](guardrails-approval-gate) 会暂挂调用，直到有人批准或
拒绝它，而保持沉默即视为拒绝。它默认位于 classpath 中，但它需要一个通道：starter 将 `ResolveApprovalUseCase` 作为 bean 发布，供您注入到自己的 controller 中，且其本身不附带任何 HTTP endpoint。该 endpoint 决定了谁有权解除限制，因此请像保护核心特权接口一样保护它。
如果不存在 `EscalationResolver`，升级处理将向代理返回一个错误 —— 即默认拒绝（fail-closed），
但其表现与普通失败毫无区别。Starter 正会在启动时针对这种情况发出警告。
## 获取帮助
* 查看上面链接的各个模块的 README —— 每个文档都详细说明了配置属性以及如何
替换默认适配器。
* 阅读 [ARCHITECTURE.md](ARCHITECTURE.md)，这是项目的最高准则：包含六边形架构规则、
质量门禁以及完成定义（Definition of Done）。
* 正式的规范文档位于 [docs/specs](docs/specs) 中 —— 每个模块包含一份规范以及一份批准记录
（`*-DONE.md`）。
* 在 [github.com/TikyParkinson/mcp-agent-guardrails-spring-boot-starter/issues](https://github.com/TikyParkinson/mcp-agent-guardrails-spring-boot-starter/issues) 报告 bug。
## 报告问题
* 在记录 bug 之前，请先在 issue 跟踪器中搜索，看看是否已经有人报告过
该问题。
* 请提供尽可能多的信息：项目版本、JVM 版本、MCP SDK 版本，如果可能的话，请提供一个能复现
该问题的测试用例。
## 从源码构建
您需要 JDK 25 和 Docker（audit 和 ratelimit 模块会通过 Testcontainers 针对真实的 PostgreSQL 运行集成测试）。
```
$ mvn verify
```
除非一切正常，否则 `mvn verify` 会导致构建失败：包含 163 个测试用例、每个模块的 Jacoco 覆盖率（行和分支）≥ 80%（目前在所有六个模块上均为 100%/100%）、要求通过 Spotless 格式化和 Checkstyle 检查。
CI 会在每次 push 和 pull request 时运行相同的命令
（[ci.yml](.github/workflows/ci.yml)）；发布版本则是从 `v*.*.*` 标签推送到 Maven Central
（[release.yml](.github/workflows/release.yml)）。
## 许可证
MCP Agent Guardrails 是开源软件，基于
[Apache 2.0 许可证](LICENSE) 发布。
标签：AI安全, Chat Copilot, JS文件枚举, MCP, Spring Boot, Streamlit, 域名枚举, 审计日志, 测试用例, 访问控制, 配置错误, 零日漏洞检测