Bulwark

Bulwark

面向 AI Agent 的开源治理层。

Bulwark 位于 AI Agent 与外部工具之间，负责执行策略、管理凭据、检查内容并维护完整的审计记录。一套策略即可管理所有 Agent，包括 Claude Code、OpenClaw、Codex，以及任何 MCP/HTTP 客户端。

为什么选择 Bulwark？

AI Agent 功能强大，却缺乏治理。它们可以访问任何工具、泄露任何凭据，而且不留下审计记录。Bulwark 可以解决这些问题：

• 策略执行 — 基于 YAML 的规则控制 Agent 可使用哪些工具，支持 glob 模式、基于范围的优先级和热重载
• 凭据管理 — Agent 永远不会看到真实密钥。Bulwark 在最后一刻注入凭据，并使用 age 加密静态数据
• 内容检查 — 扫描请求和响应中的密钥、PII 和提示词注入，并自动拦截或脱敏
• 审计日志 — 每项操作都会记录在具备防篡改能力的 SQLite 数据库中，并使用 blake3 哈希链
• 速率限制 — 按会话、操作员、工具或全局设置令牌桶速率限制，并通过预算强制执行进行成本跟踪
• 原生支持 MCP — 可用作 MCP 网关或 HTTP 正向代理。每个工具调用响应都包含治理元数据

安装

# Homebrew (macOS / Linux)
brew install bpolania/tap/bulwark

# Docker
docker pull ghcr.io/bpolania/bulwark

# From source
git clone https://github.com/bpolania/bulwark.git
cd bulwark && cargo build --release

快速开始：通过 GitHub 对 Claude Code 进行治理

本指南将 Claude Code 通过 Bulwark 连接到 GitHub。每次工具调用都会经过策略评估、审计和凭据注入——整个过程约需 5 分钟。

前提条件： 已安装 Claude Code，拥有 GitHub 个人访问令牌，并安装 Node.js/npm（用于 GitHub MCP 服务）。

1. 初始化并验证

bulwark init my-project && cd my-project
bulwark doctor

doctor 会运行 9 项诊断检查。检查结果都应通过。

2. 存储 GitHub 令牌

bulwark cred add github-token --type bearer_token
# Prompts for the token — hidden input, encrypted with age at rest

在绑定文件中配置凭据与工具的绑定，让 Bulwark 知道应在 GitHub 工具调用时注入此令牌。

3. 配置上游 GitHub 服务

编辑 bulwark.yaml：

mcp_gateway:
  upstream_servers:
    - name: github
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

policy:
  policies_dir: "./policies"
  hot_reload: true

audit:
  enabled: true

inspect:
  enabled: true
  inspect_requests: true
  inspect_responses: true

确保在 shell 中设置了 GITHUB_TOKEN（export GITHUB_TOKEN=ghp_...）。

4. 编写策略

cat > policies/base.yaml << 'EOF'
metadata:
  name: quickstart-policy
  scope: global

rules:
  - name: allow-reads
    description: "Allow all read operations"
    match:
      actions: ["read_*", "get_*", "list_*", "search_*"]
    verdict: allow
    priority: 10

  - name: allow-github-writes
    description: "Allow creating issues, comments, PRs"
    match:
      tools: ["github__*"]
      actions: ["create_*", "update_*"]
    verdict: allow
    priority: 10

  - name: block-destructive
    description: "Block all delete and force-push operations"
    match:
      actions: ["delete_*", "force_push_*"]
    verdict: deny
    priority: 20
    message: "Destructive operations are blocked by policy"

  - name: default-deny
    match: {}
    verdict: deny
    priority: -100
    message: "No policy explicitly allows this action"
EOF

bulwark policy validate

5. 创建会话并连接 Claude Code

# Create a session (--ttl is in seconds: 28800 = 8 hours)
bulwark session create --operator $(whoami) --agent-type claude-code --ttl 28800
# → Token: bwk_sess_7f3a...

export BULWARK_SESSION="bwk_sess_7f3a..."   # paste your actual token

# Register Bulwark as an MCP server in Claude Code
claude mcp add --transport stdio bulwark \
  --env BULWARK_SESSION=$BULWARK_SESSION \
  -- bulwark mcp start

6. 使用 Claude Code——现在已受治理

启动 Claude Code。GitHub 工具会以命名空间形式显示，例如 github__list_issues、github__create_issue 等。

试试看：

“列出我仓库中未关闭的问题”

打开另一个终端：

bulwark audit tail

22:01:03  github__list_issues   ✓ allow   3ms  (allow-reads)

每次调用都会记录判定结果、匹配的规则和耗时。现在试试具有破坏性的操作：

“删除问题 #1”

22:02:01  github__delete_issue  ✗ deny    <1ms (block-destructive)

操作已拦截，耗时不到 1 毫秒——策略评估在内存中完成。Agent 会收到结构化错误，说明是哪条规则拒绝了该操作。

刚才发生了什么

Claude Code 连接的是 Bulwark，而不是直接连接 GitHub。每次工具调用时，Bulwark 都会验证会话、扫描密钥和 PII、评估策略、注入真实的 GitHub 令牌、扫描响应，并记录防篡改审计事件。Agent 的使用体验不变，底层则实现了全面治理。

深入了解

内容检查 — 13 种内置模式可扫描 AWS 密钥、GitHub 令牌、私钥、PII 和提示词注入。在内容到达 Agent 之前就会进行脱敏。

bulwark inspect rules
bulwark inspect scan --text "my key is AKIAIOSFODNN7EXAMPLE"

策略重放 — 在部署策略更改前，基于真实审计历史预览其影响：

bulwark policy test --dir ./new-policies/ --since 1h

审计取证 — 重建会话时间线并验证哈希链：

bulwark session inspect <session-id>
bulwark audit verify
bulwark audit export --since 24h --format json

HTTP 代理模式 — 对于非 MCP Agent，Bulwark 可作为带 TLS 拦截功能的正向代理运行：

bulwark proxy start
bulwark ca export   # trust the CA in your HTTP client

架构

┌─────────────┐     ┌──────────────────────────────────────────────┐     ┌──────────────┐
│             │     │                  Bulwark                      │     │              │
│  AI Agent   │────>│  Session > Inspect > Policy > Inject > Proxy │────>│  Upstream    │
│  (Claude,   │<────│  <── Audit <── Inspect <── Response <─────── │<────│  Tool/API    │
│   Codex,    │     │                                              │     │              │
│   custom)   │     └──────────────────────────────────────────────┘     └──────────────┘
└─────────────┘

集成模式

模式	传输方式	适用场景
MCP 网关（stdio）	stdio/JSON-RPC	Claude Code、OpenClaw、任何 MCP 客户端
MCP 网关（HTTP）	Streamable HTTP	远程 Agent、MCP 注册表、多 Agent 场景
HTTP 代理	HTTP/HTTPS	Codex、curl、任何 HTTP 客户端

策略示例

# policies/base.yaml
metadata:
  name: my-policy
  scope: global

rules:
  - name: allow-reads
    verdict: allow
    priority: 10
    match:
      actions: ["read*", "get*", "list*"]

  - name: block-destructive-in-prod
    verdict: deny
    priority: 100
    match:
      actions: ["delete*", "drop*"]
    conditions:
      environments: ["production"]

  - name: default-deny
    verdict: deny
    match: {}

完整的策略集（初创公司、企业、开发、多 Agent）请参见 examples/policies/。

命令行界面

bulwark init <path>              # Scaffold a new project
bulwark proxy start              # Start HTTP/HTTPS proxy
bulwark mcp start                # Start MCP gateway (stdio)
bulwark mcp serve                # Start MCP gateway (HTTP)
bulwark doctor                   # Diagnose setup issues (9 checks)
bulwark status                   # Health dashboard
bulwark policy validate          # Validate policy files
bulwark policy test --dir <path> # Test policies against audit log
bulwark session create|list|revoke|inspect
bulwark cred add|list|remove|test
bulwark audit search|tail|stats|export|verify
bulwark inspect scan|rules       # Content inspection
bulwark ca export|path           # CA certificate management
bulwark completions <shell>      # Shell completions (bash/zsh/fish)

Documentation

• Getting Started
• Architecture Overview
• Policy Reference
• Configuration Reference
• Credential Management
• Audit System
• Content Inspector
• Rate Limiting
• Threat Model
• Agent Guides: Claude Code | Codex | OpenClaw

Development

git clone https://github.com/bpolania/bulwark.git
cd bulwark
cargo build --workspace
cargo test --workspace          # 487 tests
cargo clippy --workspace --all-targets -- -D warnings

Project Structure

crates/
  cli/        # CLI binary and commands
  proxy/      # HTTP/HTTPS forward proxy with TLS MITM
  mcp/        # MCP governance gateway
  config/     # Configuration loading and types
  policy/     # YAML policy engine with hot-reload
  vault/      # Credential storage and session management
  audit/      # Tamper-evident audit logging
  inspect/    # Content inspection (secrets, PII, injection)
  ratelimit/  # Token-bucket rate limiter and cost tracker
  common/     # Shared types and error definitions

License

Apache 2.0. See LICENSE.