Skip to content

aporthq/aport-agent-guardrails

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

105 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

APort logo APort Agent Guardrails

npm PyPI License Tests Node Python OpenClaw

npm β€’ PyPI β€’ Website β€’ Docs β€’ Meet Porter β€’ Quick Start β€’ Security


Deterministic pre-action authorization for AI agents. Guardrails run before tool execution, so prompt injection cannot bypass policy checks.

CTF Evidence

From the live APort Vault adversarial testbed:

Metric Result
Total authorization decisions observed 4,437
Total attack sessions observed 1,151
Level 5 ("Vault") restrictive attempts 879
Level 5 ("Vault") successful breaches 0
Level 5 restrictive success rate 0%
Permissive baseline success rate (for comparison) 74.6%

Start Here

Install in 30 seconds

npx @aporthq/aport-agent-guardrails
  • Choose your framework: openclaw, cursor, claude-code, langchain, crewai, deerflow, n8n
  • OpenClaw direct: npx @aporthq/aport-agent-guardrails openclaw
  • Hosted passport: npx @aporthq/aport-agent-guardrails openclaw <agent_id>

Why Developers and teams trust APort

  • Deterministic enforcement: runtime hook, not prompt instructions
  • Fail-closed defaults: verification failures block risky actions
  • Auditable decisions: each allow/deny is logged with context
  • Open standard artifacts: Open Agent Passport (OAP) v1.0 passport and decision formats
  • Research-backed outcomes: in a live adversarial testbed, permissive-policy success was 74.6% vs 0% under restrictive OAP policy (879 top-tier attempts)
  • Low latency at production scale: cloud API verification p50 ~53ms at N=1,000
  • Security docs: SECURITY.md, SECURITY_MODEL.md
  • Backed by Peer-reviewed research: arXiv preprint (Mar 2026)

Fast path by persona

Brand personality (optional)

Security should feel rigorous, not intimidating. Meet Porter, the APort mascot used across the product experience: Meet Porter.

Deeper background (threat model, rationale, evidence)

The security concern is that agent tools and skills can execute sensitive actions (files, commands, external calls). APort addresses this by verifying each tool call against a passport and policy limits before execution. This reduces prompt-injection and β€œagent decided wrong” risk from runtime behavior to policy configuration.


πŸ”Œ Supported frameworks

APort Agent Guardrail adapters are available per framework; the same passport and policies apply. Node users: npx @aporthq/aport-agent-guardrails (then choose framework) or npx @aporthq/aport-agent-guardrails <framework>. Python users (LangChain/CrewAI/DeerFlow): run the same CLI for the wizard and config, then install the framework adapter/provider package shown in the framework doc.

Two ways to use APort: (1) Guardrails (CLI/setup) β€” run the installer to create your passport and config; (2) Core (library) β€” use the OAPGuardrailProvider (docs/PROVIDER.md) in your app so each tool call is verified. One provider per language (Python + TypeScript), works with any framework. Framework docs: OpenClaw, Cursor, Claude Code, LangChain, CrewAI, DeerFlow, n8n.

CLI-supported frameworks: openclaw, langchain, crewai, cursor, claude-code, deerflow, n8n. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. See Deployment readiness.

Framework Doc Integration Install
OpenClaw docs/frameworks/openclaw.md Native GuardrailProvider or plugin npm i @aporthq/aport-agent-guardrails-core && npx @aporthq/aport-agent-guardrails openclaw
Cursor docs/frameworks/cursor.md beforeShellExecution / preToolUse hooks β†’ writes ~/.cursor/hooks.json. Runtime enforcement is the bash hook; the Node package @aporthq/aport-agent-guardrails-cursor is a helper only (Evaluator, getHookPath()). npx @aporthq/aport-agent-guardrails cursor
Claude Code docs/frameworks/claude-code.md PreToolUse hook β†’ writes ~/.claude/settings.json (Claude Code format; not Cursor). npx @aporthq/aport-agent-guardrails claude-code
LangChain / LangGraph docs/frameworks/langchain.md Python: APortCallback (on_tool_start) npx @aporthq/aport-agent-guardrails langchain then pip install aport-agent-guardrails-langchain + aport-langchain setup
CrewAI docs/frameworks/crewai.md Python: @before_tool_call hook, register_aport_guardrail npx @aporthq/aport-agent-guardrails crewai then pip install aport-agent-guardrails-crewai + aport-crewai setup
DeerFlow docs/frameworks/deerflow.md Python: generic OAP provider wiring in DeerFlow config npx @aporthq/aport-agent-guardrails deerflow then follow printed uv/config steps
n8n docs/frameworks/n8n.md Coming soon β€” custom node and runtime in progress β€”

Install via npx @aporthq/aport-agent-guardrails <framework> (or choose when prompted). OpenClaw can also use the full installer flow. For LangChain and CrewAI, the Node CLI only runs the wizard and writes config; you must then run the printed pip install and setup commands to install the runtime adapter. Python adapters on PyPI; Node adapters on npm (same version as the CLI).

Passport path: Each framework has its own default passport path (where that framework stores data): e.g. Cursor β†’ ~/.cursor/aport/passport.json, OpenClaw β†’ ~/.openclaw/aport/passport.json, LangChain β†’ ~/.aport/langchain/aport/passport.json. The passport wizard’s first question is β€œPassport file path [default]:” β€” press Enter for the framework default or type a different path. In non-interactive mode (e.g. CI) use --output /path/to/passport.json to choose the path. Roadmap: docs/FRAMEWORK_ROADMAP.md.

Using SDKs or middleware directly: If you prefer to integrate with the APort API from your own app (no CLI/framework installer), use the official SDKs and middleware: Node β€” @aporthq/sdk-node, @aporthq/middleware-express; Python β€” aporthq-sdk-python, aporthq-middleware-fastapi.


πŸš€ Quick Start

Prerequisites: For the setup wizard you need Node 18+ (or use the Python CLI below). jq is needed for local/bash guardrail. No clone required.

1. Run the setup β€” Choose your framework when prompted (or pass it). Same wizard for everyone.

Node (Cursor, OpenClaw, or to create config for any framework):

npx @aporthq/aport-agent-guardrails
# or: npx @aporthq/aport-agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n

Python (LangChain or CrewAI only): Run the wizard via the Node command above, then install the Python adapter and run the framework setup (see the printed next steps). Or use the Python CLI to see the exact commands:

pip install aport-agent-guardrails
aport setup --framework=langchain   # prints: npx ... langchain, then pip install aport-agent-guardrails-langchain, aport-langchain setup
# or --framework=crewai for CrewAI

Then run the printed npx command to create passport and config, and the printed pip / aport-<framework> setup to install the adapter.

This runs the passport wizard and writes config for your framework. Follow the next steps printed at the end (e.g. restart Cursor; or for LangChain/CrewAI: pip install aport-agent-guardrails-langchain + aport-langchain setup).

2. Hosted passport (optional) β€” If you already have an agent_id from aport.io, use it to skip the wizard: npx @aporthq/aport-agent-guardrails openclaw <agent_id>. See Hosted passport setup.

3. Test that policy runs β€” After setup, the guardrail runs automatically when your agent uses tools (Cursor hook, LangChain callback, OpenClaw plugin, etc.). To try allow/deny from the command line (any framework), use the installed aport-guardrail command (Node) or call the evaluator from Python; both use your existing passport from the framework config dir (e.g. ~/.cursor/aport/, ~/.aport/langchain/aport/).

Node:

aport-guardrail system.command.execute '{"command":"ls"}'      # ALLOW (safe)
aport-guardrail system.command.execute '{"command":"rm -rf /"}'  # DENY (blocked pattern)
# Exit: 0 = ALLOW, 1 = DENY

(If you use npx without -g, run npx aport-guardrail ....)

Python: Use the guardrail in your app (e.g. add APortCallback() to your LangChain agent, or register_aport_guardrail() for CrewAI). The guardrail runs on every tool call. To test allow/deny from the shell without Node, use npx aport-guardrail ... as above, or see your framework doc for in-app testing.

Check passport status and audit:

What Where
Passport & audit Stored in your framework config dir (e.g. ~/.cursor/aport/, ~/.openclaw/aport/, ~/.aport/langchain/aport/). Same for all frameworks.
Audit log config_dir/aport/audit.log β€” one line per decision (timestamp, tool, allow/deny, policy, context).
Last decision config_dir/aport/decision.json (OAP v1.0 format).

Your framework doc (Cursor, OpenClaw, LangChain, CrewAI) describes where the config dir is and any framework-specific status commands.

πŸ“– Per-framework: OpenClaw Β· Cursor Β· Claude Code Β· LangChain Β· CrewAI Β· DeerFlow Β· n8n
🌐 Hosted passport: Use agent_id from aport.io


πŸ”’ Enforcement Options

OpenClaw Plugin βœ… AGENTS.md only ⚠️
Deterministic Yes No
Bypass risk None High
Recommended Yes Only if plugin unavailable

Plugin (recommended): Platform runs the guardrail before every tool; the model cannot skip it. This repo implements the plugin (before_tool_call) integrationβ€”Option 2 in the APort Γ— OpenClaw integration proposal.
AGENTS.md: Agent is instructed to call the guardrail; best-effort only.


πŸ”Œ Verification methods (local vs API)

Default and recommended: API mode β€” full OAP policy evaluation (JSON Schema, assurance, regions, evaluation rules from policy JSON, signed decisions). The setup wizard defaults to API when you choose a mode.

Fail-closed by default: If the evaluator cannot find a passport or guardrail script (e.g. first run, wrong config dir), it denies the tool call (oap.misconfigured). For legacy allow-when-missing behavior, set fail_open_when_missing_config: true in your config or APORT_FAIL_OPEN_WHEN_MISSING_CONFIG=1 in the environment.

Mode Best for Full OAP? Network
API (default) Production, full policy parity, new policy packs without code changes βœ… Yes (api.aport.io or self-hosted)
Local (bash) Privacy, offline, air-gapped Subset only (hand-coded limits for exec, messaging, repo) No

API mode can use either a local passport file (sent in the request body; not stored) or agent_id only: set APORT_AGENT_ID to your hosted passport’s agent ID and the API fetches the passport from the registry β€” no passport JSON file needed. See Hosted passport setup.

Deep dive (what each supports, comparison table): Verification methods.


⚑ Performance

Guardrail verification latency from the latest preprint benchmark set (N=1,000).

Mode p50 p95 p99 N
Cloud API (agent_id, pack in path) 53ms 63ms 76ms 1,000
Cloud API (agent_id, policy in body) 53ms 62ms 77ms 1,000
Cloud API (passport in body, pack in path) 54ms 63ms 74ms 1,000
Cloud API (passport in body, policy in body) 53ms 63ms 71ms 1,000
Local policy evaluation 174ms 243ms 358ms 1,000

Source: Before the Tool Call: Deterministic Pre-Action Authorization for Autonomous AI Agents


πŸ“ How It Works (expand)

πŸ“ How It Works

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1','secondaryColor':'#e0f2fe','tertiaryColor':'#bae6fd'}}}%%
sequenceDiagram
  autonumber
  participant User as πŸ‘€ User
  participant OC as πŸ¦€ OpenClaw
  participant Hook as πŸ”’ before_tool_call
  participant Plugin as πŸ›‘οΈ APort Plugin
  participant Guard as πŸ“‹ Guardrail

  User->>OC: "Run: rm -rf /tmp"
  activate OC
  OC->>Hook: tool call (exec.run, params)
  activate Hook
  Hook->>Plugin: before_tool_call(exec.run, params)
  activate Plugin
  Note over Plugin: Map tool β†’ policy<br/>exec.run β†’ system.command.execute.v1
  Plugin->>Guard: evaluate(passport, policy, context)
  activate Guard
  Note over Guard: API or local script<br/>passport + limits
  Guard-->>Plugin: DENY (blocked pattern)
  deactivate Guard
  Plugin-->>Hook: block: true, blockReason
  deactivate Plugin
  Hook-->>OC: Tool blocked
  deactivate Hook
  OC-->>User: ❌ Action blocked by policy
  deactivate OC
Loading

Flow (high level):

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1'}}}%%
flowchart TB
  subgraph User["πŸ‘€ User"]
    A[User request]
  end
  B[πŸ¦€ OpenClaw: tool call]
  C[πŸ”’ before_tool_call hook]
  D[πŸ›‘οΈ APort plugin]
  E[πŸ“‹ Guardrail: passport + policy]
  F{Decision}
  G[βœ… ALLOW β€” tool runs]
  H[❌ DENY β€” tool blocked]
  A --> B --> C --> D --> E --> F
  F --> G
  F --> H
  style A fill:#0277bd,stroke:#01579b,stroke-width:2px,color:#fff
  style B fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#fff
  style C fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff
  style D fill:#ff6f00,stroke:#bf360c,stroke-width:3px,color:#fff
  style E fill:#ff6f00,stroke:#bf360c,stroke-width:2px,color:#fff
  style F fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
  style G fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff
  style H fill:#c62828,stroke:#b71c1c,stroke-width:2px,color:#fff
Loading
User β†’ "Delete all log files"
         ↓
   OpenClaw: tool "exec.run"
         ↓
   πŸ”’ before_tool_call hook
         ↓
   πŸ›‘οΈ APort plugin β†’ guardrail (passport + policy)
         ↓
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   βœ… ALLOW            ❌ DENY
   Tool runs           Tool blocked

Key: The platform enforces policy. The AI cannot skip this check.


πŸ›οΈ Security model (three layers) (expand)

πŸ›οΈ Security model (three layers)

APort enforces identity β†’ authorization β†’ audit before any tool runs. This repo implements the plugin (Option 2) integration: OpenClaw calls the APort extension in before_tool_call; the extension uses either local script or API to evaluate policy.

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1'}}}%%
graph TB
  subgraph L1["Layer 1: Identity (Who)"]
    A[Agent Passport<br/>OAP v1.0 / W3C DID]
    B[Owner, contact, org]
    C[Assurance level L0–L3]
  end

  subgraph L2["Layer 2: Authorization (What)"]
    D[Policy packs<br/>code.*, data.*, messaging.*]
    E[Graduated controls<br/>Max amounts, daily caps]
    F[Context-aware rules<br/>Branch allowlist, PII filters]
  end

  subgraph L3["Layer 3: Audit (Proof)"]
    G[Decision receipts<br/>Ed25519 in API mode]
    H[Audit trail<br/>Allow/deny logged]
    I[Kill switch<br/>Local file or global via API]
  end

  A --> D
  B --> D
  C --> D
  D --> G
  E --> G
  F --> G
  G --> H
  H --> I

  style A fill:#0277bd,stroke:#01579b,stroke-width:2px,color:#fff
  style D fill:#ff6f00,stroke:#bf360c,stroke-width:2px,color:#fff
  style G fill:#6a1b9a,stroke:#4a148c,stroke-width:2px,color:#fff
Loading
  • Local-first: Passport and policy live on your machine (or in repo); no cloud required for basic enforcement.
  • Fail-closed: Missing or invalid passport β†’ deny.
  • Opt-in cloud: Use API mode for global kill switch, signed receipts, and team sync.

What APort Protects

βœ… 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 + 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

Application-layer security model: APort enforces policies at the agent action layer (between agent decision and tool execution). It operates within the OS trust boundaryβ€”standard for authorization systems like OAuth, IAM, and policy engines.

For production: Use API mode (mode: api with agent_id) for cryptographically signed decisions, protected passports, and global suspend. See docs/SECURITY_MODEL.md for full threat model, attack scenarios, and best practices.


🌐 When to use API vs local

Use local when Use API (default) when
Single developer, no cloud Team; same policies across machines
Offline or air-gapped You want global kill switch (<15s)
Plain audit logs are enough You need signed receipts (e.g. SOC 2, compliance)
No API key / self-host not ready Registry checks, analytics, or policy marketplace

See Verification methods for a detailed comparison.


πŸ“– Example outcomes

Scenario Without APort With APort
Oversized PR Agent creates 1200-file PR Denied: β€œPR size exceeds limit of 500 files”
PII export Agent exports SSN/driver’s license Denied: β€œPII export not allowed” (data.export policy)
Kill switch Manually edit config on every machine API: suspend passport once β†’ all agents deny in <15s

πŸ“œ Commands (after install)

Node: When you install via npm install @aporthq/aport-agent-guardrails (or use npx), these commands are available:

Command Purpose
agent-guardrails Main entry β€” prompt for framework or pass one: agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n. Args after the framework are passed through (e.g. agent-guardrails openclaw <agent_id>).
aport OpenClaw one-command setup (passport + plugin + wrappers). Optional: aport <agent_id> for hosted passport.
aport-guardrail Run guardrail check from the CLI (e.g. aport-guardrail system.command.execute '{"command":"ls"}'). Uses passport from your framework config dir.

Python: After pip install aport-agent-guardrails you get aport (setup helper). For LangChain or CrewAI, install the adapter and framework setup:

Command Purpose
aport setup --framework=langchain Print next-step commands (npx wizard, then pip install aport-agent-guardrails-langchain, aport-langchain setup).
aport setup --framework=crewai Same for CrewAI: npx wizard, then pip install aport-agent-guardrails-crewai, aport-crewai setup.
aport-langchain setup LangChain config and wizard (after installing aport-agent-guardrails-langchain).
aport-crewai setup CrewAI config and wizard (after installing aport-agent-guardrails-crewai).

Use the framework-specific doc for where config and passport live and for any extra steps (e.g. Cursor: restart IDE; LangChain/CrewAI: add callback/hook in code).

Contributors: repo layout and dev scripts (build, test, release) are in docs/REPO_LAYOUT.md and CONTRIBUTING.md.


πŸ“š Documentation

Doc Description
QuickStart: OpenClaw Plugin 5-minute OpenClaw setup
Hosted passport setup Use passport from aport.io β€” npx ... openclaw <agent_id> or choose hosted in wizard
Verification methods (local vs API) Deep dive: bash vs API evaluator
Quick Start Guide Passport wizard, copy-paste option
OpenClaw Local Integration API, Python example
Tool / Policy Mapping Tool names β†’ policy packs
Repo Layout For contributors: package layout (bin/, src/, extensions/)
Upgrade Guide Migrating between versions (e.g. 0.1.0 β†’ 1.0.0)
Frameworks Per-framework setup and how guardrails run
β†’ OpenClaw before_tool_call plugin
β†’ Cursor beforeShellExecution / preToolUse hooks, ~/.cursor/hooks.json
β†’ Claude Code PreToolUse hook, ~/.claude/settings.json
β†’ LangChain / LangGraph APortCallback handler
β†’ CrewAI @before_tool_call hook, register_aport_guardrail
β†’ DeerFlow Generic provider wiring via DeerFlow config.yaml
β†’ n8n Custom node, branch on allow/deny
Framework roadmap Support status and roadmap

πŸ—οΈ Architecture (expand)

πŸ—οΈ Architecture

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1','secondaryColor':'#e0f2fe','tertiaryColor':'#bae6fd'}}}%%
flowchart LR
  subgraph Runtime["Runtime"]
    OC[πŸ¦€ OpenClaw / IronClaw]
    S[Sandbox, channels, tools]
    OC --> S
  end
  subgraph Policy["Pre-action policy"]
    AP[πŸ›‘οΈ APort Guardrails]
    P[Passport, limits, audit]
    AP --> P
  end
  Runtime <-->|before every tool| Policy
  style OC fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#fff
  style S fill:#6a1b9a,stroke:#4a148c,stroke-width:1px,color:#fff
  style AP fill:#ff6f00,stroke:#bf360c,stroke-width:3px,color:#fff
  style P fill:#ff6f00,stroke:#bf360c,stroke-width:1px,color:#fff
Loading

Where verification runs (this repo):

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1'}}}%%
flowchart TB
  subgraph Machine["Your machine"]
    OC[πŸ¦€ OpenClaw]
    Plug[πŸ›‘οΈ APort plugin<br/>before_tool_call]
    Guard[πŸ“‹ Guardrail]
    OC --> Plug
    Plug --> Guard
  end
  Guard -->|API mode| API[πŸ“‘ api.aport.io<br/>or self-hosted]
  Guard -->|Local mode| Bash[πŸ“œ aport-guardrail-bash.sh]
  style OC fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#fff
  style Plug fill:#ff6f00,stroke:#bf360c,stroke-width:3px,color:#fff
  style Guard fill:#ff6f00,stroke:#bf360c,stroke-width:2px,color:#fff
  style API fill:#2e7d32,stroke:#1b5e20,stroke-width:1px,color:#fff
  style Bash fill:#6b7280,stroke:#374151,stroke-width:1px,color:#fff
Loading
  • OpenClaw = Runtime (sandbox, channels, tools).
  • APort plugin = Pre-action hook; calls guardrail (API or local script).
  • Guardrail = Passport + policy evaluation; allow/deny before the tool runs.

Defense in depth: policy before execution, runtime safety during execution.


🀝 Contributing

Contributions welcome: policy packs, framework adapters, docs. See CONTRIBUTING.md.


πŸ“„ License

Apache 2.0 β€” see LICENSE.

Open-core: Local evaluation and CLI in this repo are open source (Apache 2.0). api.aport.io is a separate product for cloud features (signed receipts, global kill switch, team sync). See APort Γ— OpenClaw proposal for free vs. paid tiers.


πŸ”— Links


Made with ❀️ by [Uchi](https://github.com/uchibeke/)

About

Pre-action authorization guardrails for AI agents - Works with OpenClaw, Claude Code, LandChain, CrewAI and others

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors