rampart (Peg)

壁垒

AI编码代理的防火墙。

    

______________________________________________________________________

克劳德代码 --dangerously-skip-permissions 模式，以及Cline和Codex中的类似自主模式，使代理可以不受限制地访问shell。你的代理可以读取你的SSH密钥，窃取你的 .env，或 rm -rf / 没有护栏。

Rampart位于代理和系统之间。每个命令、文件访问和网络请求在执行之前都会根据您的策略进行评估。危险命令从不运行。

______________________________________________________________________

安装

# Homebrew (macOS and Linux, recommended)
brew install peg/tap/rampart

# One-line install (no sudo required)
curl -fsSL https://rampart.sh/install | bash

# Go install (requires Go 1.24+)
go install github.com/peg/rampart/cmd/rampart@latest

Windows（PowerShell）：

irm https://rampart.sh/install.ps1 | iex

安装后，运行 rampart quickstart 或按照以下设置步骤进行操作。

______________________________________________________________________

快速启动

选择您的代理并运行一个命令：

# Claude Code
rampart setup claude-code

# OpenClaw
rampart setup openclaw

# Cline
rampart setup cline

# Codex CLI
rampart setup codex

# Any other agent (wraps $SHELL)
rampart wrap -- your-agent

就是这样。确认一切正常：

rampart doctor

然后实时观察你的经纪人：

rampart watch

可选持久本地配置

如果您不想继续导出环境变量，Rampart还支持 ~/.rampart/config.yaml 对于本地默认值：

url: http://127.0.0.1:9090
# serve_url: http://127.0.0.1:9090   # compatibility alias for url
# api: http://127.0.0.1:9091         # optional advanced override for daemon/split-topology API setups

笔记：

• url 是主旋钮；除非你有明确的理由不这样做，否则请使用它。
• api 是 不 正常设置 rampart serve；它适用于高级守护进程/拆分拓扑设置。
• 客户端 --api 旗帜期待 API基本URL (http://127.0.0.1:9091)，而守护进程/服务器 --api 标志是指 API监听地址 (127.0.0.1:9091).

分辨率顺序为：flag→ 环境→ 配置文件→ 自动发现状态→ 违约。

一旦运行，每个工具调用都会首先通过Rampart的策略引擎：

ALLOW 14:23:01  exec  "npm test"                      [allow-dev]
ALLOW 14:23:03  read  ~/project/src/main.go            [default]
DENY  14:23:05  exec  "rm -rf /tmp/*"                  [block-destructive]
LOG   14:23:08  exec  "curl https://api.example.com"   [log-network]
ASK   14:23:10  exec  "kubectl apply -f prod.yaml"     [ask]
DENY  14:23:12  resp  read .env                        [block-credential-leak]
                  -> blocked: response contained AWS_SECRET_ACCESS_KEY

______________________________________________________________________

运作原理

模式匹配在微秒内处理95%以上的决策。可选 城墙验证 sidecar为不明确的命令添加了基于LLM的分类。所有决策都会进入哈希链审计跟踪。

Table of Contents

入门指南： 安装 · 快速启动 · 克劳德代码 · 开爪 · 包裹任何试剂

核心特点： 政策 · 审批流程 · 审计跟踪 · 实时仪表板 · Webhook通知

高级： LD_peload · MCP代理 · SIEM集成 · Webhook操作 · 预制API

参考： 演出 · 安全 · OWASP覆盖范围 · CLI参考 · 兼容性 · 从源头构建

______________________________________________________________________

克劳德代码

通过Claude Code的钩子系统进行本地集成。每个Bash命令、文件读取和写入在执行之前都要经过Rampart：

# Install background service
rampart serve install

# Wire up hooks
rampart setup claude-code

然后正常使用克劳德代码。Rampart在后台不可见地运行。

要删除：

rampart setup claude-code --remove

______________________________________________________________________

开爪

原生插件集成现在是当前OpenClaw构建的首选设置：

rampart setup openclaw

这保留了OpenClaw的原生审批UI，同时让Rampart决定哪些命令实际需要审批。

rampart serve 是这条道路的一部分。该插件调用本地Rampart服务进行策略评估、批准和审计流。

高管审批是如何运作的

Rampart离开全球 tools.exec.ask 着手 "off"，因此常规shell命令不会向您发送审批提示。当Rampart策略返回时 ask 对于特定的exec调用，插件仅重新发出该命令 ask: "always"，它通过OpenClaw的本地批准卡发送。

在实践中，这意味着：

• 安全命令正常运行，无提示
• 被拒绝的命令立即被阻止
• 仅与Rampart匹配的命令 ask 规则显示OpenClaw批准卡

插件保护什么

1.原生插件：评估中的工具调用 before_tool_call，立即阻止拒绝决策，并通过OpenClaw的本地审批UI路由选择性执行审批。

2.选择性本地批准：Rampart决定执行者何时需要批准，OpenClaw仅显示匹配命令的批准卡。

3.捆绑政策简介：安装插件安装程序使用的以OpenClaw为中心的策略配置文件。

传统兼容性路径

rampart setup openclaw --patch-tools 它仍然作为旧设置的兼容性选项存在，但不再是推荐的路径。它修改了OpenClaw dist文件，升级后必须重新应用。

跑 rampart doctor 随时验证当前的OpenClaw集成状态。

______________________________________________________________________

包裹任何试剂

对于没有钩子系统的代理， wrap 套 $SHELL 到政策检查垫片。与任何读到以下内容的代理一起工作 $SHELL （助手、OpenCode、继续等）：

rampart wrap -- aider
rampart wrap -- opencode
rampart wrap -- python my_agent.py

______________________________________________________________________

保护任何进程（LD_PRELOAD）

对于没有挂钩系统和没有挂钩系统的代理 $SHELL 支持， preload 在操作系统级别拦截exec系列系统调用：

rampart preload -- codex
rampart preload -- python my_agent.py
rampart preload -- node agent.js

# Monitor mode: log only, no blocking
rampart preload --mode monitor -- risky-tool

截距 execve, execvp, system(), popen()，以及 posix_spawn().被拒绝的来电返回 EPERM.

平台说明： 适用于Linux上的所有动态链接二进制文件。在macOS上使用Homebrew/nvm/pyenv二进制文件；被SIP阻止 /usr/bin/* （AI代理不住在那里）。

______________________________________________________________________

保护MCP服务器

在您的代理和任何MCP服务器之间插入代理：

rampart mcp -- npx @modelcontextprotocol/server-filesystem /path

在MCP配置中（Claude Desktop等）：

{
  "mcpServers": {
    "filesystem": {
      "command": "rampart",
      "args": ["mcp", "--", "npx", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

从MCP服务器的工具列表自动生成策略：

rampart mcp scan -- npx @modelcontextprotocol/server-filesystem .

______________________________________________________________________

制定政策

策略是YAML。全局匹配，文件更改时热重新加载。

rampart setup 创造 ~/.rampart/policies/custom.yaml 作为启动模板。它永远不会被升级覆盖。

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 对于子字符串匹配（不区分大小写）：

  - name: block-dangerous-substrings
    match:
      tool: ["exec"]
    rules:
      - action: deny
        when:
          command_contains: ["DROP TABLE", "rm -rf"]
        message: "Dangerous substring detected"

使用 action: ask 要触发审批提示：

  - name: ask-before-sudo
    match:
      agent: ["claude-code"]
      tool: ["exec"]
    rules:
      - action: ask
        when:
          command_contains: ["sudo "]
        message: "This command needs your approval"

常见情况下不需要进行YAML编辑。 当命令被阻止时，Rampart会建议运行什么：

# When "npm install lodash" gets denied:
#   💡 To allow this: rampart allow "npm install *"
rampart allow "npm install *"
#  Rule added; policy reloaded (12 rules active)

评价： 否认总是赢。优先级较低=首先评估。四项行动： deny, ask, watch, allow.

项目地方政策

掉落 .rampart/policy.yaml 在任何git仓库中，都有特定于项目的规则。提交它，这样每个团队成员都会自动得到相同的规则：

rampart init --project

安全说明： 集 RAMPART_NO_PROJECT_POLICY=1 在不受信任的存储库中工作时跳过项目策略加载。

内置配置文件

rampart init --profile standard    # allow-by-default, blocks dangerous commands
rampart init --profile paranoid    # deny-by-default, explicit allowlist
rampart init --profile ci          # strict; all approvals become hard denies
rampart init --profile yolo        # log-only, no blocking

______________________________________________________________________

审批流程

对于需要人工决定的命令：

policies:
  - name: production-deploys
    match:
      tool: ["exec"]
    rules:
      - action: ask
        when:
          command_matches: ["kubectl apply *", "terraform apply *"]
        message: "Production deployment requires approval"

如何获得批准取决于您的环境：

rampart pending          # What's waiting
rampart approve abc123   # Let it through
rampart deny abc123      # Block it

默认情况下，待审批将在2分钟后过期(--approval-timeout 改变）。

______________________________________________________________________

审计跟踪

每个工具调用都记录到哈希链JSONL中。篡改任何记录，链条就会断裂：

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

Web仪表板位于 http://localhost:9090/dashboard/ 当 rampart serve 正在运行。三个选项卡：实时流、历史和策略REPL，用于在命令运行前对其进行测试。

______________________________________________________________________

Webhook通知

notify:
  url: "https://discord.com/api/webhooks/your/webhook"
  on: ["deny"]

policies:
  # ...

适用于Discord webhooks、Slack传入webhooks或任何HTTP端点。

______________________________________________________________________

SIEM集成

# RFC 5424 syslog (Wazuh, QRadar, ArcSight, Sentinel)
rampart serve --syslog localhost:514

# Common Event Format (Splunk, QRadar)
rampart serve --syslog localhost:514 --cef

______________________________________________________________________

Webhook操作

将允许/拒绝决策委托给外部服务：

rules:
  - action: webhook
    when:
      command_matches: ['*production*']
    webhook:
      url: 'http://localhost:8090/verify'
      timeout: 5s
      fail_open: true

看 城墙验证，一个用于模糊命令的可选LLM sidecar（~0.0001美元/调用）。

______________________________________________________________________

预制API

检查在不执行调用的情况下是否允许调用：

curl -s localhost:9090/v1/preflight/exec \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent":"a","session":"s","params":{"command":"rm -rf /"}}'
# → {"allowed":false,"decision":"deny","matched_policies":["block-destructive"]}

______________________________________________________________________

演出

以个位数微秒为单位的策略评估：

______________________________________________________________________

安全建议

自我修改保护。 代理无法通过运行以下命令绕过自己的策略 rampart allow 或 rampart block这些命令在由代理执行时被阻止。政策修改必须由人来完成。

不要以root身份运行你的AI代理。 根访问会破坏用户分离。以无特权用户身份运行代理框架。

跑 rampart serve 作为独立用户 在生产环境中，防止代理读取审计日志或修改策略。

有关威胁模型的完整讨论，请参阅 docs/THREAT-MODEL.md.

______________________________________________________________________

OWASP覆盖范围

Rampart地图 代理应用程序的OWASP前10名:

完整的OWASP映射→

______________________________________________________________________

CLI参考

# Setup
rampart quickstart                           # Auto-detect, install, configure, health check
rampart setup claude-code                    # Claude Code native hooks
rampart setup cline                          # Cline native hooks
rampart setup openclaw                       # OpenClaw native plugin integration
rampart setup codex                          # Codex CLI shell wrapper (Linux, macOS)
rampart setup  --remove               # Clean uninstall

# Run
rampart wrap --                     # Wrap any agent via $SHELL
rampart preload --                  # LD_PRELOAD syscall interception
rampart mcp --           # Proxy MCP with policy enforcement
rampart mcp scan --                  # Auto-generate policies from MCP tools

# Serve
rampart serve [--port 9090]                  # Start approval + dashboard server
rampart serve install                        # Install as a boot service (systemd/launchd)
rampart serve --background                   # Start in background
rampart serve stop                           # Stop background server

# Diagnose
rampart doctor                               # Health check (colored output)
rampart doctor --fix                         # Auto-apply missing patches
rampart doctor --json                        # Machine-readable (exit 1 on issues)
rampart status                               # Quick dashboard: what's protected
rampart watch                                # Live TUI event stream

# Policy
rampart init [--profile standard|paranoid|ci|yolo]   # Initialize global policy
rampart init --project                                # Create .rampart/policy.yaml
rampart policy lint [file]                            # Lint policy file
rampart policy explain "git status"                   # Trace evaluation
rampart policy list                                   # Browse community registry
rampart policy fetch                            # Install community policy

# Rules (no YAML editing required)
rampart allow "npm install *"               # Allow a command pattern
rampart block "curl * | bash"               # Block a pattern
rampart rules                               # List custom rules
rampart rules remove 3                      # Remove by number
rampart allow "docker *" --for 1h          # Temporary allow

# Test
rampart test "rm -rf /"                     # Dry-run against policies
rampart test --json                         # Structured output for CI

# Approvals
rampart pending                             # What's waiting
rampart approve                         # Allow
rampart deny                            # Deny

# Audit
rampart audit tail [--follow]
rampart audit verify
rampart audit stats
rampart log --deny                          # Recent denies

# Upgrade
rampart upgrade                             # New binary + refresh policies
rampart upgrade --no-binary                 # Refresh policies only

______________________________________________________________________

兼容性

______________________________________________________________________

从源头构建

git clone https://github.com/peg/rampart.git
cd rampart
go build -o rampart ./cmd/rampart
go test ./...

需要Go 1.24+。

______________________________________________________________________

从v0.9.8升级？

v0.9.9包含三个突破性的更改：

action: require_approval 现在是一个严重的错误。 从以下位置更新您的政策：

- action: require_approval

致：

- action: ask
  ask:
    audit: true

跑 rampart policy lint 查找所有事件。

--serve-token 旗帜被移除。 使用 RAMPART_TOKEN 改为环境变量：

# Before (v0.9.8 and earlier)
rampart serve --serve-token mysecrettoken

# After (v0.9.9+)
RAMPART_TOKEN=mysecrettoken rampart serve

GET /v1/policy 端点已删除。 使用 GET /v1/status 用于服务器健康或 GET /v1/policies 列出活动策略。

______________________________________________________________________

配套工具：Snare

坡道块。 陷阱 捕捉。

Snare在人工智能代理的环境中植入金丝雀代币——API密钥、云证书、文件路径。如果你的代理或破坏它的东西使用了这些令牌，你会收到即时警报。

Rampart+Snare=预防性+检测性控制。 两者都用。

______________________________________________________________________

贡献

欢迎捐款。对于小修复之外的任何问题，请先打开一个问题。所有工作都要经过 staging 支。PR至 main 需要一次批准审查。

______________________________________________________________________

许可证

Apache 2.0