AlwaysReadyAllies/warden

# 🛡️ Warden [](https://pypi.org/project/warden-mcp/) [](https://pypi.org/project/warden-mcp/) [](LICENSE) **MCP 的直接替换式安全 middleware。** 将你的 AI 客户端指向 Warden 而不是原始的 tool-server —— 只需一行配置，零代码改动 —— 并且每一次 tool 调用都会被进行防篡改记录， 根据 policy 进行允许/拒绝/拦截，在遇到危险操作时暂停以等待人工批准，并且会进行扫描以 防范 prompt 注入以及敏感信息/PII（个人身份信息）泄露。 ## 工作原理 ``` AI client ──MCP──▶ WARDEN ──MCP──▶ downstream MCP servers policy · audit · approval · guard (filesystem, github, payments, …) ``` 对于你的客户端，Warden 是一个 MCP **server**，而对于每一个真实的 server，它则是一个 MCP **client**。它会聚合 它们的 tool（以 `server__tool` 命名空间划分），并通过以下路径路由每一次 `tools/call`： **policy → audit(request) → guard(args) → [deny | approve | allow] → forward → guard(result) → audit(response)** ## 快速开始 ``` uvx warden-mcp init # write a starter warden.yaml uvx warden-mcp run --config warden.yaml uvx warden-mcp audit verify # prove the audit log wasn't altered ``` “地毯式抽离”防御（TOFU tool 定义锁定）**默认开启** —— 如果一个下游 tool 的 定义在你首次批准后发生了改变，它将被隔离，直到你再次批准。 ### 可选：防范恶意操作者的防篡改机制 普通的审计日志可以检测到未经重新链接的编辑。为了让即使拥有主机写入权限的人也能检测到篡改，请启用**前向安全密封**（使用标准库，无需额外依赖）： ``` uvx warden-mcp audit setup-keys --out warden.seed # prints a VERIFICATION SEED — store it OFF-box uvx warden-mcp run --seal-state warden_seal_state.json --anchor heads.jsonl uvx warden-mcp audit verify --log warden_audit.jsonl --seed warden.seed # verifies the seals ``` 在系统被入侵之前密封的记录事后无法被伪造或重写——因为用于密封的密钥已经向前更新并被销毁。（防篡改-**可见**，而非防篡改：删除操作始终是 可能的，你可以通过主机外部的锚定头部来检测它。） 将你的客户端指向它（例如 `.mcp.json` / Claude Desktop / Cursor）： ``` { "mcpServers": { "warden": { "command": "uvx", "args": ["warden-mcp", "run"] } } } ``` ## Policy (`warden.yaml`) ``` mode: allow # allow (log all, gate listed) | strict (deny unless allowed) servers: filesystem: cmd: ["npx","-y","@modelcontextprotocol/server-filesystem","/work"] tools: read_file: { action: allow } write_file: { action: gate, reason: "file write" } delete_*: { action: deny } payments: url: "http://localhost:9001/mcp" tools: { "*": { action: gate } } sensitive_actions: [transfer, send, delete, purchase, grant, deploy] rules: - id: dangerous-shell match: { arg_regex: "rm\\s+-rf|DROP\\s+TABLE" } action: deny - id: secret-egress match: { direction: result, contains: ["BEGIN PRIVATE KEY", "password="] } action: redact_and_flag ``` `policies/` 中的入门 policy：**paranoid · balanced · dev**。 ### 跨 server 数据流：致命三要素防御 单次调用规则无法察觉跨越 session 的攻击——从一个 server 读取不受信任的内容， 被注入的指令所引导，然后通过另一个 server 泄露出去。标记这些端点，Warden 就能追踪 数据流：一旦不受信任的 **source** 向 session 中返回了内容，任何能够进行数据泄露的 **sink** 都会被拒绝（或拦截）： ``` flow: on_violation: gate # gate (ask a human) | deny (default, fail closed) sources: ["web__*", "email__read*"] # tools whose results are untrusted content sinks: ["email__send*", "http__post", "slack__*"] # tools that can send data out ``` “涉及不受信任内容的上下文，如果没有人工干预，不得流向具备数据泄露能力的 tool。” ## 远程部署：HTTP 网关 + OAuth 2.1 将 Warden 作为可部署的 HTTP MCP 网关（流式传输）运行，而不是使用 stdio： ``` pip install "warden-mcp[http,auth]" uvx warden-mcp run --http --host 0.0.0.0 --port 8080 --config warden.yaml ``` 配置了 `auth:` 块后，Warden 就是一个 **OAuth 2.1 Resource Server** —— 每一个发往 `/mcp` endpoint 的请求都必须携带有效的 bearer token，否则将被拒绝，在**到达任何 tool 之前**就返回 `401` + `WWW-Authenticate` 质询。它根据 MCP 授权规范进行验证：RFC 9728 Protected Resource Metadata（通过 `/.well-known/oauth-protected-resource` 提供）、**RFC 8707 audience binding** （为其他服务生成的 token 会被拒绝）、JWKS 签名验证（仅限非对称加密——不允许 `alg:none`）以及 scope 强制校验。 ``` auth: resource: https://warden.example/mcp issuer: https://auth.example/ jwks_uri: https://auth.example/.well-known/jwks.json required_scopes: [mcp:call] ``` （stdio 是一个本地单用户信任边界，不需要 token；没有配置 `auth:` 块的 `--http` 会开放服务——请将其置于你自己的安全边界之后。） ### 远程批准（Telegram） 在 headless / `--http` 模式下没有终端，因此被拦截的调用会直接失败关闭。你可以转而从 手机上进行批准 —— 运行 `pip install "warden-mcp[telegram]"` 并添加： ``` approval: channel: telegram bot_token_env: WARDEN_TELEGRAM_TOKEN # token read from the environment, never the file chat_id: "123456789" ``` 每一个被拦截的调用都会发送一条带有内联 **Approve** / **Deny** 按钮的消息；超时或任何错误 都会导致失败关闭。 ## `mcp-scan` —— 在信任 server 之前进行审计 Warden 在 runtime 保护 tool 调用；而 `mcp-scan` 是静态的、安装前的配套工具。将其指向一个 MCP server，它会检查每一个 tool **definition**，以防范隐藏在描述中的 tool 投毒 / prompt 注入、schema 中的机密信息、危险的功能，以及**致命三要素组合**（一个既能 读取不受信任的内容*又能*进行数据泄露的 server）。遇到风险时会以非零状态退出，因此可以对 CI 进行拦截。 ``` mcp-scan --command npx --arg -y --arg @some/mcp-server # or --url https://…/mcp, or --config .mcp.json warden scan --config .mcp.json --json # same, as a warden subcommand ``` 它复用了 Warden 自己的 guard 语料库、锁定指纹和数据流分类法——这是同一 引擎的静态半边。（填补了 Invariant 的 `mcp-scan` 被收购并关闭后留下的空白。） ## 为什么值得信赖 - **防篡改审计** —— 哈希链式 JSONL；`warden audit verify` 可检测任何编辑/插入/删除操作。 添加**前向安全密封**，以抓获甚至重写并重新链接日志的恶意操作者。 - **“地毯式抽离”防御** —— TOFU 锁定机制会将批准后定义发生变化的 tool 隔离。 - **失败关闭** —— 批准超时、无通信渠道、未设 guard 的脱敏，或任何非 yes 的回复 ⇒ 均被阻止。 - **纵深防御** —— 当 policy 显示允许时，guard 也会硬拒绝明确具有破坏性的 payload（`rm -rf`、 `mkfs`、`DROP TABLE`），并对泄露的机密（提供商密钥、JWT、私钥）进行脱敏。`direction: result` 规则可以拒绝泄露信息的响应（例如私钥）。 - **默认不信任下游** —— tool 元数据会经过命名空间划分、验证和剥离，绝不 直接透传；恶意的下游 server 无法隐藏另一个 server，也无法通过 tool 描述进行注入。 - **零出站流量** —— 核心 proxy + guard 不会自行发起任何网络调用。guard 是纯 本地的正则表达式——在请求路径中没有 LLM（具备确定性、速度快、不会有任何数据离开本机）。 ## 目录结构 ``` warden/ schemas.py shared contract (closed-enum decisions, hash-by-default audit) proxy.py MCP upstream server + downstream clients + namespacing + pin check interceptor.py the policy→audit→approval→guard pipeline (+ REDACT + result rules) policy.py YAML → allow/deny/gate/redact/redact_and_flag (request + result direction) guard.py prompt-injection corpus + secret/PII + shell/SQL/path detection audit.py hash-chained tamper-evident log + verify (+ forward-secure seals) sealing.py forward-secure sealing + external anchoring (hostile-operator defense) pinning.py TOFU tool-definition pinning (rug-pull defense) auth.py OAuth 2.1 Resource Server — RFC 9728/8707, JWKS, scopes (extra: [auth]) http.py deployable HTTP MCP gateway + bearer-auth middleware (extra: [http]) flow.py cross-server dataflow / lethal-trifecta defense (session taint tracking) scan.py mcp-scan — static pre-install risk audit of an MCP server's tools scan_cli.py the `mcp-scan` console script + `warden scan` subcommand approval/ human-in-the-loop — CLI (/dev/tty) + Telegram (headless/remote, extra: [telegram]) ``` Apache-2.0 · 由 Always Ready Allies LLC 构建。安全联系方式：参见 `SECURITY.md`。

标签：AI安全, Chat Copilot, MCP中间件, Python, Streamlit, 安全代理, 无后门, 策略控制, 访问控制, 请求响应过滤, 逆向工具