Claude Code's --dangerously-skip-permissions mode, and similar autonomous modes in Cline and Codex, give agents unrestricted shell access. Your agent can read your SSH keys, exfiltrate your .env, or rm -rf / with no guardrails.
Rampart evaluates the actions an agent exposes through a supported hook, plugin, proxy, or process boundary. Matching shell commands, file operations, fetches, and other tool calls can be blocked before the host executes them. Rampart does not see arbitrary syscalls or network traffic inside a process you already allowed; read the threat model for the boundary.
# 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.25.12+)
go install github.com/peg/rampart/cmd/rampart@latestWindows (PowerShell):
irm https://rampart.sh/install.ps1 | iexUpgrading on Windows? Rerun the PowerShell installer above; binary self-upgrade is intentionally disabled on Windows. The installer also repairs the affected legacy
~\.rampartACL found on v1.2.x installations.
To detect and protect every installed supported agent with managed defaults:
rampart protectDetect supported installed agents, install their native boundaries, and run safe behavioral verification—no policy file to read or write:
rampart protectYou can also select one integration explicitly. For OpenClaw, this installs the
native plugin and local service, activates fail-closed Guard defaults, restarts
the gateway, and runs safe canaries through the live before_tool_call path.
For native-hook agents, Rampart verifies the installed configuration, directly
exercises the adapter, and checks the live local policy service. It never asks a
model to execute a verification canary.
Recheck the boundary at any time:
rampart verify openclawDirect setup for supported integration paths remains available:
# Claude Code
rampart setup claude-code
# Cline
rampart setup cline
# Codex CLI, IDE extension, and desktop app
rampart setup codex
rampart verify codex
# Antigravity CLI (host-verified) and IDE (shared contract)
rampart setup antigravity
rampart verify antigravity
# GitHub Copilot CLI adapter and VS Code Preview hooks
rampart setup copilot
rampart verify copilot
# Any other agent (wraps $SHELL)
rampart wrap -- your-agentExperimental integrations are explicit opt-ins and stay outside bare
rampart protect auto-detection:
# Hermes Agent (experimental; native approval/resume pending)
rampart setup hermes
# Gemini CLI (experimental enterprise/API-key path; no authenticated host proof)
rampart setup gemini
rampart verify geminiCheck the broader installation state:
rampart doctorCurrent integration coverage, live-host evidence, and known gaps are published in the support matrix and security-assurance guide.
Then watch your agent in real time:
rampart watchIf you do not want to keep exporting environment variables, Rampart also supports
~/.rampart/config.yaml for local defaults:
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 split control-service setups| Setting | Use it for | Notes |
|---|---|---|
url |
Primary Rampart base URL | Canonical setting for hook/watch/plugin/service-backed flows |
serve_url |
Backwards-compatible alias for url |
Kept for compatibility; prefer url in new configs |
api |
Optional API base URL override for approval/control commands | Advanced only; usually unnecessary unless you split the API away from the main serve endpoint |
Notes:
urlis the main knob; use this unless you have a specific reason not to.apiis not the normal setting forrampart serve; it is for advanced split control-service setups.- Client-side
--apiflags expect an API base URL (http://127.0.0.1:9091), while server--apiflags refer to an API listen address (127.0.0.1:9091).
Resolution order is: flag → environment → config file → auto-discovered state → default.
Once an integration is configured, each tool call that integration exposes to Rampart goes through the policy engine:
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
Local pattern matching is benchmarked at microsecond scale. The optional rampart-verify sidecar adds LLM-based classification for selected ambiguous commands. Decisions observed at the configured Rampart boundary are written to a hash-chained audit trail.
| Agent | Setup command | Integration |
|---|---|---|
| Claude Code | rampart setup claude-code |
Native pre/post tool hooks via ~/.claude/settings.json |
| OpenClaw | rampart protect openclaw |
Zero-config native guard + active verification |
| Hermes Agent | rampart setup hermes |
Experimental pre_tool_call user plugin |
| Cline | rampart setup cline |
Platform-native editor/CLI hook files |
| Codex | rampart setup codex |
Native user-level lifecycle hooks for CLI, IDE, and desktop |
| Gemini CLI | rampart setup gemini |
Experimental enterprise/API-key BeforeTool/AfterTool hooks |
| Antigravity | rampart setup antigravity |
Shared CLI/IDE PreToolUse plugin; CLI 1.1.7 host-verified, IDE contract-tested |
| GitHub Copilot | rampart setup copilot |
Shared hooks; CLI package startup + adapter tested, authenticated ingestion pending; VS Code Preview contract-tested |
| Any agent | rampart wrap -- <agent> |
Shell wrapping via $SHELL |
| MCP servers | rampart mcp -- <server> |
MCP protocol proxy |
| Compatible native processes | rampart preload -- <cmd> |
Optional libc exec/spawn interposition (Linux/macOS) |
Table of Contents
Getting Started: Install · Quick start · Claude Code · OpenClaw · Antigravity · Hermes Agent · Wrap any agent
Core Features: Policies · Approval flow · Audit trail · Live dashboard · Webhook notifications
Advanced: LD_PRELOAD · MCP proxy · SIEM integration · Webhook actions · Preflight API
Reference: Performance · Security · OWASP coverage · CLI reference · Compatibility · Building from source
Native integration through Claude Code's hook system. Rampart classifies the
current hook-visible shell, file, network, MCP, delegation, transfer, and
scheduling tools before execution. In enforce mode, a future unknown
PreToolUse tool fails closed until Rampart is updated. Successful tool responses are scanned and
policy-blocked string content is replaced before the next model turn:
# Optional: dashboard and service-backed/headless approval features
rampart serve install
# Wire up hooks
rampart setup claude-codeThen use Claude Code normally. Rampart runs invisibly in the background.
To remove:
rampart setup claude-code --removeOpenClaw uses Rampart's strongest native-plugin zero-configuration path:
rampart protect openclawThe command installs and enables the native plugin, restores Rampart's managed OpenClaw and Guard policies, starts the background service, enables fail-closed degraded behavior, restarts the gateway, and actively verifies the result. Existing unrelated OpenClaw settings and custom Rampart policies are preserved.
The managed Guard defaults focus on consequences:
- routine local work continues without prompts
- destructive commands and credential access are denied
- publishing, deployment, privileged service changes, and cross-conversation messages require approval
- read-only message actions and replies to the originating conversation remain available
- with the managed
failOpen: falsesetting, the plugin returns a deny for tool requests when the policy service is unavailable
rampart verify openclaw uses fixed safe canaries. It traverses the running
plugin's normalization, message classification, policy request, degraded-mode,
and decision-mapping code without executing a command, reading a file, sending a
message, contacting an external host, or adding verification noise to the audit
log. Verification requires Rampart's local admin token and rejects incomplete or
stale plugin self-reports.
rampart serve is part of this path. The plugin calls the local Rampart service for policy evaluation, approvals, and audit flow.
Rampart leaves global tools.exec.ask set to "off", so routine shell commands do not spam you with approval prompts. When a Rampart policy returns ask, the plugin returns OpenClaw's native requireApproval result for that specific tool call.
In practice, that means:
- safe commands run normally, with no prompt
- denied commands are blocked immediately
- only commands that match a Rampart
askrule show an OpenClaw approval card
1. Native plugin: evaluates tool calls in before_tool_call, blocks deny decisions immediately, and routes selective approvals through OpenClaw's native approval UI.
2. Selective native approvals: Rampart decides when an action should require approval, and OpenClaw shows the approval card only for those matched calls.
3. Managed Guard defaults: layers consequence-oriented safeguards over the OpenClaw profile without requiring YAML configuration.
For advanced/manual integration work, rampart setup openclaw remains available.
rampart setup openclaw --patch-tools still exists as a compatibility option for older setups, but it is no longer the recommended path. It modifies OpenClaw dist files and must be re-applied after upgrades.
Run rampart verify openclaw to test behavior; use rampart doctor for a wider configuration health report.
Rampart installs one global plugin shared by Antigravity CLI and the Antigravity IDE. The CLI 1.1.7 path has completed host proof; the IDE shares the reviewed contract, but a separate physical IDE host run remains pending:
rampart setup antigravity
rampart verify antigravityThe plugin evaluates every documented PreToolUse call before execution.
Approval rules return Antigravity's native force_ask, so a cached "Always
Allow" permission cannot bypass a Rampart prompt. Unknown future tool names
deny until Rampart understands their policy surface.
Antigravity's current PostToolUse payload does not include the completed tool
call or its result. This integration therefore protects actions before they
run, but does not claim post-result secret scanning. Allowed actions still run
inside Antigravity's own permission and sandbox model.
Hermes Agent integration uses a user plugin installed into ~/.hermes/plugins/rampart:
rampart setup hermes
hermes plugins enable rampartThe plugin registers a Hermes pre_tool_call hook and sends sanitized tool metadata to Rampart before execution. It defaults to /v1/preflight/{tool} with execution intent, so one-time grants and call counters are enforced without creating hidden approvals that Hermes cannot resume. ask decisions block with an approval-required message until Hermes has a first-class plugin approval/resume flow. Service outages deny every Hermes tool by default.
For agents without a hook system, wrap sets $SHELL to a policy-checking shim. Works with any agent that reads $SHELL (Aider, OpenCode, Continue, and more):
rampart wrap -- aider
rampart wrap -- opencode
rampart wrap -- python my_agent.pyFor agents with no hook system and no $SHELL support, preload can interpose
supported libc exec/spawn calls in a compatible dynamically linked process:
Source build required: current GitHub release archives and Homebrew packages ship the CLI but not
librampart. From the matching Rampart source checkout, runmake -C preload installfirst.
rampart preload -- your-agent
rampart preload -- python my_agent.py
rampart preload -- node agent.js
# Monitor mode: log only, no blocking
rampart preload --mode monitor -- risky-toolIntercepts execve, execvp, system(), popen(), posix_spawn(), and posix_spawnp(). Denied calls return EPERM.
Platform notes: Preload mode covers supported exec-family calls made through the dynamic loader on Linux and in non-SIP-protected macOS processes. Static or setuid binaries, direct syscalls, and macOS SIP-protected processes can bypass this boundary; see the threat model before relying on preload mode.
Drop-in proxy between your agent and any MCP server:
rampart mcp -- npx @modelcontextprotocol/server-filesystem /pathIn your MCP config (Claude Desktop, etc.):
{
"mcpServers": {
"filesystem": {
"command": "rampart",
"args": ["mcp", "--", "npx", "@modelcontextprotocol/server-filesystem", "."]
}
}
}Auto-generate policies from an MCP server's tool list:
rampart mcp scan -- npx @modelcontextprotocol/server-filesystem .Policies are YAML. Glob matching, hot-reload on file change.
rampart setupcreates~/.rampart/policies/custom.yamlas a starter template. It's never overwritten by upgrades.
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"Use command_contains for substring matching. Restrictive actions (deny and
approval gates) match case-insensitively; execution-granting actions preserve
argument casing so an allow cannot widen a case-sensitive URL path or Git ref:
- name: block-dangerous-substrings
match:
tool: ["exec"]
rules:
- action: deny
when:
command_contains: ["DROP TABLE", "rm -rf"]
message: "Dangerous substring detected"Use action: ask to trigger an approval prompt:
- name: ask-before-sudo
match:
agent: ["claude-code"]
tool: ["exec"]
rules:
- action: ask
when:
command_contains: ["sudo "]
message: "This command needs your approval"No YAML editing required for common cases. When a command is blocked, Rampart suggests what to run:
# When "npm install lodash" gets denied:
# 💡 To allow this: rampart allow "npm install *"
rampart allow "npm install *"
# Rule added; policy reloaded (12 rules active)Evaluation: Deny always wins. Lower priority number = evaluated first. Four actions: deny, ask, watch, allow.
Drop .rampart/policy.yaml in any git repo for project-specific rules. Commit it so every team member gets the same rules automatically:
rampart init --projectSecurity note: Set RAMPART_NO_PROJECT_POLICY=1 to skip project policy loading when working in untrusted repos.
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 blockingFor commands that need a human to decide:
policies:
- name: production-deploys
match:
tool: ["exec"]
rules:
- action: ask
when:
command_matches: ["kubectl apply *", "terraform apply *"]
message: "Production deployment requires approval"How approval reaches you depends on your environment:
| Environment | How you approve |
|---|---|
| Claude Code | Native approval prompt in the terminal |
| OpenClaw | Native approval card in your connected chat surface |
| Any | rampart approve <id> via CLI, dashboard, or signed URL |
rampart pending # What's waiting
rampart approve abc123 # Let it through
rampart deny abc123 # Block itPending approvals expire after 2 minutes by default (--approval-timeout to change).
Each tool decision Rampart receives is logged to hash-chained JSONL. Editing, inserting, or deleting an individual record breaks chain verification:
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 rangerampart watch # TUI: live colored event streamWeb dashboard at http://localhost:9090/dashboard/ when rampart serve is running. Three tabs: live stream, history, and a policy REPL to test commands before they run.
notify:
url: "https://discord.com/api/webhooks/your/webhook"
on: ["deny"]
policies:
# ...Works with Discord webhooks, Slack incoming webhooks, or any HTTP endpoint.
# RFC 5424 syslog (Wazuh, QRadar, ArcSight, Sentinel)
rampart serve --syslog localhost:514
# Common Event Format (Splunk, QRadar)
rampart serve --syslog localhost:514 --cefDelegate allow/deny decisions to an external service:
rules:
- action: webhook
when:
command_matches: ['*production*']
webhook:
url: 'http://localhost:8090/verify'
timeout: 5s
fail_open: trueSee rampart-verify, an optional LLM sidecar for ambiguous commands (~$0.0001/call).
Check if a call would be allowed without executing it:
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"]}The in-process policy hot path is benchmarked at microsecond scale. Hook process startup, policy size, machine speed, and audit I/O affect end-to-end latency. Reproduce the engine-only benchmark on your own hardware with:
go test ./internal/engine -run '^$' -bench '^BenchmarkEvaluate$' -benchmem -count=3Self-modification protection. The standard profile blocks recognized agent-issued Rampart mutation commands and writes to known Rampart paths. This is defense in depth, not an OS isolation boundary: keep policy files and admin credentials outside the agent account for stronger protection.
Don't run your AI agent as root. Root access defeats user separation. Run agent frameworks as an unprivileged user.
Run rampart serve as a separate user in production to prevent agents from reading audit logs or modifying policies.
For a full discussion of the threat model, see docs/THREAT-MODEL.md.
Rampart maps to the OWASP Top 10 for Agentic Applications:
| Risk | Coverage |
|---|---|
| ASI02: Tool Misuse | Partial: supported host-exposed tool calls are policy evaluated |
| ASI05: Unexpected Code Execution | Partial: command patterns and optional semantic verification; allowed interpreters remain a boundary |
| ASI08: Data Exfiltration | Partial: known domains, file paths, and credential patterns |
| ASI09: Human-Agent Trust | Partial: ask where the integration has an approval path |
| ASI10: Rogue Agents | Partial: observed actions are audited; Rampart is not process isolation |
| ASI01: Goal Hijack | Partial: policy limits blast radius even if goals are altered |
| ASI06: Context Poisoning | Partial: response scanning blocks credentials from context window |
| ASI07: Inter-Agent Communication | ❌ Not addressed |
# Setup
rampart protect # Detect, configure, and verify supported installed agents
rampart protect openclaw # Zero-config guard + live behavioral verification
rampart verify openclaw # Re-run safe canaries through the live plugin
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 # Advanced/manual OpenClaw integration management
rampart setup codex # Codex native lifecycle hooks
rampart setup antigravity # CLI host-verified; IDE shares the tested plugin contract
rampart setup copilot # Copilot CLI adapter + VS Code Preview hooks
rampart verify codex # Verify hook install + native deny response
rampart verify antigravity # Verify plugin install + native deny response
rampart verify copilot # Verify dual-host deny response + audit
# Experimental, explicit opt-in integrations
rampart setup gemini # Enterprise/API-key Gemini CLI; no authenticated host proof
rampart verify gemini # Verify generated hooks + adapter response
rampart setup hermes # Hermes plugin; native approval/resume pending
rampart setup <agent> --remove # Clean uninstall
# Run
rampart wrap -- <command> # Wrap any agent via $SHELL
rampart preload -- <command> # Optional compatible libc exec/spawn interposition
rampart mcp -- <mcp-server-command> # Proxy MCP with policy enforcement
rampart mcp scan -- <server> # 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 <name> # 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 <id> # Allow
rampart deny <id> # 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 protect # Refresh managed integrations + verify
rampart upgrade --no-binary # Refresh policies only| Agent | Method | Platforms |
|---|---|---|
| Claude Code | rampart setup claude-code |
Linux, macOS, Windows |
| OpenClaw | rampart protect openclaw |
Linux, macOS |
| Cline | rampart setup cline |
Linux, macOS, Windows* |
| Codex CLI, IDE, desktop | rampart setup codex |
Linux, macOS, Windows |
| Gemini CLI (enterprise/API key) | rampart setup gemini |
Experimental; Linux, macOS |
| Antigravity CLI / IDE | rampart setup antigravity |
Linux, macOS, Windows; CLI 1.1.7 host proof, IDE contract-tested |
| GitHub Copilot CLI / VS Code | rampart setup copilot |
Linux, macOS, Windows; CLI adapter-tested, VS Code Preview contract-tested |
| Claude Desktop MCP servers | rampart mcp |
Linux, macOS, Windows |
| Aider, OpenCode, Continue | rampart wrap |
Linux, macOS |
| Python agents | rampart preload or HTTP API |
Linux, macOS |
| Node.js agents | rampart preload or HTTP API |
Linux, macOS |
| Command-launched MCP servers | rampart mcp |
Linux, macOS, Windows |
| Supported dynamically linked processes | rampart preload |
Linux, macOS |
| Custom agents | HTTP API at localhost:9090 |
Linux, macOS, Windows |
* Cline's Windows .ps1 contract is source-reviewed and cross-build tested;
physical Windows host E2E remains pending. Legacy Cline CLI --yolo disables
runtime hooks. The current CLI also continues after hook infrastructure failure
and treats post-tool hooks as asynchronous audit only. See the
Cline integration guide.
git clone https://github.com/peg/rampart.git
cd rampart
go build -o rampart ./cmd/rampart
go test ./...Requires Go 1.25.12+.
v0.9.9 contains three breaking changes:
action: require_approval is now a hard error.
Update your policies from:
- action: require_approvalto:
- action: ask
ask:
audit: trueRun rampart policy lint to find all occurrences.
--serve-token flag removed.
Use the RAMPART_TOKEN environment variable instead:
# Before (v0.9.8 and earlier)
rampart serve --serve-token mysecrettoken
# After (v0.9.9+)
RAMPART_TOKEN=mysecrettoken rampart serveGET /v1/policy endpoint removed.
Use GET /v1/status for server health or GET /v1/policies to list active policies.
Rampart blocks. Snare catches.
Snare plants canary tokens in your AI agent's environment - API keys, cloud credentials, file paths. If your agent, or something that compromised it, uses those tokens, you get an instant alert.
Rampart + Snare = preventive + detective controls. Use both.
Contributions welcome. Open an issue first for anything beyond small fixes. All work goes through the staging branch. PRs to main require one approving review.