{"_id":"@aari/aari-firewall","_rev":"2-8547af8ec8e6f2351de92a8cda659388","name":"@aari/aari-firewall","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aari/aari-firewall","version":"0.1.0","keywords":["openclaw","openclaw-plugin","aari","firewall","execution-firewall","ai-agent","agent-safety","agent-security"],"author":{"url":"https://api.getaari.com","name":"AARI","email":"hello@getaari.com"},"license":"MIT","_id":"@aari/aari-firewall@0.1.0","maintainers":[{"name":"neshkito","email":"nneshev@msn.com"}],"homepage":"https://api.getaari.com/openclaw","bugs":{"url":"https://github.com/aari-ai/openclaw-aari/issues","email":"hello@getaari.com"},"dist":{"shasum":"072c2f148b6b4a8c2232aaf213055a2ee524b3da","tarball":"https://registry.npmjs.org/@aari/aari-firewall/-/aari-firewall-0.1.0.tgz","fileCount":10,"integrity":"sha512-3AK3Y7BgbtXGIemIUIfI5ADOObcTGySXm4/3dBXaT3kv1/RmrZLVhFD5k9FCp/1eJuK9l1CQLjN12yk2Opn6Cw==","signatures":[{"sig":"MEUCIDA8BBmEQBUbVa344+JEciZ8ZBolyC3IlQFe1sXLENmvAiEAmUZRdzhz6TBr4jwunfzZiphkajb505tJqQm/XKXSyJg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26858},"main":"./src/index.ts","type":"module","engines":{"node":">=18"},"exports":{".":"./src/index.ts"},"gitHead":"b4e769d25d94b4491f05c321c8d3941b404b6ea7","scripts":{"build":"tsc"},"_npmUser":{"name":"neshkito","email":"nneshev@msn.com"},"openclaw":{"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/aari-ai/openclaw-aari.git","type":"git"},"_npmVersion":"10.8.2","description":"AARI Execution Firewall plugin for OpenClaw — intercepts tool calls before execution and enforces ALLOW/WARN/BLOCK decisions","directories":{},"_nodeVersion":"20.19.6","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/aari-firewall_0.1.0_1773610681842_0.8109464827611814","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aari/aari-firewall","version":"0.1.1","description":"AARI Execution Firewall plugin for OpenClaw — intercepts tool calls before execution and enforces ALLOW/WARN/BLOCK decisions","author":{"name":"AARI","email":"hello@getaari.com","url":"https://api.getaari.com"},"license":"MIT","type":"module","main":"./src/index.ts","exports":{".":"./src/index.ts"},"keywords":["openclaw","openclaw-plugin","aari","firewall","execution-firewall","ai-agent","agent-safety","agent-security"],"repository":{"type":"git","url":"git+https://github.com/aari-ai/openclaw-aari.git"},"homepage":"https://api.getaari.com/openclaw","bugs":{"url":"https://github.com/aari-ai/openclaw-aari/issues","email":"hello@getaari.com"},"publishConfig":{"access":"public"},"openclaw":{"extensions":["./src/index.ts"]},"scripts":{"build":"tsc"},"devDependencies":{"typescript":"^5.4.0"},"engines":{"node":">=18"},"_id":"@aari/aari-firewall@0.1.1","gitHead":"491026f37b42d9c50ad21a1745030decf27de225","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-JDnuE98NXAwB8cnFMFvQvKX6T6CTlPyWE7+EGRsR3FGjAQnNI9ym3uu2xvFCEP6lMEYVZQ7nGe/xQuSyo5s73A==","shasum":"cdf73fbebccb2cc1a33cff00780092e9a8b9f8b1","tarball":"https://registry.npmjs.org/@aari/aari-firewall/-/aari-firewall-0.1.1.tgz","fileCount":10,"unpackedSize":29384,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH+8zKB0knwg0p9U+XYwJa5PX5Du0A1JOnkUjDZzdNz/AiEAndffZOI+FWl09blVLbVqPghWmRt+CjuHJOjYY0ALesc="}]},"_npmUser":{"name":"neshkito","email":"nneshev@msn.com"},"directories":{},"maintainers":[{"name":"neshkito","email":"nneshev@msn.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aari-firewall_0.1.1_1773665081265_0.8092974448786456"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-15T21:38:01.746Z","modified":"2026-03-16T12:44:41.513Z","0.1.0":"2026-03-15T21:38:01.994Z","0.1.1":"2026-03-16T12:44:41.395Z"},"bugs":{"url":"https://github.com/aari-ai/openclaw-aari/issues","email":"hello@getaari.com"},"author":{"name":"AARI","email":"hello@getaari.com","url":"https://api.getaari.com"},"license":"MIT","homepage":"https://api.getaari.com/openclaw","keywords":["openclaw","openclaw-plugin","aari","firewall","execution-firewall","ai-agent","agent-safety","agent-security"],"repository":{"type":"git","url":"git+https://github.com/aari-ai/openclaw-aari.git"},"description":"AARI Execution Firewall plugin for OpenClaw — intercepts tool calls before execution and enforces ALLOW/WARN/BLOCK decisions","maintainers":[{"name":"neshkito","email":"nneshev@msn.com"}],"readme":"# AARI Execution Firewall — OpenClaw Plugin\n\nExecution firewall for OpenClaw agents.\nThe plugin intercepts tool calls **before execution**, asks the AARI control plane for a decision, and enforces **ALLOW / WARN / BLOCK** behavior inside OpenClaw.\n\nThis README reflects the **current hook-based implementation** and the runtime behavior already validated on a live OpenClaw instance.\n\n---\n\n## What it does\n\nThe plugin adds a real pre-execution control layer in front of OpenClaw tool calls.\n\nMain user value:\n- OpenClaw remains powerful\n- risky actions can be scored and blocked before they execute\n- users get clear block reasons instead of silent failures or hidden behavior\n- AARI receives an audit trail for decisions and outcomes\n\n---\n\n## Current implementation model\n\nThe plugin uses **native OpenClaw hooks**:\n\n1. **`before_prompt_build`**\n   - injects AARI system context into the prompt\n   - advisory layer only\n\n2. **`before_tool_call`**\n   - maps the OpenClaw tool call to an AARI `action_type`\n   - calls the AARI `/gate` endpoint\n   - enforces the decision before execution\n\n3. **`after_tool_call`**\n   - reports `SUCCESS` / `FAILURE` outcomes back to AARI\n   - blocked calls are reported as skipped from the blocking path\n\nThis is the current source-of-truth behavior.\nIt is **not** based on `registerTool` tool-shadowing in the current implementation.\n\n---\n\n## Decision behavior\n\nFor each intercepted tool call, AARI returns one of:\n\n- **ALLOW** — execution proceeds normally\n- **WARN** — execution proceeds, but the action is flagged\n- **BLOCK** — execution is stopped before the tool runs\n\nIn enforced mode, BLOCK returns a clean OpenClaw block result such as:\n\n```text\n[AARI BLOCK] 'exec' blocked. Policy: ...\n```\n\nThe goal is to stop the action cleanly without breaking the runtime.\n\n---\n\n## Fail-closed behavior\n\nIf the AARI server is unreachable, the plugin uses local degraded/fail-closed logic.\n\nThis is **action-type based**, not a universal block-all mode:\n\n- `filesystem.rm`, `filesystem.write`, `file.delete`, `code.execute` → **BLOCK** locally\n- `unknown.action`, `agent.action` → **WARN** locally (never silent pass-through)\n- Other action types → ALLOW or WARN depending on class\n\n---\n\n## Installation\n\n### Package name\n\nCurrent package name:\n\n```text\n@aari/aari-firewall\n```\n\n### Local/path install\n\nOpenClaw can install the plugin from a local path.\nExample:\n\n```bash\nopenclaw plugins install /path/to/openclaw-aari\n```\n\nAfter installation, configure the plugin entry in `openclaw.json`.\n\n### Minimal config example\n\n```json\n{\n  \"plugins\": {\n    \"allow\": [\"aari-firewall\"],\n    \"entries\": {\n      \"aari-firewall\": {\n        \"enabled\": true,\n        \"config\": {\n          \"apiKey\": \"sk_aari_...\",\n          \"server\": \"https://api.getaari.com\",\n          \"agentId\": \"openclaw-agent\",\n          \"environment\": \"dev\",\n          \"mode\": \"enforced\",\n          \"timeoutMs\": 5000\n        }\n      }\n    }\n  }\n}\n```\n\nThen restart OpenClaw.\n\n---\n\n## Configuration\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `apiKey` | string | required | AARI API key |\n| `server` | string | `https://api.getaari.com` | AARI server URL |\n| `agentId` | string | `openclaw-agent` | Agent identifier used in AARI audit trail |\n| `environment` | `dev \\| staging \\| prod` | `prod` | Deployment environment |\n| `mode` | `enforced \\| advisory` | `enforced` | `enforced` blocks; `advisory` warns only |\n| `timeoutMs` | number | `5000` | Gate request timeout |\n\n---\n\n## Tool mapping\n\nThe plugin maps OpenClaw tool names into AARI action types.\n\n### Confirmed important mappings\n\n| OpenClaw tool | AARI action type |\n|---|---|\n| `shell`, `bash`, `exec`, `execute` | `code.execute` |\n| `file_write`, `write_file` | `filesystem.write` |\n| `file_delete`, `delete_file` | `filesystem.rm` |\n| `http_post` | `http.post` |\n| `send_email`, `email_send` | `email.send` |\n| `message` | `message.send` |\n| `sql`, `db_query`, `db_execute` | `db.execute` |\n| fallback | `unknown.action` |\n\nThe `message` mapping is important because real OpenClaw outbound messaging flows through `message`, not only through older names like `send_message`.\n\nAny tool name not in the mapping table falls back to `unknown.action` (score 55, WARN territory). This means unmapped tools are never silently low-risk.\n\n---\n\n## Runtime validation already completed\n\nThe following paths have already been validated on a live OpenClaw instance:\n\n### Shell / exec\n- `exec` ALLOW path works\n- destructive `exec` commands can be blocked by AARI policy\n- blocked `exec` actions do not execute\n\n### Protected path escalation\n- writes and deletes targeting `~/.ssh`, `.aws/credentials`, and other secret paths → BLOCK\n- writes and deletes targeting `/etc/`, `/usr/bin/`, and other system paths → BLOCK\n- `code.execute` commands touching protected paths → BLOCK (enforced mode)\n- temp path operations score correctly without false elevation\n\n### Outbound messaging\n- outbound `message -> telegram` ALLOW path works\n- outbound `message -> telegram` BLOCK path works\n- `message.send` and `email.send` → WARN by default (warn policies fire)\n\n### Unknown / unmapped tools\n- unmapped tool names fall back to `unknown.action`\n- `unknown.action` → WARN decision (never silent ALLOW)\n- warn-oc-unknown-action policy fires on all unmapped tool calls\n\nThis means the plugin is validated on:\n- shell/exec enforcement\n- protected-path blocking (secret and system paths)\n- outbound messaging visibility and control\n- unmapped tool fallback behavior\n\n---\n\n## Audit trail\n\nEvery intercepted action can be reported into AARI with:\n- action type\n- resource\n- score\n- policy hits\n- decision\n- outcome (`SUCCESS`, `FAILURE`, `SKIPPED`)\n- agent ID / run context\n\nThis makes the plugin both an enforcement layer and an audit surface.\n\n---\n\n## Known limitations\n\nCurrent known limitations:\n\n- README/install flow still needs a fresh-user validation pass\n- other OpenClaw channels beyond exec and Telegram are not yet all proven end-to-end\n- command understanding is heuristic (pattern matching, not full shell-intent parsing)\n- workspace root is not configured — workspace-like path detection is heuristic\n- actions are evaluated independently — cross-tool multi-step correlation is not yet supported\n- scripts are scored by execution context, not by reading script contents\n\n---\n\n## Honest V1 scope\n\nThis plugin is currently proven as:\n\n- an OpenClaw execution firewall for shell/exec actions\n- protected-path blocking (secret and system paths, write and delete)\n- outbound messaging visibility and control (`message.send`, `email.send`, Telegram)\n- safe unmapped tool fallback via `unknown.action` (never silent)\n- fail-closed behavior when AARI is unreachable\n\nIt should **not** yet be described as universal coverage for every OpenClaw channel or every agent ecosystem.\n\n---\n\n## Summary\n\nAARI Execution Firewall for OpenClaw provides:\n- pre-execution interception via native OpenClaw hooks\n- ALLOW / WARN / BLOCK decisions from AARI\n- clean blocking behavior inside OpenClaw\n- outcome reporting for audit trail\n- proven protection for `exec` and shell commands\n- proven protected-path blocking (secret and system paths)\n- outbound messaging visibility and control\n- safe fallback for unmapped tools via `unknown.action`\n","readmeFilename":"README.md"}