@aporthq/aport-agent-guardrails 1.0.11 → 1.0.12

package/README.md

@@ -60,7 +60,7 @@ Your agent should **only do what you explicitly allow**. APort runs in the hook
 
 | Policy | What it guards |
 |--------|----------------|
-| **system.command.execute.v1** | Shell commands — allowlist, 40+ blocked patterns (`rm -rf`, `sudo`, injection) |
+| **system.command.execute.v1** | Shell commands — allowlist, 50+ blocked patterns (`rm -rf`, `sudo`, `nc`, `find -exec rm`, injection); passport `allowed_paths` override for path rules |
 | **mcp.tool.execute.v1** | MCP tool calls — server allowlist, rate limits |
 | **messaging.message.send.v1** | Message sends — rate caps, capability checks |
 | **agent.session.create.v1** / **agent.tool.register.v1** | Sessions and tool registration |
@@ -335,7 +335,7 @@ graph TB
 **✅ Pre-action authorization (agent misbehavior):**
 - **Prompt injection** - Hook-based enforcement; agent cannot bypass via prompts
 - **Malicious skills** - Third-party OpenClaw skills validated before execution
-- **Unauthorized commands** - Allowlist + 40+ blocked patterns (rm -rf, sudo, etc.)
+- **Unauthorized commands** - Allowlist + 50+ blocked patterns (rm -rf, sudo, nc, find -exec rm, etc.)
 - **Data exfiltration** - File access, messaging, web requests controlled by policy
 - **Resource limits** - Rate limits, size caps, transaction amounts enforced
 

package/docs/OPENCLAW_TOOLS_AND_POLICIES.md

@@ -32,6 +32,7 @@ Per the **Open Agent Passport (OAP) spec**, the passport has a **limits** object
 - **read** and **write** are **now mapped** to APort policies:
   - **read** → `data.file.read.v1` (enforces path allowlists, blocked patterns for SSH keys/credentials/.env)
   - **write** → `data.file.write.v1` (enforces path allowlists, blocks system directories, optional extension restrictions)
+- **Middleware param spreading:** The LangChain and CrewAI Node middlewares automatically parse tool input JSON and spread parameters (e.g. `file_path`) into the top-level verification context. This is required because the API's policy schema validates `file_path` as a required field. Without this, `read`/`write` tool calls would fail with 400 Bad Request.
 - Configure passport limits for file operations:
   - `limits.data.file.read.allowed_paths` - Array of allowed path prefixes (e.g. `["/tmp/*", "/home/user/projects/*"]`)
   - `limits.data.file.read.blocked_patterns` - Array of patterns to block (e.g. `["**/.ssh/**", "**/.env"]`)
@@ -41,6 +42,23 @@ Per the **Open Agent Passport (OAP) spec**, the passport has a **limits** object
 
 ---
 
+## Passport-configurable path overrides
+
+The `system.command.execute.v1` policy includes hardcoded security patterns that block access to sensitive system directories (`/etc/`, `/sys/`, `/proc/`, etc.), sensitive hidden files, credential files, and more. Passport owners can override **path-sensitivity heuristics** by setting `limits.allowed_paths` or `limits.allowed_directories` in the passport:
+
+```json
+{
+  "limits": {
+    "allowed_paths": ["/root/", "/home/agent/work/"],
+    "allowed_commands": ["*"]
+  }
+}
+```
+
+When `allowed_paths` is set and the command references one of those paths, overridable rules (like "Access to sensitive system directories" or "Access to secrets and credentials files") are skipped. **Catastrophic protections are never overridable** — fork bombs, `rm -rf /`, reverse shells, `nc`/`netcat`, and `find -exec rm` are always blocked regardless of passport config.
+
+---
+
 ## Summary table
 
 | OpenClaw tool (examples) | APort policy              | Passport limits (key)                    |

package/docs/SECURITY_MODEL.md

@@ -30,8 +30,9 @@ APort operates as a **pre-action authorization layer** that enforces policies **
 
 **Unauthorized tool usage:**
 - Agent tries to execute commands not in allowlist
-- Commands match blocked patterns (`rm -rf`, `sudo`, `chmod 777`, etc.)
+- Commands match blocked patterns (`rm -rf`, `sudo`, `chmod 777`, `nc`/`netcat`, `find -exec rm`, etc.)
 - Shell escapes and interpreter bypasses (python -c, base64 encoding)
+- Stderr redirects (`2>/dev/null`) are allowed; dangerous redirects to files are blocked
 - Result: Only allowlisted, non-dangerous commands execute
 
 **Resource exhaustion and limit violations:**
@@ -135,7 +136,7 @@ APort's three-layer security model:
 - Use case: Testing custom policies before registering them
 
 **Example policies (out of the box):**
-- `system.command.execute.v1` - Shell commands (allowlist, 40+ blocked patterns)
+- `system.command.execute.v1` - Shell commands (allowlist, 50+ blocked patterns, passport `allowed_paths` override)
 - `data.file.read.v1` / `data.file.write.v1` - File access control
 - `web.fetch.v1` / `web.browser.v1` - Web requests and browser automation
 - `messaging.message.send.v1` - Message rate limits, recipient allowlist
@@ -292,6 +293,7 @@ APort's three-layer security model:
 APort uses secure defaults out of the box:
 
 ✅ `failClosed: true` - Block tools on errors (security over availability)
+✅ `fail_open_on_api_error: false` - API infrastructure errors (4xx/5xx, network) also fail closed by default
 ✅ `allowUnmappedTools: false` - Unmapped tools blocked (deny-by-default)
 ✅ API mode recommended for production
 ✅ Passport status checked first (suspended/revoked → deny all)
@@ -335,6 +337,25 @@ APort uses secure defaults out of the box:
 
 ---
 
+#### `fail_open_on_api_error: false` vs `fail_open_on_api_error: true`
+
+**False (default, recommended):**
+- API infrastructure errors (4xx/5xx, network failures, timeouts) → deny tool execution
+- Same behavior as `failClosed: true` for API errors
+
+**True (use with caution):**
+- API infrastructure errors → allow tool execution with `[fail-open]` warning
+- Genuine policy denials (HTTP 200 with `allow: false`) are **never** overridden—always denied
+- Useful when API availability is unreliable but you still want policy enforcement when the API is reachable
+
+**Security impact:** MEDIUM - Only API errors become allow; actual policy denials still block.
+
+**When to use true:** Production environments where API downtime shouldn't halt agent operations, combined with monitoring for `[fail-open]` decisions.
+
+**Config:** Set in `config.yaml` as `fail_open_on_api_error: true` or env var `APORT_FAIL_OPEN_ON_API_ERROR=1`.
+
+---
+
 #### `allowUnmappedTools: false` vs `allowUnmappedTools: true`
 
 **False (default, recommended):**
@@ -546,7 +567,10 @@ A: API for production (signed decisions, protected passport, global suspend). Lo
 A: In API mode, policies come from APort API over HTTPS. In local mode, policies are embedded in bash scripts (protected by filesystem permissions). Custom policies can be passed in request body for testing.
 
 **Q: What if the API is down?**
-A: Default behavior (failClosed: true) denies tool calls. For high-availability scenarios, consider running a self-hosted agent-passport instance or use local mode as fallback.
+A: Default behavior (failClosed: true) denies tool calls. You can set `fail_open_on_api_error: true` to allow on API infrastructure errors while still enforcing genuine policy denials. For high-availability scenarios, consider running a self-hosted agent-passport instance or use local mode as fallback.
+
+**Q: Can passport owners override blocked path rules (e.g. allow /root/)?**
+A: Yes. Set `limits.allowed_paths` (or `limits.allowed_directories`) in the passport to override path-sensitivity heuristics like "Access to sensitive system directories." Catastrophic protections (fork bombs, `rm -rf /`, reverse shells, `nc`/`netcat`) can **never** be overridden by passport config.
 
 **Q: Can decisions be tampered with?**
 A: Local mode: hash-protected (detects naive tampering). API mode: cryptographically signed (Ed25519, cannot forge).

package/docs/VERIFICATION_METHODS.md

@@ -93,5 +93,6 @@ So: **local is robust enough for the core policies** (exec, messaging, repo merg
 
 - **Local (bash):** Useful for privacy, offline, and the core use cases (exec allowlist/blocklist, messaging recipient, repo/PR limits). For full OAP parity and future policy packs, use **API mode**.
 - **API (default):** Recommended for production and when you want the same behavior as [APort in Goose](https://raw.githubusercontent.com/aporthq/.github/refs/heads/main/profile/APORT_GOOSE_ARCHITECTURE.md) and the full generic evaluator (JSON Schema, assurance, regions, evaluation_rules, signed decisions).
+- **`fail_open_on_api_error`:** In API mode, set this config option to `true` if you want API infrastructure errors (4xx/5xx, network failures) to return allow instead of deny. Genuine policy denials (HTTP 200 with `allow: false`) are **never** overridden. Default: `false` (fail-closed on API errors). Set via config YAML or env var `APORT_FAIL_OPEN_ON_API_ERROR=1`.
 
 The installer (`./bin/openclaw`) defaults to **API mode**; choose local only when you need to run without the network.

package/docs/frameworks/crewai.md

@@ -95,10 +95,15 @@ withAPortGuardrail(() => {
 });
 ```
 
+### How tool parameters are handled
+
+The Node middleware automatically spreads object tool inputs into the verification context. For example, `{ tool_input: { file_path: "/tmp/data.txt" } }` will pass `file_path` at the top level of the context, ensuring policies like `data.file.read.v1` receive required fields for validation.
+
 ## Config
 
 - **Config path:** `~/.aport/crewai/config.yaml`, or `.aport/config.yaml` in the project root.
 - **Mode:** `api` (default for production) or `local` (bash evaluator, no network). Same options as [LangChain](langchain.md) and OpenClaw.
+- **`fail_open_on_api_error`**: Set to `true` in config to allow tool execution when the APort API is unreachable (genuine policy denials are never overridden). Default: `false` (fail-closed).
 
 ## Suspend (kill switch)
 

package/docs/frameworks/langchain.md

@@ -58,10 +58,15 @@ const callback = new APortGuardrailCallback(); // optional: { configPath: '...',
 // On deny, the callback throws GuardrailViolationError.
 ```
 
+### How tool parameters are handled
+
+The Node middleware automatically parses JSON tool input and spreads parameters (e.g. `file_path`, `command`) into the verification context. This ensures policies like `data.file.read.v1` and `data.file.write.v1` receive the required `file_path` field at the top level for proper validation.
+
 ## Config
 
 - **Config:** `~/.aport/langchain/` or `.aport/config.yaml`
 - **Usage:** Add the callback to your agent (see above).
+- **`fail_open_on_api_error`**: Set to `true` in config to allow tool execution when the APort API is unreachable (genuine policy denials are never overridden). Default: `false` (fail-closed).
 
 ## Suspend (kill switch)
 

package/extensions/openclaw-aport/README.md

@@ -93,7 +93,7 @@ plugins:
 - **exec** is OpenClaw’s main “run something” tool: it can run the guardrail script (we delegate to the inner tool) or a real shell command (e.g. `mkdir`, `npm install`). By default we map **exec** → **system.command.execute.v1** and check the **command** against your passport’s **limits.system.command.execute.allowed_commands**. If `mkdir` (or another command) is not in that list, the policy denies with `oap.command_not_allowed`.
 - **Fix:** Add every command you need to **allowed_commands** in your passport (e.g. `mkdir`, `cp`, `ls`, `cat`, `echo`, `pwd`, `mv`, `touch`, `npx`, `open`). Re-run the passport wizard to get an expanded default list, or edit `~/.openclaw/aport/passport.json` (or `~/.openclaw/passport.json` for legacy) and add to `limits.system.command.execute.allowed_commands`. If the guardrail is ever run via **exec** (e.g. a skill runs `bash ~/.openclaw/.skills/aport-guardrail.sh ...`), include **`bash`** (or the full script path) in **allowed_commands** so that invocation is allowed; the wizard default includes `bash` and `sh`.
 - **Optional:** Set **mapExecToPolicy: false** in plugin config so **exec** is not mapped; then exec is treated as an unmapped tool and allowed (no command allowlist). Use only if you rely on other controls; this disables guardrail protection for shell commands.
-- **read, write, edit, etc.** (OpenClaw file/browser tools) have **no policy mapping** in this plugin, so they are **allowed** by default when `allowUnmappedTools` is true. A “read failed: ENOENT” is the tool failing (e.g. file not found), not the guardrail blocking. Tool→policy mapping and passport limits are documented in [TOOL_POLICY_MAPPING.md](../../docs/TOOL_POLICY_MAPPING.md) and [OPENCLAW_TOOLS_AND_POLICIES.md](../../docs/OPENCLAW_TOOLS_AND_POLICIES.md).
+- **read, write** are now mapped to `data.file.read.v1` and `data.file.write.v1` policies, enforcing path allowlists and blocked patterns. The LangChain/CrewAI middlewares automatically spread tool input parameters (e.g. `file_path`) into the verification context for proper API validation. **edit, browser, cron, etc.** remain unmapped and allowed by default when `allowUnmappedTools` is true. Tool→policy mapping and passport limits are documented in [TOOL_POLICY_MAPPING.md](../../docs/TOOL_POLICY_MAPPING.md) and [OPENCLAW_TOOLS_AND_POLICIES.md](../../docs/OPENCLAW_TOOLS_AND_POLICIES.md).
 
 ---
 

package/extensions/openclaw-aport/index.ts

@@ -8,7 +8,8 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { spawn } from "child_process";
 import { createHash, randomUUID } from "crypto";
-import { readFile, mkdir } from "fs/promises";
+import { readFile, mkdir, appendFile } from "fs/promises";
+import { appendFileSync, mkdirSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
 
@@ -175,6 +176,21 @@ const plugin = {
             passportFile: agentId ? null : passportFile,
             agentId,
           });
+          // Audit log for API mode (local mode is logged by the bash script via OPENCLAW_AUDIT_LOG)
+          const configDir = dirname(passportFile);
+          const auditLogPath = join(configDir, "audit.log");
+          const ctxSummary = typeof context.command === "string" ? context.command
+            : typeof context.file_path === "string" ? context.file_path
+            : typeof context.recipient === "string" ? context.recipient
+            : undefined;
+          logAuditEntry(auditLogPath, {
+            tool: effectiveToolName,
+            allow: Boolean(decision.allow),
+            policy: effectivePolicyName,
+            code: decision.reasons?.[0]?.code,
+            agentId: agentId || undefined,
+            context: ctxSummary,
+          });
         } else {
           decision = await verifyViaScript(scriptToolName, context, {
             guardrailScript,
@@ -501,3 +517,33 @@ function expandPath(path: string): string {
   }
   return path;
 }
+
+/**
+ * Write one-line audit entry matching bash guardrail format.
+ * Deny: sync (blocking). Allow: async (non-blocking). Best-effort: never throws.
+ */
+function logAuditEntry(
+  auditLogPath: string,
+  entry: { tool: string; allow: boolean; policy: string; code?: string; agentId?: string; context?: string },
+): void {
+  try {
+    const ts = new Date().toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
+    const code = entry.code || (entry.allow ? "oap.allowed" : "oap.denied");
+    let line = `[${ts}] tool=${entry.tool} allow=${entry.allow} policy=${entry.policy} code=${code}`;
+    if (entry.agentId) line += ` agent_id=${entry.agentId}`;
+    if (entry.context) {
+      const sanitized = entry.context.replace(/[\r\n]+/g, " ").replace(/"/g, '\\"').slice(0, 120);
+      line += ` context="${sanitized}"`;
+    }
+    line += "\n";
+    const dir = dirname(auditLogPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    if (!entry.allow) {
+      appendFileSync(auditLogPath, line, "utf8");
+    } else {
+      appendFile(auditLogPath, line, "utf8").catch(() => {});
+    }
+  } catch {
+    /* best-effort */
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/aport-agent-guardrails",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
   "workspaces": [
     "packages/*",