@clawdreyhepburn/carapace 0.1.0 → 0.2.1

package/README.md

@@ -10,6 +10,7 @@
     <a href="#installation">Installation</a> •
     <a href="#quick-start">Quick Start</a> •
     <a href="#how-it-works">How It Works</a> •
+    <a href="docs/RECOMMENDED-POLICIES.md">Recommended Policies</a> •
     <a href="#gui">Control GUI</a> •
     <a href="#security">Security</a> •
     <a href="#attribution">Attribution</a>
@@ -18,11 +19,11 @@
 
 ---
 
-Carapace is an [OpenClaw](https://github.com/openclaw/openclaw) plugin that sits between your AI agent and its MCP tools. It aggregates multiple MCP servers, discovers their tools, and enforces [Cedar](https://www.cedarpolicy.com/) authorization policies on every tool call — with a local GUI where humans can see and control everything.
+Carapace is an [OpenClaw](https://github.com/openclaw/openclaw) plugin that puts Cedar authorization between your AI agent and everything it can do — MCP tools, shell commands, and outbound API calls. It aggregates multiple MCP servers, discovers their tools, gates shell execution by binary name, controls outbound HTTP by domain, and enforces [Cedar](https://www.cedarpolicy.com/) policies on every operation — with a local GUI where humans can see and control everything.
 
-**The problem:** MCP gives agents access to tools. But who decides *which* tools an agent can use? Today the answer is "whatever's in the config file" — a static, all-or-nothing list with no audit trail, no formal guarantees, and no human oversight.
+**The problem:** Agents have access to tools, a shell, and the network. But who decides what they can actually *do*? Today the answer is "whatever's in the config file" — a static, all-or-nothing list with no audit trail, no formal guarantees, and no human oversight.
 
-**The solution:** Carapace puts Cedar between your agent and its tools. Cedar policies are declarative, auditable, and formally verifiable. The local GUI makes it accessible to humans who don't want to write policy files by hand. Toggle a switch, and the Cedar policy updates. It's that simple.
+**The solution:** Carapace puts Cedar between your agent and its capabilities. Cedar policies are declarative, auditable, and formally verifiable. The local GUI makes it accessible to humans who don't want to write policy files by hand. Toggle a switch, and the Cedar policy updates. It's that simple.
 
 ## Design Philosophy
 
@@ -42,12 +43,17 @@ The progression:
 |  OpenClaw   |---->|                            |---->|  (filesystem)   |
 |  Agent      |     |  +----------------------+  |     +-----------------+
 |             |     |  |   Cedarling WASM      |  |     |  MCP Server B   |
-|             |     |  |   (Cedar 4.4.2)       |  |---->|  (GitHub)       |
+|  mcp_call   |---->|  |   (Cedar 4.4.2)       |  |---->|  (GitHub)       |
 |             |     |  +----------------------+  |     +-----------------+
-|             |     |  +----------------------+  |     |  MCP Server C   |
-|             |     |  |  Local Control GUI    |  |---->|  (database)     |
+| carapace    |     |                            |     +-----------------+
+|   _exec   --|---->|  Cedar: exec_command       |---->|  Shell (local)  |
+|             |     |                            |     +-----------------+
+| carapace    |     |                            |     +-----------------+
+|   _fetch  --|---->|  Cedar: call_api           |---->|  HTTP (remote)  |
 |             |     |  +----------------------+  |     +-----------------+
-+-------------+     +--------------+--------------+
+|             |     |  |  Local Control GUI    |  |
++-------------+     |  +----------------------+  |
+                    +--------------+--------------+
                                    |
                             +------+------+
                             |    Human    |
@@ -55,7 +61,7 @@ The progression:
                             +-------------+
 ```
 
-**Every tool call flows through Cedar evaluation.** If the policy says deny, the call never reaches the upstream MCP server. The agent gets a clear denial message with the reason.
+**Every operation flows through Cedar evaluation.** MCP tool calls, shell commands, and outbound API requests are all authorized by Cedar policies before execution. If the policy says deny, the operation never happens. The agent gets a clear denial message with the reason.
 
 ## Screenshots
 
@@ -149,18 +155,36 @@ In your OpenClaw config, add the servers you want Carapace to manage:
 }
 ```
 
-### 2. Open the control GUI
+### 2. Close the bypass gap
+
+By default, agents can still use OpenClaw's built-in `exec` and `web_fetch` tools, which bypass Cedar entirely. Run setup to close this:
+
+```bash
+openclaw carapace setup
+```
+
+This adds `exec`, `web_fetch`, and `web_search` to `tools.deny` in your OpenClaw config, forcing agents to use `carapace_exec` and `carapace_fetch` instead — which go through Cedar.
+
+You can check for bypasses anytime:
+
+```bash
+openclaw carapace check
+```
+
+> ⚠️ **Without this step, Carapace policies are advisory, not enforced.** The agent can simply choose to use the built-in tools instead. Always run `carapace setup` for real security.
+
+### 3. Open the control GUI
 
 Navigate to [http://localhost:19820](http://localhost:19820) in your browser. You'll see all discovered tools from all connected servers.
 
-### 3. Enable tools
+### 4. Enable tools
 
 Toggle individual tools on/off. Each toggle writes a Cedar policy:
 
 - **Toggle ON** → creates a `permit` policy for that tool
 - **Toggle OFF** → creates a `forbid` policy for that tool
 
-### 4. Create custom policies
+### 5. Create custom policies
 
 Click **"+ New Policy"** to open the visual builder, or edit policies directly in the Policies tab. Examples:
 
@@ -179,6 +203,32 @@ forbid(
   resource == Jans::Tool::"filesystem/write_file"
 );
 
+// Allow git and npm commands, block everything else
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"git"
+);
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"npm"
+);
+
+// Allow API calls to GitHub, block all other domains
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"api.github.com"
+);
+
+// Block a specific domain
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"evil.example.com"
+);
+
 // Allow everything (use with caution)
 permit(
   principal is Jans::Workload,
@@ -187,7 +237,9 @@ permit(
 );
 ```
 
-### 5. Verify policies
+> 📖 **Want more?** See [Recommended Policies](docs/RECOMMENDED-POLICIES.md) for real-world policies covering destructive commands, credential theft, data exfiltration, email deletion, and complete starter configurations.
+
+### 6. Verify policies
 
 Click **⚡ Verify** to validate that all policies are syntactically correct and consistent.
 
@@ -198,10 +250,21 @@ Click **⚡ Verify** to validate that all policies are syntactically correct and
 Carapace uses [Cedarling](https://github.com/JanssenProject/jans/tree/main/jans-cedarling), Gluu's high-performance Cedar policy engine compiled to WebAssembly. This means:
 
 - **Real Cedar evaluation** — not a simplified subset. Full Cedar 4.4.2 with the official Rust SDK.
+- **Three resource types** — `Tool` (MCP tools), `Shell` (commands by binary name), `API` (outbound HTTP by domain). All go through the same Cedar engine.
 - **Forbid always wins** — if any policy says `forbid`, the request is denied regardless of any `permit` policies. This is core Cedar semantics and prevents privilege escalation.
-- **Allow-all by default** — installing Carapace doesn't break anything. All tools work until you add `forbid` policies. Switch to `deny-all` when you're ready for least-privilege.
+- **Allow-all by default** — installing Carapace doesn't break anything. All operations work until you add `forbid` policies. Switch to `deny-all` when you're ready for least-privilege.
 - **Sub-millisecond evaluation** — WASM runs at near-native speed. Typical authorization decisions take <6ms.
 
+### Resource Types
+
+| Type | Cedar Entity | Action | Gates | Example |
+|------|-------------|--------|-------|---------|
+| MCP Tool | `Jans::Tool` | `call_tool` | Upstream MCP server calls | `Tool::"filesystem/write_file"` |
+| Shell | `Jans::Shell` | `exec_command` | Local command execution | `Shell::"rm"`, `Shell::"git"` |
+| API | `Jans::API` | `call_api` | Outbound HTTP requests | `API::"api.github.com"` |
+
+Shell commands are matched by **binary name** (the first token of the command). API calls are matched by **domain name**. This keeps policies readable and auditable — you can see at a glance "this agent can run `git` and `npm` but not `rm` or `curl`."
+
 ### Policy Store Format
 
 Policies are stored as individual `.cedar` files in the policy directory (default: `~/.openclaw/mcp-policies/`). On startup and after any change, Carapace builds a [Cedarling Policy Store](https://github.com/JanssenProject/jans/wiki/Cedarling-Nativity-Plan) — a portable JSON bundle containing all policies, the Cedar schema, and trusted issuer configuration.
@@ -227,7 +290,7 @@ The GUI communicates with Carapace through a local REST API:
 |----------|--------|-------------|
 | `/api/status` | GET | Server status, all tools, all policies |
 | `/api/tools` | GET | List tools (optional `?server=` filter) |
-| `/api/toggle` | POST | Enable/disable a tool `{"tool": "...", "enabled": true}` |
+| `/api/toggle` | POST | Enable/disable a resource `{"tool": "...", "enabled": true, "type": "tool\|shell\|api"}` |
 | `/api/policy` | POST | Create/update a policy `{"id": "...", "raw": "..."}` |
 | `/api/policy` | DELETE | Delete a policy `{"id": "..."}` |
 | `/api/policies` | GET | List all policies |
@@ -250,7 +313,8 @@ Carapace is designed to protect against:
 ### What Carapace Does NOT Protect Against
 
 - **Malicious MCP servers** — Carapace trusts the upstream MCP servers to behave as described. It does not sandbox server execution.
-- **Tool argument validation** — Carapace authorizes *which* tool can be called, not *what arguments* are passed. (Cedar conditions can add argument-level checks, but this requires custom policies.)
+- **Argument-level validation** — Carapace authorizes *which* operation can be performed (which tool, which binary, which domain), not the specific arguments. Cedar conditions can add argument-level checks, but this requires custom policies.
+- **Shell argument injection** — Carapace gates by binary name (`git`, `npm`), not by the full command line. An agent permitted to run `git` could run `git push --force`. Use Cedar `when` conditions on `context.args` for finer control.
 - **Network-level attacks** — The GUI runs on localhost without authentication. See [GUI Security](#gui-security) below.
 
 ### GUI Security

package/docs/RECOMMENDED-POLICIES.md

@@ -0,0 +1,519 @@
+# Recommended Policies
+
+Real-world Cedar policies for common "oh no" scenarios. These are starting points — adapt them to your agent's actual needs.
+
+## Before You Write Policies: Close the Bypass Gap
+
+**This is the most important step.** If you skip it, every policy in this document is advisory — the agent can just use OpenClaw's built-in `exec` tool instead of `carapace_exec` and bypass Cedar entirely.
+
+```bash
+openclaw carapace setup
+openclaw gateway restart
+```
+
+This denies the built-in `exec`, `web_fetch`, and `web_search` tools, forcing agents to use the Cedar-gated `carapace_exec` and `carapace_fetch` instead. Verify with:
+
+```bash
+openclaw carapace check
+# Should show: ✅ No bypass vulnerabilities found.
+```
+
+**Without this, an agent can:**
+- Call `exec` directly with `rm -rf /` — Carapace never sees it
+- Call `web_fetch` to exfiltrate data — Carapace never sees it
+- Call `exec` with `curl` to hit any API — Carapace never sees it
+
+Run setup first. Then write policies.
+
+## The Basics
+
+Carapace defaults to **allow-all** so installing it never breaks anything. The recommended path:
+
+1. **Run `carapace setup`** → close the bypass gap
+2. **Add forbids** → block the scary stuff (this doc)
+3. **Switch to deny-all** → explicitly permit only what's needed (advanced)
+
+Most people should start with step 2 and stay there until they're comfortable.
+
+---
+
+## Shell Policies
+
+### Block destructive file operations
+
+The classics. An agent with shell access can `rm -rf /` before you blink.
+
+```cedar
+// Block rm entirely — use trash instead
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"rm"
+);
+
+// Block destructive disk tools
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"rmdir"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"mkfs"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"dd"
+);
+
+// Block format/partition tools
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"diskutil"
+);
+```
+
+**Why:** An agent that can delete files can delete *all* files. `rm` is the single most dangerous command you can give an agent. Use `trash` (recoverable) instead and permit that.
+
+### Block credential and secret access
+
+Agents don't need to read your SSH keys or browser passwords.
+
+```cedar
+// Block direct credential access tools
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"security"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"ssh-keygen"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"gpg"
+);
+
+// Block password managers
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"op"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"pass"
+);
+```
+
+**Why:** `security` (macOS Keychain CLI) can dump stored passwords. `ssh-keygen` can overwrite your keys. An agent doesn't need either of these to do useful work.
+
+### Block system administration
+
+Unless your agent is explicitly managing infrastructure, it shouldn't touch system config.
+
+```cedar
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"sudo"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"su"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"chmod"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"chown"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"launchctl"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"systemctl"
+);
+```
+
+**Why:** Privilege escalation is the nightmare scenario. If your agent can `sudo`, it can do *anything*. Even `chmod` can weaken file permissions enough to enable other attacks.
+
+### Block network reconnaissance
+
+Agents don't need to scan your network.
+
+```cedar
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"nmap"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"tcpdump"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"netcat"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"nc"
+);
+```
+
+### Allow a safe set of dev tools
+
+If your agent does development work, permit the tools it actually needs:
+
+```cedar
+// Version control
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"git"
+);
+
+// Package managers
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"npm"
+);
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"npx"
+);
+
+// Safe file operations
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"cat"
+);
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"ls"
+);
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"grep"
+);
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"find"
+);
+
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"exec_command",
+  resource == Jans::Shell::"trash"
+);
+```
+
+---
+
+## API Policies
+
+### Block data exfiltration
+
+An agent that can POST to any URL can send your files, credentials, and chat history anywhere.
+
+```cedar
+// Block known paste/upload services
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"pastebin.com"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"hastebin.com"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"transfer.sh"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"file.io"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"webhook.site"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"requestbin.com"
+);
+```
+
+**Why:** Prompt injection attacks can instruct an agent to exfiltrate data by posting it to an attacker-controlled URL. Blocking common exfil endpoints is a basic hygiene measure.
+
+### Allow specific APIs your agent needs
+
+Better than blocking bad domains: only allow the domains your agent actually uses.
+
+```cedar
+// GitHub API
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"api.github.com"
+);
+
+// npm registry
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"registry.npmjs.org"
+);
+
+// Your own services
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"api.yourcompany.com"
+);
+```
+
+### Block social media posting
+
+If your agent has social media access, you might want to prevent it from posting without oversight, or block it from leaking info to random accounts.
+
+```cedar
+// Block direct API access to social platforms
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"api.twitter.com"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"api.x.com"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"graph.facebook.com"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_api",
+  resource == Jans::API::"api.linkedin.com"
+);
+```
+
+**Why:** An agent that can post to social media can damage your reputation in seconds. Even if your agent "should" post, you probably want that gated through an MCP tool with its own policy rather than raw API access.
+
+---
+
+## MCP Tool Policies
+
+### Block destructive MCP tools
+
+If you're using the filesystem MCP server, the write tools are the dangerous ones:
+
+```cedar
+forbid(
+  principal,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"filesystem/write_file"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"filesystem/move_file"
+);
+```
+
+### Block email mass operations
+
+If your agent has email access via MCP:
+
+```cedar
+// Prevent bulk deletion
+forbid(
+  principal,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"email/delete_all"
+);
+
+forbid(
+  principal,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"email/empty_trash"
+);
+
+// Prevent mass sending (spam)
+forbid(
+  principal,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"email/send_bulk"
+);
+```
+
+**Why:** An agent that can delete emails can delete your *entire inbox*. An agent that can send emails can spam your contacts. These are catastrophic, irreversible actions.
+
+### Block database mutations
+
+If your agent has database access:
+
+```cedar
+forbid(
+  principal,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"database/execute_sql"
+);
+
+// Allow reads only
+permit(
+  principal is Jans::Workload,
+  action == Jans::Action::"call_tool",
+  resource == Jans::Tool::"database/query"
+);
+```
+
+---
+
+## Complete Starter Policies
+
+### "Cautious developer" — safe for a coding agent
+
+```cedar
+// Shell: allow common dev tools, block everything dangerous
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"git");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"npm");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"npx");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"node");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"cat");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"ls");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"grep");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"find");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"trash");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"mkdir");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"cp");
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"mv");
+
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"rm");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"sudo");
+forbid(principal, action == Jans::Action::"exec_command", resource == Jans::Shell::"security");
+
+// API: allow GitHub and npm, block exfil
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"api.github.com");
+permit(principal is Jans::Workload, action == Jans::Action::"call_api", resource == Jans::API::"registry.npmjs.org");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"pastebin.com");
+forbid(principal, action == Jans::Action::"call_api", resource == Jans::API::"webhook.site");
+
+// MCP: allow all tools (rely on shell/API policies for safety)
+permit(principal is Jans::Workload, action == Jans::Action::"call_tool", resource);
+```
+
+### "Paranoid lockdown" — least privilege, deny-all baseline
+
+Set `defaultPolicy: "deny-all"` in config, then only add permits:
+
+```cedar
+// Only the exact tools this agent needs
+permit(principal is Jans::Workload, action == Jans::Action::"call_tool", resource == Jans::Tool::"filesystem/read_file");
+permit(principal is Jans::Workload, action == Jans::Action::"call_tool", resource == Jans::Tool::"filesystem/list_directory");
+
+// Only git
+permit(principal is Jans::Workload, action == Jans::Action::"exec_command", resource == Jans::Shell::"git");
+
+// No API access at all (omit all call_api permits)
+```
+
+Everything not explicitly permitted is denied. This is the most secure posture but requires you to know exactly what your agent needs.
+
+---
+
+## Policy Design Principles
+
+1. **Forbid the catastrophic, then iterate.** Start by blocking `rm`, `sudo`, and data exfil domains. You can always add more forbids later.
+
+2. **Forbid always wins.** In Cedar, a `forbid` policy overrides any `permit`. This means you can write broad permits and surgical forbids without worrying about order or precedence.
+
+3. **Binary name is the gate, not the arguments.** `Shell::"git"` permits *all* git commands including `git push --force`. If you need argument-level control, use Cedar `when` conditions on `context.args`:
+
+   ```cedar
+   forbid(
+     principal,
+     action == Jans::Action::"exec_command",
+     resource == Jans::Shell::"git"
+   ) when {
+     context.args like "*--force*"
+   };
+   ```
+
+4. **Domain name is the gate, not the path.** `API::"api.github.com"` permits all endpoints on that domain. If you need path-level control, use `when` conditions on `context.url`.
+
+5. **Deny-all is aspirational.** Most people should start with allow-all + surgical forbids. Switch to deny-all only when you understand your agent's full tool surface.
+
+6. **Review regularly.** Your agent's needs change. Policies that made sense last month might be too loose or too tight today. The GUI makes this easy — open it, look at what's enabled, adjust.
+
+---
+
+## Further Reading
+
+- [Cedar for AI Agents: Why Your AI Agent Needs a Policy Language](https://clawdrey.com/blog/cedar-for-ai-agents-part-1-why-your-ai-agent-needs-a-policy-language.html)
+- [Cedar for AI Agents: Writing Your First Agent Policy](https://clawdrey.com/blog/cedar-for-ai-agents-part-2-writing-your-first-agent-policy.html)
+- [Cedar for AI Agents: When Forbid Meets Permit](https://clawdrey.com/blog/cedar-for-ai-agents-part-3-when-forbid-meets-permit.html)
+- [Cedar for AI Agents: Proving It — SMT Solvers and Why I Trust Math More Than Tests](https://clawdrey.com/blog/proving-it-smt-solvers-and-why-i-trust-math-more-than-tests.html)
+- [Cedar Language Reference](https://docs.cedarpolicy.com/)
+- [Carapace README](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdreyhepburn/carapace",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Immutable policy boundaries for MCP tool access. Powered by Cedar + Cedarling WASM.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cedar-engine-cedarling.ts

@@ -144,6 +144,12 @@ export class CedarlingEngine {
         .replace(/.*::"/g, "")
         .replace(/"$/, "");
 
+      // Determine resource entity type from the request string
+      // Supports Tool::"x", Shell::"x", API::"x", etc.
+      let resourceEntityType = "Tool";
+      const typeMatch = request.resource.match(/^(?:\w+::)?(\w+)::/);
+      if (typeMatch) resourceEntityType = typeMatch[1];
+
       const result = await this.cedarling.authorize_unsigned({
         principals: [
           {
@@ -157,7 +163,7 @@ export class CedarlingEngine {
         action: `${this.namespace}::Action::"${actionName}"`,
         resource: {
           cedar_entity_mapping: {
-            entity_type: `${this.namespace}::Tool`,
+            entity_type: `${this.namespace}::${resourceEntityType}`,
             id: resourceId,
           },
           ...(request.context ?? {}),
@@ -189,37 +195,47 @@ export class CedarlingEngine {
   }
 
   /**
-   * Enable a tool by adding a permit policy and rebuilding Cedarling.
+   * Enable a resource by adding a permit policy and rebuilding Cedarling.
+   * resourceType: "Tool" | "Shell" | "API"
+   * action: the Cedar action name (e.g., "call_tool", "exec_command", "call_api")
    */
-  enableTool(qualifiedName: string): void {
-    const policyId = `tool-enable-${qualifiedName.replace(/\//g, "-")}`;
-    const raw = `permit(\n  principal is ${this.namespace}::${this.agentEntityType},\n  action == ${this.namespace}::Action::"call_tool",\n  resource == ${this.namespace}::Tool::"${qualifiedName}"\n);`;
+  enableResource(qualifiedName: string, resourceType: string = "Tool", action: string = "call_tool"): void {
+    const slug = qualifiedName.replace(/[^a-zA-Z0-9_-]/g, "-");
+    const policyId = `${resourceType.toLowerCase()}-enable-${slug}`;
+    const raw = `permit(\n  principal is ${this.namespace}::${this.agentEntityType},\n  action == ${this.namespace}::Action::"${action}",\n  resource == ${this.namespace}::${resourceType}::"${qualifiedName}"\n);`;
 
-    // Remove any disable policy
-    const disableId = `tool-disable-${qualifiedName.replace(/\//g, "-")}`;
+    const disableId = `${resourceType.toLowerCase()}-disable-${slug}`;
     this.removePolicyFile(disableId);
 
     this.writePolicyFile(policyId, raw);
     this.policies.set(policyId, { effect: "permit", raw });
     this.rebuildCedarling().catch(() => {});
-    this.logger.info(`Enabled tool: ${qualifiedName}`);
+    this.logger.info(`Enabled ${resourceType}: ${qualifiedName}`);
   }
 
   /**
-   * Disable a tool by adding a forbid policy and rebuilding Cedarling.
+   * Disable a resource by adding a forbid policy and rebuilding Cedarling.
    */
-  disableTool(qualifiedName: string): void {
-    const policyId = `tool-disable-${qualifiedName.replace(/\//g, "-")}`;
-    const raw = `forbid(\n  principal,\n  action == ${this.namespace}::Action::"call_tool",\n  resource == ${this.namespace}::Tool::"${qualifiedName}"\n);`;
+  disableResource(qualifiedName: string, resourceType: string = "Tool", action: string = "call_tool"): void {
+    const slug = qualifiedName.replace(/[^a-zA-Z0-9_-]/g, "-");
+    const policyId = `${resourceType.toLowerCase()}-disable-${slug}`;
+    const raw = `forbid(\n  principal,\n  action == ${this.namespace}::Action::"${action}",\n  resource == ${this.namespace}::${resourceType}::"${qualifiedName}"\n);`;
 
-    // Remove any enable policy
-    const enableId = `tool-enable-${qualifiedName.replace(/\//g, "-")}`;
+    const enableId = `${resourceType.toLowerCase()}-enable-${slug}`;
     this.removePolicyFile(enableId);
 
     this.writePolicyFile(policyId, raw);
     this.policies.set(policyId, { effect: "forbid", raw });
     this.rebuildCedarling().catch(() => {});
-    this.logger.info(`Disabled tool: ${qualifiedName}`);
+    this.logger.info(`Disabled ${resourceType}: ${qualifiedName}`);
+  }
+
+  /** Backwards-compatible aliases */
+  enableTool(qualifiedName: string): void {
+    this.enableResource(qualifiedName, "Tool", "call_tool");
+  }
+  disableTool(qualifiedName: string): void {
+    this.disableResource(qualifiedName, "Tool", "call_tool");
   }
 
   /**
@@ -293,27 +309,29 @@ export class CedarlingEngine {
       };
     }
 
-    // Verification: try a dummy authorize request. If the policy store loaded,
-    // schemas and policies are valid.
+    // Verification: try dummy authorize requests for each resource type.
+    // If the policy store loaded, schemas and policies are valid.
     try {
-      await this.cedarling.authorize_unsigned({
-        principals: [
-          {
+      for (const [action, resType] of [["call_tool", "Tool"], ["exec_command", "Shell"], ["call_api", "API"]]) {
+        await this.cedarling.authorize_unsigned({
+          principals: [
+            {
+              cedar_entity_mapping: {
+                entity_type: `${this.namespace}::${this.agentEntityType}`,
+                id: "__verify_probe__",
+              },
+            },
+          ],
+          action: `${this.namespace}::Action::"${action}"`,
+          resource: {
             cedar_entity_mapping: {
-              entity_type: `${this.namespace}::${this.agentEntityType}`,
+              entity_type: `${this.namespace}::${resType}`,
               id: "__verify_probe__",
             },
           },
-        ],
-        action: `${this.namespace}::Action::"call_tool"`,
-        resource: {
-          cedar_entity_mapping: {
-            entity_type: `${this.namespace}::Tool`,
-            id: "__verify_probe__",
-          },
-        },
-        context: {},
-      });
+          context: {},
+        });
+      }
       return { ok: true, issues: [], durationMs: Date.now() - start };
     } catch (err: any) {
       return {
@@ -491,6 +509,45 @@ export class CedarlingEngine {
               },
             },
           },
+          Shell: {
+            shape: {
+              type: "Record",
+              attributes: {
+                command: {
+                  type: "EntityOrCommon",
+                  name: "String",
+                  required: false,
+                },
+                workdir: {
+                  type: "EntityOrCommon",
+                  name: "String",
+                  required: false,
+                },
+              },
+            },
+          },
+          API: {
+            shape: {
+              type: "Record",
+              attributes: {
+                url: {
+                  type: "EntityOrCommon",
+                  name: "String",
+                  required: false,
+                },
+                method: {
+                  type: "EntityOrCommon",
+                  name: "String",
+                  required: false,
+                },
+                domain: {
+                  type: "EntityOrCommon",
+                  name: "String",
+                  required: false,
+                },
+              },
+            },
+          },
         },
         actions: {
           call_tool: {
@@ -507,6 +564,53 @@ export class CedarlingEngine {
               context: { type: "Record", attributes: {} },
             },
           },
+          exec_command: {
+            appliesTo: {
+              principalTypes: [this.agentEntityType],
+              resourceTypes: ["Shell"],
+              context: {
+                type: "Record",
+                attributes: {
+                  args: {
+                    type: "EntityOrCommon",
+                    name: "String",
+                    required: false,
+                  },
+                  workdir: {
+                    type: "EntityOrCommon",
+                    name: "String",
+                    required: false,
+                  },
+                },
+              },
+            },
+          },
+          call_api: {
+            appliesTo: {
+              principalTypes: [this.agentEntityType],
+              resourceTypes: ["API"],
+              context: {
+                type: "Record",
+                attributes: {
+                  url: {
+                    type: "EntityOrCommon",
+                    name: "String",
+                    required: false,
+                  },
+                  method: {
+                    type: "EntityOrCommon",
+                    name: "String",
+                    required: false,
+                  },
+                  body: {
+                    type: "EntityOrCommon",
+                    name: "String",
+                    required: false,
+                  },
+                },
+              },
+            },
+          },
         },
       },
     };

package/src/index.ts

@@ -64,6 +64,53 @@ export default function register(api: OpenClawPluginApi) {
     logger,
   });
 
+  // --- Bypass detection: warn if built-in tools aren't denied ---
+  const BYPASS_TOOLS = ["exec", "web_fetch", "web_search"];
+
+  function checkForBypasses(): string[] {
+    // Read OpenClaw config to check tools.deny
+    try {
+      const { readFileSync, existsSync } = require("node:fs");
+      const { join } = require("node:path");
+      const { homedir } = require("node:os");
+      const configPath = join(homedir(), ".openclaw", "openclaw.json");
+      if (!existsSync(configPath)) return BYPASS_TOOLS;
+      const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+      const denied: string[] = cfg.tools?.deny ?? [];
+      return BYPASS_TOOLS.filter((t) => !denied.includes(t));
+    } catch {
+      return BYPASS_TOOLS;
+    }
+  }
+
+  function patchConfigDenyTools(): { patched: string[]; alreadyDenied: string[] } {
+    const { readFileSync, writeFileSync, existsSync } = require("node:fs");
+    const { join } = require("node:path");
+    const { homedir } = require("node:os");
+    const configPath = join(homedir(), ".openclaw", "openclaw.json");
+
+    let cfg: any = {};
+    if (existsSync(configPath)) {
+      cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+
+    if (!cfg.tools) cfg.tools = {};
+    if (!cfg.tools.deny) cfg.tools.deny = [];
+
+    const alreadyDenied = BYPASS_TOOLS.filter((t) => cfg.tools.deny.includes(t));
+    const toAdd = BYPASS_TOOLS.filter((t) => !cfg.tools.deny.includes(t));
+
+    for (const tool of toAdd) {
+      cfg.tools.deny.push(tool);
+    }
+
+    if (toAdd.length > 0) {
+      writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    }
+
+    return { patched: toAdd, alreadyDenied };
+  }
+
   // --- Background service: connect to MCP servers and serve GUI ---
   api.registerService({
     id: "carapace",
@@ -73,6 +120,16 @@ export default function register(api: OpenClawPluginApi) {
       await aggregator.connectAll();
       await gui.start();
       logger.info(`Control GUI at http://localhost:${config.guiPort ?? 19820}`);
+
+      // Check for bypass vulnerabilities
+      const bypasses = checkForBypasses();
+      if (bypasses.length > 0) {
+        logger.warn(
+          `⚠️  BYPASS RISK: Built-in tools [${bypasses.join(", ")}] are NOT denied. ` +
+          `Agents can use these to bypass Carapace Cedar policies. ` +
+          `Run "openclaw carapace setup" to fix this automatically.`
+        );
+      }
     },
     async stop() {
       await gui.stop();
@@ -158,6 +215,184 @@ export default function register(api: OpenClawPluginApi) {
     },
   });
 
+  // --- Agent tool: execute a shell command through Cedar authorization ---
+  api.registerTool({
+    name: "carapace_exec",
+    label: "Shell Exec (Carapace)",
+    description:
+      "Execute a shell command through the Carapace Cedar proxy. The command is authorized by Cedar policies before execution. Use this when you want Cedar-gated shell access.",
+    parameters: {
+      type: "object",
+      required: ["command"],
+      properties: {
+        command: {
+          type: "string",
+          description: "The shell command to execute (e.g., 'git status', 'npm install')",
+        },
+        workdir: {
+          type: "string",
+          description: "Working directory for the command (optional)",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default: 30)",
+        },
+      },
+    },
+    async execute(_toolCallId: string, params: { command: string; workdir?: string; timeout?: number }) {
+      const { command, workdir, timeout = 30 } = params;
+
+      // Extract the binary name for policy matching
+      const binary = command.trim().split(/\s+/)[0].replace(/^.*\//, "");
+
+      // Authorize via Cedar
+      const decision = await cedar.authorize({
+        principal: `Agent::"openclaw"`,
+        action: `Action::"exec_command"`,
+        resource: `Shell::"${binary}"`,
+        context: { args: command, workdir: workdir ?? "" },
+      });
+
+      if (decision.decision === "deny") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `DENIED by Cedar policy: shell command "${binary}"\nFull command: ${command}\nReason: ${decision.reasons.join(", ") || "default deny"}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Execute the command
+      try {
+        const { execSync } = await import("node:child_process");
+        const result = execSync(command, {
+          cwd: workdir,
+          timeout: timeout * 1000,
+          maxBuffer: 1024 * 1024,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        return {
+          content: [{ type: "text", text: result }],
+        };
+      } catch (err: any) {
+        const output = err.stdout ?? err.stderr ?? err.message;
+        return {
+          content: [{ type: "text", text: `Command failed (exit ${err.status ?? "?"}): ${output}` }],
+          isError: true,
+        };
+      }
+    },
+  }, { optional: true });
+
+  // --- Agent tool: make an HTTP API call through Cedar authorization ---
+  api.registerTool({
+    name: "carapace_fetch",
+    label: "API Fetch (Carapace)",
+    description:
+      "Make an HTTP API call through the Carapace Cedar proxy. The request is authorized by Cedar policies before being sent. Use this when you want Cedar-gated outbound API access.",
+    parameters: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: {
+          type: "string",
+          description: "The URL to fetch",
+        },
+        method: {
+          type: "string",
+          description: "HTTP method (GET, POST, PUT, DELETE, PATCH). Default: GET",
+        },
+        headers: {
+          type: "object",
+          description: "HTTP headers to include",
+        },
+        body: {
+          type: "string",
+          description: "Request body (for POST/PUT/PATCH)",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default: 30)",
+        },
+      },
+    },
+    async execute(_toolCallId: string, params: {
+      url: string; method?: string; headers?: Record<string, string>; body?: string; timeout?: number
+    }) {
+      const { url, method = "GET", headers = {}, body, timeout = 30 } = params;
+
+      // Extract domain for policy matching
+      let domain: string;
+      try {
+        domain = new URL(url).hostname;
+      } catch {
+        return {
+          content: [{ type: "text", text: `Invalid URL: ${url}` }],
+          isError: true,
+        };
+      }
+
+      // Authorize via Cedar
+      const decision = await cedar.authorize({
+        principal: `Agent::"openclaw"`,
+        action: `Action::"call_api"`,
+        resource: `API::"${domain}"`,
+        context: { url, method, body: body ?? "" },
+      });
+
+      if (decision.decision === "deny") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `DENIED by Cedar policy: API call to "${domain}"\nURL: ${url}\nMethod: ${method}\nReason: ${decision.reasons.join(", ") || "default deny"}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Make the HTTP request
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout * 1000);
+
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ?? undefined,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timer);
+
+        const responseText = await response.text();
+        const truncated = responseText.length > 50000
+          ? responseText.slice(0, 50000) + "\n...[truncated]"
+          : responseText;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `HTTP ${response.status} ${response.statusText}\n\n${truncated}`,
+            },
+          ],
+          isError: !response.ok,
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `API call failed: ${err.message}` }],
+          isError: true,
+        };
+      }
+    },
+  }, { optional: true });
+
   // --- CLI command ---
   api.registerCli?.(
     ({ program }) => {
@@ -195,6 +430,58 @@ export default function register(api: OpenClawPluginApi) {
           }
         }
       });
+
+      cmd.command("setup")
+        .description("Configure OpenClaw to route exec/fetch through Carapace (denies built-in bypass tools)")
+        .action(async () => {
+          console.log("\n🦞 Carapace Setup\n");
+
+          const bypasses = checkForBypasses();
+          if (bypasses.length === 0) {
+            console.log("  ✅ All bypass tools are already denied. No changes needed.\n");
+            return;
+          }
+
+          console.log("  Built-in tools that bypass Carapace Cedar policies:");
+          for (const tool of bypasses) {
+            console.log(`    ⚠️  ${tool} — agents can use this to skip Cedar authorization`);
+          }
+
+          console.log("\n  This will add the following to your OpenClaw config:");
+          console.log(`    tools.deny: [${bypasses.map(t => `"${t}"`).join(", ")}]`);
+          console.log("\n  After setup, agents must use carapace_exec and carapace_fetch");
+          console.log("  instead, which enforce Cedar policies on every call.\n");
+
+          const { patched, alreadyDenied } = patchConfigDenyTools();
+
+          if (alreadyDenied.length > 0) {
+            console.log(`  Already denied: ${alreadyDenied.join(", ")}`);
+          }
+          if (patched.length > 0) {
+            console.log(`  ✅ Added to tools.deny: ${patched.join(", ")}`);
+            console.log("\n  Restart the gateway for changes to take effect:");
+            console.log("    openclaw gateway restart\n");
+          } else {
+            console.log("  ✅ No changes needed.\n");
+          }
+        });
+
+      cmd.command("check")
+        .description("Check for bypass vulnerabilities (built-in tools that skip Cedar)")
+        .action(async () => {
+          console.log("\n🦞 Carapace Security Check\n");
+          const bypasses = checkForBypasses();
+          if (bypasses.length === 0) {
+            console.log("  ✅ No bypass vulnerabilities found.");
+            console.log("  All agent exec/fetch operations go through Cedar.\n");
+          } else {
+            console.log("  ⚠️  Bypass vulnerabilities found:\n");
+            for (const tool of bypasses) {
+              console.log(`    🔓 ${tool} — agents can bypass Cedar policies via this tool`);
+            }
+            console.log(`\n  Run "openclaw carapace setup" to fix.\n`);
+          }
+        });
     },
     { commands: ["carapace"] },
   );

package/src/types.ts

@@ -42,6 +42,32 @@ export interface McpTool {
   enabled: boolean;
 }
 
+/** A gated resource — tools, shell commands, or APIs */
+export interface GatedResource {
+  id: string;              // unique identifier (e.g., "filesystem/read_file", "bash", "api.github.com")
+  type: "tool" | "shell" | "api";
+  name: string;            // display name
+  description: string;
+  source: string;          // server name, "local", or domain
+  enabled: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ShellRule {
+  id: string;              // e.g., "bash", "git", "npm"
+  pattern: string;         // command pattern (binary name or glob)
+  description: string;
+  enabled: boolean;
+}
+
+export interface ApiRule {
+  id: string;              // e.g., "api.github.com", "registry.npmjs.org"
+  pattern: string;         // URL pattern (domain or prefix)
+  method?: string;         // HTTP method filter (optional)
+  description: string;
+  enabled: boolean;
+}
+
 export interface ServerStatus {
   connected: boolean;
   toolCount: number;