openclaw-safe-exec

Per-agent whitelisted sudo execution with three-layer defense-in-depth

Whitelist Isolation · Audit Trail · Zero Dependencies · sudoers Integration

Why This Plugin?

AI Agents that manage macOS infrastructure need sudo for tasks like restarting services or applying configuration changes. Unrestricted root access is unacceptable. This plugin gives each agent exactly the privileges it needs — no more, no less — with every action recorded in an audit trail.

Capability	OpenClaw Built-in (exec-approvals)	+ safe-exec Plugin
Binary path restriction	✅	✅
Per-agent command isolation	❌	✅
App:command whitelist	❌	✅
Wildcard patterns (app:*)	❌	✅
Audit trail (ALLOW/DENY/RESULT)	❌	✅
Dynamic agent ID resolution	❌	✅
sudo -n non-interactive mode	❌	✅
execFile (no shell injection)	❌	✅
Execution timeout (30s)	❌	✅
Per-agent tool description	❌	✅
Unconfigured agents blocked	❌	✅

Architecture

Three independent layers — compromising one does not bypass the others.

flowchart TB
    subgraph L3["Layer 3 — OpenClaw Platform"]
        EA["exec-approvals: binary path restriction"]
    end
    subgraph L2["Layer 2 — safe-exec Plugin"]
        WL["Per-agent whitelist check"]
        AU["Audit log (ALLOW / DENY)"]
    end
    subgraph L1["Layer 1 — OS sudoers"]
        SD["NOPASSWD: dispatcher app cmd only"]
    end

    Agent -->|"safe_exec(app, cmd)"| L3
    L3 --> L2
    WL -->|DENY| AU
    WL -->|ALLOW| AU
    AU -->|ALLOW| L1
    L1 -->|"execFile (no shell)"| Dispatcher
    Dispatcher --> Result
    Result -->|"audit RESULT"| AU

Loading

Per-Agent Permission Isolation

Agent	Role	Allowed	Denied
david	Infrastructure ops	webserver:*, database:*, monitoring:status, backup:status, backup:list	backup:start/stop/restart, monitoring:*
bob	Maintenance assistant	backup:*, monitoring:*	webserver:*, database:*

david can restart the webserver and manage the database, but cannot run backups or view full monitoring. bob can manage backups and monitoring, but has zero access to core services. Each agent operates in its own permission sandbox.

Audit Trail

Every call — allowed or denied — is appended to the audit log:

2026-03-08T16:30:00.000Z | david        | ALLOW  | webserver status
2026-03-08T16:30:01.000Z | david        | RESULT | webserver status | exit=0
2026-03-08T16:31:00.000Z | bob          | DENY   | database status

Fields: timestamp, agent ID, verdict (ALLOW/DENY/RESULT), command, exit code. Enables post-incident forensics and compliance review.

Installation

1. Install the plugin

   npm install openclaw-safe-exec
   openclaw plugins install openclaw-safe-exec

   Or install from source:

   git clone https://github.com/yangsjt/openclaw-safe-exec.git
   cd openclaw-safe-exec
   openclaw plugins install .

2. Install sudoers rules (grants NOPASSWD for tools.sh only)

   bash sudoers/install-sudoers.sh

3. Add plugin config to ~/.openclaw/openclaw.json

   Copy examples/openclaw.json.example and customize:

   • dispatcher — absolute path to your dispatcher script
   • sudoApps — apps that require sudo to execute
   • agents — per-agent allow lists (see Whitelist Format below)

4. Restart OpenClaw gateway

Configuration

{
  "plugins": {
    "entries": {
      "safe-exec": {
        "enabled": true,
        "config": {
          "dispatcher": "/path/to/your/dispatcher.sh",
          "sudoApps": ["webserver", "database"],
          "auditLog": "~/.openclaw/safe-exec-audit.log",
          "agents": {
            "david": {
              "allow": [
                "webserver:*",
                "database:*",
                "monitoring:status",
                "backup:status",
                "backup:list"
              ]
            },
            "bob": {
              "allow": [
                "backup:*",
                "monitoring:*"
              ]
            }
          }
        }
      }
    }
  }
}

Whitelist Format

• app:cmd — exact match (e.g. monitoring:status)
• app:* — all commands for that app (e.g. webserver:*)

Tests

npm test

Files

File	Purpose
index.js	Plugin entry: register(api)
src/safe-exec-tool.js	Tool factory with per-agent permission
src/permission.js	Whitelist parsing and matching
src/executor.js	child_process.execFile wrapper with sudo
src/audit.js	Append-only audit log
sudoers/openclaw-agents.sudoers.example	NOPASSWD rules template
sudoers/install-sudoers.sh	Safe sudoers installer
examples/openclaw.json.example	Sanitized config template
examples/local.json	Local machine config (gitignored)
openclaw.plugin.json	Plugin manifest (id: safe-exec)

License

MIT