Merge pull request #16 from peg/staging

v0.1.9: LD_PRELOAD cascade, OpenClaw file tool patching, docs overhaul

Author: peg

README.md

@@ -498,6 +498,16 @@ For [OpenClaw](https://github.com/openclaw/openclaw) users — one command sets
 rampart setup openclaw
 ```
 
+This covers all `exec` tool calls. For full file tool coverage (Read, Write, Edit), run:
+
+```bash
+rampart setup openclaw --patch-tools
+```
+
+This patches OpenClaw's Read, Write, Edit, and Grep tools to check Rampart before file operations. Requires write access to the OpenClaw installation directory (typically needs `sudo` for global npm installs).
+
+⚠️ **Re-run after OpenClaw upgrades** — the patch modifies files in `node_modules` that get replaced on update. Between upgrade and re-patch, file tools bypass Rampart (exec shim remains active).
+
 Works on Linux (systemd) and macOS (launchd).
 
 ---
@@ -649,8 +659,9 @@ Current: **v0.1.8** — all tests passing.
 
 | Agent | Method | Status |
 |-------|--------|--------|
-| Claude Code | `rampart setup claude-code` | Native hooks, all platforms |
-| Cline | `rampart setup cline` | Native hooks, all platforms |
+| Claude Code | `rampart setup claude-code` | Native hooks (exec + file), all platforms |
+| Cline | `rampart setup cline` | Native hooks (exec + file), all platforms |
+| OpenClaw | `rampart setup openclaw [--patch-tools]` | Exec shim + optional file tool patch, Linux/macOS |
 | Codex CLI | `rampart preload` | LD_PRELOAD, Linux + macOS |
 | Claude Desktop | `rampart mcp` | MCP server proxying, all platforms |
 | Aider | `rampart wrap` | Linux, macOS |

configs/examples/openclaw.yaml

@@ -16,6 +16,11 @@ policies:
         when:
           path_matches:
             - "**/.ssh/id_*"
+          path_not_matches:
+            - "**/*.pub"
+      - action: deny
+        when:
+          path_matches:
             - "**/.aws/credentials"
             - "**/.gnupg/*"
             - "**/*.pem"

docs/THREAT-MODEL.md

@@ -1,6 +1,6 @@
 # Threat Model
 
-> Last reviewed: 2026-02-12 | Applies to: v0.1.8
+> Last reviewed: 2026-02-13 | Applies to: v0.1.9-dev (with file tool patching)
 
 Rampart is a policy engine for AI agents — not a sandbox, not a hypervisor, not a full isolation boundary. This document describes what Rampart protects against, what it doesn't, and why.
 
@@ -49,11 +49,13 @@ Policy files are the security boundary. If an attacker can modify policy files,
 Rampart evaluates the command string passed to the shell. This applies to **all integration methods** — native hooks (Claude Code, Cline), wrap mode, LD_PRELOAD, and the HTTP API all see the same command string. If an agent runs `python3 script.py`, Rampart sees and evaluates `python3 script.py` — but cannot inspect what `script.py` does internally.
 
 **Mitigations:**
+- **LD_PRELOAD cascade** (v0.1.9+): When using `rampart preload` or `rampart wrap`, child processes spawned by allowed commands automatically inherit the interceptor. This means `python3 script.py` calling `os.system("rm -rf /")` is caught — the subprocess goes through Rampart's policy engine. Covers `execve`, `execvpe`, and `posix_spawn` call paths.
 - The optional [rampart-verify](https://github.com/peg/rampart-verify) sidecar uses LLM classification to assess intent of commands like `python3 -c "..."` based on the inline code
-- File write hooks can catch the creation of malicious scripts before execution
 - Patterns like `python3 -c *` can be routed to semantic verification via `action: webhook`
 
-**Remaining surface:** Multi-step sequences (write file, then execute) are an active area of development. In practice, AI agents overwhelmingly shell out via `subprocess`/`os.system` rather than using native APIs — and those shell-outs go through Rampart.
+**Remaining surface:** The cascade only applies to wrap/preload modes, not native hooks (Claude Code, Cline). Programs that use native file I/O without shelling out, or setuid binaries that drop LD_PRELOAD, are not covered.
+
+**Multi-step sequences:** With file tool coverage enabled (native hooks or `--patch-tools`), write-then-execute sequences are evaluated at both steps independently — the write is checked against file policies and the exec against command policies.
 
 ### 2. Audit Log Rewrite
 
@@ -91,7 +93,22 @@ An agent could potentially encode commands to bypass pattern matching:
 
 **Coverage:** The two-layer approach (pattern matching + LLM classification) significantly reduces the obfuscation surface. Pattern matching catches known encodings; the LLM layer catches intent regardless of how the command is formatted.
 
-### 5. Fail-Open Behavior
+### 5. Framework-Specific Patching
+
+Some agent frameworks (e.g., OpenClaw) don't expose hook points for file operations. Rampart provides a `--patch-tools` option that modifies framework source files to add policy checks before read/write/edit operations. These patches don't survive framework upgrades — they modify files in `node_modules` that get replaced on update.
+
+**Mitigations:**
+- `rampart setup openclaw --patch-tools` must be re-run immediately after OpenClaw upgrades to restore protection
+- Native hook integrations (Claude Code, Cline) don't have this limitation — they use the framework's own hook system
+- A feature request for generic tool authorization hooks benefits the entire ecosystem and would eliminate the need for patching
+
+**Security implications:**
+- **Timing window:** Between OpenClaw upgrade and re-patch, file tools bypass all policies (exec shim remains active)
+- **Silent degradation:** If the target code changes in a new version, patches fail to apply and file tools fail-open without warning. The patch script exits with an error, but if run unattended this could go unnoticed.
+
+**Trade-off:** Monkey-patching is fragile but functional. It closes a real security gap today while proper upstream support is developed. The patches fail-open — if the patched code changes in an upgrade, the worst case is that file tools bypass Rampart (reverting to the pre-patch state), not that they break.
+
+### 6. Fail-Open Behavior
 
 When `rampart serve` is unreachable (crashed, network issue), the shim defaults to **fail-open** — commands execute without policy checks. This is a deliberate design choice: fail-closed would lock you out of your own machine.
 

policies/standard.yaml

@@ -53,6 +53,11 @@ policies:
         when:
           path_matches:
             - "**/.ssh/id_*"
+          path_not_matches:
+            - "**/*.pub"
+      - action: deny
+        when:
+          path_matches:
             - "**/.aws/credentials"
             - "**/.env"
             - "**/.netrc"

preload/librampart.c

@@ -23,6 +23,7 @@
 #include <unistd.h>
 #include <dlfcn.h>
 #include <errno.h>
+#include <limits.h>
 #include <sys/types.h>
 #include <sys/wait.h>
 #include <pthread.h>
@@ -51,6 +52,8 @@ struct http_response {
 static CURL *curl_handle = NULL;
 static pthread_mutex_t curl_mutex = PTHREAD_MUTEX_INITIALIZER;
 static pthread_once_t init_once = PTHREAD_ONCE_INIT;
+static char preload_lib_path[PATH_MAX];
+static int preload_anchor;
 
 // Original function pointers
 static int (*real_execve)(const char *, char *const[], char *const[]) = NULL;
@@ -62,6 +65,7 @@ static int (*real_system)(const char *) = NULL;
 static FILE *(*real_popen)(const char *, const char *) = NULL;
 static int (*real_posix_spawn)(pid_t *, const char *, const posix_spawn_file_actions_t *,
                                const posix_spawnattr_t *, char *const[], char *const[]) = NULL;
+extern char **environ;
 
 static void debug_log(const char *fmt, ...) {
     if (!config.debug) return;
@@ -119,6 +123,12 @@ static void init_config(void) {
 static void init_library(void) {
     init_config();
     debug_log("Initializing librampart for PID %d", getpid());
+
+    Dl_info info;
+    if (dladdr(&preload_anchor, &info) && info.dli_fname) {
+        strncpy(preload_lib_path, info.dli_fname, sizeof(preload_lib_path) - 1);
+        preload_lib_path[sizeof(preload_lib_path) - 1] = '\0';
+    }
 
     // Initialize libcurl
     curl_global_init(CURL_GLOBAL_DEFAULT);
@@ -175,6 +185,58 @@ static void init_library(void) {
     debug_log("Library initialized successfully");
 }
 
+static int ld_preload_contains(const char *value) {
+    if (!value || !*value || !*preload_lib_path) return 0;
+    size_t n = strlen(preload_lib_path);
+    const char *p = value;
+    while (*p) {
+        const char *end = strchr(p, ':');
+        size_t len = end ? (size_t)(end - p) : strlen(p);
+        if (len == n && strncmp(p, preload_lib_path, n) == 0) return 1;
+        if (!end) break;
+        p = end + 1;
+    }
+    return 0;
+}
+
+static void free_modified_envp(char **env) {
+    if (!env) return;
+    for (size_t i = 0; env[i]; i++) free(env[i]);
+    free(env);
+}
+
+static char **ensure_preload_env(char *const envp[], int *modified) {
+    *modified = 0;
+    if (!*preload_lib_path) return (char **)envp;
+    char *const *src = envp ? envp : (char *const *)environ;
+    size_t n = 0, ld_idx = (size_t)-1;
+    for (; src && src[n]; n++) if (strncmp(src[n], "LD_PRELOAD=", 11) == 0) ld_idx = n;
+    if (ld_idx != (size_t)-1 && ld_preload_contains(src[ld_idx] + 11)) return (char **)envp;
+    char **out = calloc(n + 2, sizeof(char *));
+    if (!out) return (char **)envp;
+    for (size_t i = 0; i < n; i++) {
+        if (i == ld_idx) {
+            const char *cur = src[i] + 11;
+            size_t cur_len = strlen(cur), lib_len = strlen(preload_lib_path);
+            out[i] = malloc(11 + cur_len + (cur_len ? 1 : 0) + lib_len + 1);
+            if (!out[i]) { free_modified_envp(out); return (char **)envp; }
+            snprintf(out[i], 11 + cur_len + (cur_len ? 1 : 0) + lib_len + 1,
+                     "LD_PRELOAD=%s%s%s", cur, cur_len ? ":" : "", preload_lib_path);
+            continue;
+        }
+        out[i] = strdup(src[i]);
+        if (!out[i]) { free_modified_envp(out); return (char **)envp; }
+    }
+    if (ld_idx == (size_t)-1) {
+        size_t lib_len = strlen(preload_lib_path);
+        out[n] = malloc(11 + lib_len + 1);
+        if (!out[n]) { free_modified_envp(out); return (char **)envp; }
+        snprintf(out[n], 11 + lib_len + 1, "LD_PRELOAD=%s", preload_lib_path);
+    }
+    *modified = 1;
+    return out;
+}
+
 /* Wrap str in quotes with JSON escaping.  Returns a malloc'd string.
  * Allocation: len*2 (worst case: every char needs a backslash) + 2 (quotes) + 1 (NUL). */
 static char *escape_json_string(const char *str) {
@@ -357,7 +419,11 @@ int execve(const char *path, char *const argv[], char *const envp[]) {
 
     debug_log("Allowing execve: %s", cmd ? cmd : "(null)");
     if (cmd) free(cmd);
-    return real_execve(path, argv, envp);
+    int modified = 0;
+    char **effective_envp = ensure_preload_env(envp, &modified);
+    int rc = real_execve(path, argv, effective_envp);
+    if (modified) free_modified_envp(effective_envp);
+    return rc;
 }
 
 int execvp(const char *file, char *const argv[]) {
@@ -400,7 +466,11 @@ int execvpe(const char *file, char *const argv[], char *const envp[]) {
 
     debug_log("Allowing execvpe: %s", cmd ? cmd : "(null)");
     if (cmd) free(cmd);
-    return real_execvpe(file, argv, envp);
+    int modified = 0;
+    char **effective_envp = ensure_preload_env(envp, &modified);
+    int rc = real_execvpe(file, argv, effective_envp);
+    if (modified) free_modified_envp(effective_envp);
+    return rc;
 }
 #endif
 
@@ -459,7 +529,11 @@ int posix_spawn(pid_t *pid, const char *path,
 
     debug_log("Allowing posix_spawn: %s", cmd ? cmd : "(null)");
     if (cmd) free(cmd);
-    return real_posix_spawn(pid, path, file_actions, attrp, argv, envp);
+    int modified = 0;
+    char **effective_envp = ensure_preload_env(envp, &modified);
+    int rc = real_posix_spawn(pid, path, file_actions, attrp, argv, effective_envp);
+    if (modified) free_modified_envp(effective_envp);
+    return rc;
 }
 
 // Cleanup function (called at library unload)
@@ -470,4 +544,4 @@ void cleanup_library(void) {
         curl_handle = NULL;
     }
     curl_global_cleanup();
-}
+}

preload/test_preload.sh

@@ -265,6 +265,17 @@ test_child_process_inheritance() {
     else
         log_error "Child process inheritance failed"
     fi
+
+    export RAMPART_DEBUG="1"
+    if command -v python3 >/dev/null 2>&1; then
+        output=$(python3 -c 'import os; os.system("true")' 2>&1 >/dev/null || true)
+        if echo "$output" | grep -q "Allowing system: true"; then log_success "Python os.system() intercepted"; else log_error "Python os.system() interception missing"; fi
+    else
+        log_warning "Skipping Python cascade test (python3 not available)"
+    fi
+    output=$(bash -c 'bash -c "ls >/dev/null"' 2>&1 >/dev/null || true)
+    if echo "$output" | grep -q "Allowing exec"; then log_success "Bash subprocess interception working"; else log_error "Bash subprocess interception missing"; fi
+    export RAMPART_DEBUG="0"
 }
 
 # Main test runner
@@ -341,4 +352,4 @@ case "${1:-}" in
         echo "Use --help for usage information"
         exit 1
         ;;
-esac
+esac