{
  "markdown": "# Bulwark\n\n**Open-source governance layer for AI agents.**\n\nBulwark sits between AI agents and external tools, enforcing policies, managing credentials, inspecting content, and maintaining a complete audit trail. One policy governs all your agents — Claude Code, OpenClaw, Codex, or any MCP/HTTP client.\n\n## Why Bulwark?\n\nAI agents are powerful but ungoverned. They can access any tool, leak any credential, and leave no audit trail. Bulwark fixes this:\n\n- **Policy enforcement** — YAML-based rules control which tools agents can use, with glob patterns, scope-based precedence, and hot-reload\n- **Credential management** — Agents never see real secrets. Bulwark injects credentials at the last mile, encrypted at rest with age\n- **Content inspection** — Scan requests and responses for secrets, PII, and prompt injection. Block or redact automatically\n- **Audit logging** — Every action recorded in a tamper-evident SQLite database with blake3 hash chains\n- **Rate limiting** — Token-bucket rate limits per session, operator, tool, or globally. Cost tracking with budget enforcement\n- **MCP-native** — Works as an MCP gateway or HTTP forward proxy. Governance metadata on every tool call response\n\n## Install\n\n```bash\n# Homebrew (macOS / Linux)\nbrew install bpolania/tap/bulwark\n\n# Docker\ndocker pull ghcr.io/bpolania/bulwark\n\n# From source\ngit clone https://github.com/bpolania/bulwark.git\ncd bulwark && cargo build --release\n```\n\n## Quick Start: Govern Claude Code with GitHub\n\nThis walkthrough connects Claude Code to GitHub through Bulwark. Every tool call is policy-evaluated, audited, and credential-injected — in about 5 minutes.\n\n**Prerequisites:** [Claude Code](https://code.claude.com/) installed, a [GitHub personal access token](https://github.com/settings/tokens), and Node.js/npm (for the GitHub MCP server).\n\n### 1. Initialize and verify\n\n```bash\nbulwark init my-project && cd my-project\nbulwark doctor\n```\n\n`doctor` runs 9 diagnostic checks. All should pass.\n\n### 2. Store your GitHub token\n\n```bash\nbulwark cred add github-token --type bearer_token\n# Prompts for the token — hidden input, encrypted with age at rest\n```\n\nConfigure the credential-to-tool binding in your bindings file so Bulwark knows to inject this token for GitHub tool calls.\n\n### 3. Configure the upstream GitHub server\n\nEdit `bulwark.yaml`:\n\n```yaml\nmcp_gateway:\n  upstream_servers:\n    - name: github\n      command: \"npx\"\n      args: [\"-y\", \"@modelcontextprotocol/server-github\"]\n      env:\n        GITHUB_PERSONAL_ACCESS_TOKEN: \"${GITHUB_TOKEN}\"\n\npolicy:\n  policies_dir: \"./policies\"\n  hot_reload: true\n\naudit:\n  enabled: true\n\ninspect:\n  enabled: true\n  inspect_requests: true\n  inspect_responses: true\n```\n\nMake sure `GITHUB_TOKEN` is set in your shell (`export GITHUB_TOKEN=ghp_...`).\n\n### 4. Write a policy\n\n```bash\ncat > policies/base.yaml << 'EOF'\nmetadata:\n  name: quickstart-policy\n  scope: global\n\nrules:\n  - name: allow-reads\n    description: \"Allow all read operations\"\n    match:\n      actions: [\"read_*\", \"get_*\", \"list_*\", \"search_*\"]\n    verdict: allow\n    priority: 10\n\n  - name: allow-github-writes\n    description: \"Allow creating issues, comments, PRs\"\n    match:\n      tools: [\"github__*\"]\n      actions: [\"create_*\", \"update_*\"]\n    verdict: allow\n    priority: 10\n\n  - name: block-destructive\n    description: \"Block all delete and force-push operations\"\n    match:\n      actions: [\"delete_*\", \"force_push_*\"]\n    verdict: deny\n    priority: 20\n    message: \"Destructive operations are blocked by policy\"\n\n  - name: default-deny\n    match: {}\n    verdict: deny\n    priority: -100\n    message: \"No policy explicitly allows this action\"\nEOF\n\nbulwark policy validate\n```\n\n### 5. Create a session and connect Claude Code\n\n```bash\n# Create a session (--ttl is in seconds: 28800 = 8 hours)\nbulwark session create --operator $(whoami) --agent-type claude-code --ttl 28800\n# → Token: bwk_sess_7f3a...\n\nexport BULWARK_SESSION=\"bwk_sess_7f3a...\"   # paste your actual token\n\n# Register Bulwark as an MCP server in Claude Code\nclaude mcp add --transport stdio bulwark \\\n  --env BULWARK_SESSION=$BULWARK_SESSION \\\n  -- bulwark mcp start\n```\n\n### 6. Use Claude Code — now governed\n\nStart Claude Code. GitHub tools appear namespaced as `github__list_issues`, `github__create_issue`, etc.\n\nTry it:\n\n> \"List the open issues in my repo\"\n\nOpen a second terminal:\n\n```bash\nbulwark audit tail\n```\n\n```\n22:01:03  github__list_issues   ✓ allow   3ms  (allow-reads)\n```\n\nEvery call is logged with the verdict, matched rule, and timing. Now try something destructive:\n\n> \"Delete issue #1\"\n\n```\n22:02:01  github__delete_issue  ✗ deny    <1ms (block-destructive)\n```\n\nBlocked. Sub-millisecond — policy evaluation happens in memory. The agent gets a structured error explaining which rule denied it.\n\n### What just happened\n\nClaude Code connected to Bulwark (not directly to GitHub). For every tool call, Bulwark validated the session, scanned for secrets/PII, evaluated the policy, injected the real GitHub token, scanned the response, and recorded a tamper-evident audit event. Same agent experience — full governance underneath.\n\n## Going Deeper\n\n**Content inspection** — 13 built-in patterns scan for AWS keys, GitHub tokens, private keys, PII, and prompt injection. Redaction happens before content reaches the agent.\n\n```bash\nbulwark inspect rules\nbulwark inspect scan --text \"my key is AKIAIOSFODNN7EXAMPLE\"\n```\n\n**Policy replay** — Preview the impact of policy changes against real audit history before deploying:\n\n```bash\nbulwark policy test --dir ./new-policies/ --since 1h\n```\n\n**Audit forensics** — Reconstruct a session timeline and verify the hash chain:\n\n```bash\nbulwark session inspect <session-id>\nbulwark audit verify\nbulwark audit export --since 24h --format json\n```\n\n**HTTP proxy mode** — For non-MCP agents, Bulwark runs as a forward proxy with TLS interception:\n\n```bash\nbulwark proxy start\nbulwark ca export   # trust the CA in your HTTP client\n```\n\n## Architecture\n\n```\n┌─────────────┐     ┌──────────────────────────────────────────────┐     ┌──────────────┐\n│             │     │                  Bulwark                      │     │              │\n│  AI Agent   │────>│  Session > Inspect > Policy > Inject > Proxy │────>│  Upstream    │\n│  (Claude,   │<────│  <── Audit <── Inspect <── Response <─────── │<────│  Tool/API    │\n│   Codex,    │     │                                              │     │              │\n│   custom)   │     └──────────────────────────────────────────────┘     └──────────────┘\n└─────────────┘\n```\n\n## Integration Modes\n\n| Mode | Transport | Best For |\n|------|-----------|----------|\n| MCP Gateway (stdio) | stdio/JSON-RPC | Claude Code, OpenClaw, any MCP client |\n| MCP Gateway (HTTP) | Streamable HTTP | Remote agents, MCP registry, multi-agent |\n| HTTP Proxy | HTTP/HTTPS | Codex, curl, any HTTP client |\n\n## Example Policy\n\n```yaml\n# policies/base.yaml\nmetadata:\n  name: my-policy\n  scope: global\n\nrules:\n  - name: allow-reads\n    verdict: allow\n    priority: 10\n    match:\n      actions: [\"read*\", \"get*\", \"list*\"]\n\n  - name: block-destructive-in-prod\n    verdict: deny\n    priority: 100\n    match:\n      actions: [\"delete*\", \"drop*\"]\n    conditions:\n      environments: [\"production\"]\n\n  - name: default-deny\n    verdict: deny\n    match: {}\n```\n\nSee [examples/policies/](./examples/policies/) for complete policy sets (startup, enterprise, development, multi-agent).\n\n## CLI\n\n```\nbulwark init <path>              # Scaffold a new project\nbulwark proxy start              # Start HTTP/HTTPS proxy\nbulwark mcp start                # Start MCP gateway (stdio)\nbulwark mcp serve                # Start MCP gateway (HTTP)\nbulwark doctor                   # Diagnose setup issues (9 checks)\nbulwark status                   # Health dashboard\nbulwark policy validate          # Validate policy files\nbulwark policy test --dir <path> # Test policies against audit log\nbulwark session create|list|revoke|inspect\nbulwark cred add|list|remove|test\nbulwark audit search|tail|stats|export|verify\nbulwark inspect scan|rules       # Content inspection\nbulwark ca export|path           # CA certificate management\nbulwark completions <shell>      # Shell completions (bash/zsh/fish)\n```\n\n## Documentation\n\n- [Getting Started](./docs/getting-started.md)\n- [Architecture Overview](./docs/architecture.md)\n- [Policy Reference](./docs/policy-reference.md)\n- [Configuration Reference](./docs/configuration.md)\n- [Credential Management](./docs/credentials.md)\n- [Audit System](./docs/audit.md)\n- [Content Inspector](./docs/content-inspector.md)\n- [Rate Limiting](./docs/rate-limiting.md)\n- [Threat Model](./docs/threat-model.md)\n- Agent Guides: [Claude Code](./docs/agents/claude-code.md) | [Codex](./docs/agents/codex.md) | [OpenClaw](./docs/agents/openclaw.md)\n\n## Development\n\n```bash\ngit clone https://github.com/bpolania/bulwark.git\ncd bulwark\ncargo build --workspace\ncargo test --workspace          # 487 tests\ncargo clippy --workspace --all-targets -- -D warnings\n```\n\n### Project Structure\n\n```\ncrates/\n  cli/        # CLI binary and commands\n  proxy/      # HTTP/HTTPS forward proxy with TLS MITM\n  mcp/        # MCP governance gateway\n  config/     # Configuration loading and types\n  policy/     # YAML policy engine with hot-reload\n  vault/      # Credential storage and session management\n  audit/      # Tamper-evident audit logging\n  inspect/    # Content inspection (secrets, PII, injection)\n  ratelimit/  # Token-bucket rate limiter and cost tracker\n  common/     # Shared types and error definitions\n```\n\n## License\n\nApache 2.0. See [LICENSE](./LICENSE).",
  "bytes": 9602,
  "sha": "cb95aca1473e9c6ed68e6628099b89fdb886cca188f5d097b9044e8f126c6c89",
  "repo_slug": "bpolania/bulwark",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bpolania_bulwark_5a8073a5/readme"
}