Aport Agent Guardrail

Pre-action authorization for AI agents. Installs an OpenClaw before_tool_call hook that evaluates every tool call against a passport and policy before execut...

Security Scan

The skill's instructions, required runtime, and optional environment variables are coherent with a pre-action guardrail for OpenClaw agents, but it relies on running an npm package via npx (remote code execution at install time) and a hosted API mode that will send tool context — both of which you should review before use.

Purpose & Capability

Name/description match the instructions: the skill adds a before_tool_call hook for OpenClaw, documents local and hosted modes, and requires Node/npx to install @aporthq/aport-agent-guardrails. Nothing requested is disproportionate to adding a guardrail.

Instruction Scope

SKILL.md instructs the user/agent to run npx to install the enforcement package, create wrapper scripts under ~/.openclaw/, register a plugin and write passport/decision/audit files. These actions are expected for a hook-based guardrail, but they do modify the agent runtime and filesystem in the user's home directory.

Install Mechanism

No install spec in the registry entry (instruction-only), but the SKILL.md directs using npx to fetch and run an npm package. npx executes code downloaded from the npm registry at install time — this is a normal delivery for Node tools but is higher-risk than a purely local script because it runs remote code; auditing the package source before running npx is advised.

Credentials

All environment variables are optional and only used for API/hosted mode (APORT_API_URL, APORT_AGENT_ID, APORT_API_KEY). Local/offline mode requires no envvars or credentials. The requested scopes are proportional to the stated hosted-mode capabilities.

Persistence & Privilege

The skill installs a persistent OpenClaw hook and wrapper scripts under ~/.openclaw/ so the guardrail runs on every tool call (expected behavior). It is not force-enabled via always:true in the registry metadata. Users should note it modifies their agent runtime and filesystem in their user profile.

Assessment

This skill appears to do what it says, but before installing: 1) Review the @aporthq/aport-agent-guardrails package source on GitHub and the npm package published version to ensure it matches what you expect (npx will execute remote code). 2) Prefer local mode if you want no data sent remotely; if you use hosted/API mode, confirm exactly what 'context' is sent and limit the API key's permissions. 3) Check and lock filesystem permissions on ~/.openclaw/aport/passport.json and audit logs. 4) Back up any existing OpenClaw config before registering the plugin. If you are not comfortable running third-party npm code with npx, consider cloning the repository and inspecting/locking the version before executing.

Pre-action authorization for AI agents. Installs an OpenClaw before_tool_call hook that evaluates every tool call against a passport (identity + capabilities + limits) and policy before it executes. If the policy denies the call, the tool does not run.

This skill provides setup instructions. The enforcement logic comes from the @aporthq/aport-agent-guardrails npm package, which is open-source (Apache 2.0) and can be audited before installation.

When to use this skill

• User wants to add guardrails to their AI agent setup
• User asks about protecting against unauthorized tool calls
• User wants pre-action authorization for OpenClaw, IronClaw, or PicoClaw agents
• User needs audit trails for AI agent actions

How it works

User Request -> Agent Decision -> APort Hook -> [ALLOW/DENY] -> Tool Execution
                                      |
                               Policy + Passport

1. Agent decides to use a tool (e.g., run a shell command)
2. OpenClaw fires the before_tool_call hook
3. APort loads the passport, maps the tool to a policy, checks allowlists and limits
4. Decision: ALLOW (tool runs) or DENY (tool blocked)
5. Decision is logged to the audit trail

Enforcement runs in the OpenClaw hook layer, not in agent prompts. However, like any application-layer security control, it depends on the integrity of the runtime environment (OS, OpenClaw, filesystem). See the Security Model for trust boundaries.

Prerequisites

Check these before starting:

1. Node.js 18+ and npx — run node -v to verify (must show v18 or higher)
2. OpenClaw (or compatible runtime) — the hook registers as an OpenClaw plugin

Installation

Quick start (recommended)

npx @aporthq/aport-agent-guardrails

The wizard will:

1. Create or load a passport (local file or hosted from aport.io)
2. Configure capabilities and limits
3. Register the OpenClaw plugin (adds before_tool_call hook)
4. Set up wrapper scripts under ~/.openclaw/

After install, the hook runs on every tool call automatically.

With hosted passport (optional)

npx @aporthq/aport-agent-guardrails <agent_id>

Get agent_id at aport.io for signed decisions, global suspend, and centralized audit dashboards.

From source

git clone https://github.com/aporthq/aport-agent-guardrails
cd aport-agent-guardrails
./bin/openclaw

What gets installed

Files created under ~/.openclaw/:

• Plugin config in config.yaml or openclaw.json
• Wrapper scripts in .skills/aport-guardrail*.sh
• aport/passport.json (local mode only)
• aport/decision.json and aport/audit.log (created at runtime)

Total disk usage: ~100KB for scripts + passport/decision files.

Usage

After installation, the hook runs automatically on every tool call:

# Allowed command — hook approves, tool executes
agent> run git status
# APort: passport checked -> policy evaluated -> ALLOW

# Blocked command — hook denies, tool does not run
agent> run rm -rf /
# APort: passport checked -> blocked pattern detected -> DENY

Testing the hook manually

# Test allowed command (exit 0 = ALLOW)
~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"ls"}'

# Test blocked command (exit 1 = DENY)
~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}'

Decision logs:

• Latest decision: ~/.openclaw/aport/decision.json
• Audit trail: ~/.openclaw/aport/audit.log

Modes

Local mode (default)

• All evaluation happens on your machine, zero network calls
• Passport stored locally at ~/.openclaw/aport/passport.json
• Works offline
• Note: local passport file must be protected from tampering (standard filesystem permissions)

API mode (optional)

• Passport hosted in the aport.io registry (not stored locally)
• Signed decisions (Ed25519) for tamper-evident audit trails
• Global suspend across all systems
• Centralized compliance dashboards
• Sends tool name + context to API (does not send file contents, env vars, or credentials)

Environment variables

All optional. Local mode requires no environment variables.

Variable	When used	Purpose
APORT_API_URL	API mode	Override endpoint (default: https://api.aport.io)
APORT_AGENT_ID	Hosted passport	Passport ID from aport.io
APORT_API_KEY	If API requires auth	Authentication token

Default protections

• Shell commands — Allowlist enforcement, 40+ blocked patterns (rm -rf, sudo, chmod 777, etc.), interpreter bypass detection
• Messaging — Rate limits, recipient allowlist, channel restrictions
• File access — Path restrictions, blocks access to .env, SSH keys, system directories
• Web requests — Domain allowlist, SSRF protection, rate limiting
• Git operations — PR size limits, branch restrictions

Tool name mapping

Agent action	Tool name	Policy checks
Shell commands	system.command.execute	Allowlist, blocked patterns
Messaging (WhatsApp/Email/Slack)	messaging.message.send	Rate limits, recipient allowlist
PRs	git.create_pr, git.merge	PR size, branch restrictions
MCP tools	mcp.tool.execute	Server/tool allowlist
File read/write	data.file.read, data.file.write	Path restrictions
Web requests	web.fetch, web.browser	Domain allowlist

Troubleshooting

Problem	Fix
Plugin not enforcing	Check openclaw plugin list shows aport-guardrail
Connection refused (API mode)	Verify APORT_API_URL is reachable
Tool blocked unexpectedly	Check ~/.openclaw/aport/decision.json for deny reason
npx not found	Install Node.js 18+: https://nodejs.org

Documentation

• Source code (Apache 2.0)
• QuickStart: OpenClaw Plugin
• Security Model & Trust Boundaries
• Hosted Passport Setup
• OAP Specification