APort Agent Guardrails: Deterministic Pre-Action Authorization for AI Agents

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

APort Agent Guardrails is an open-source repository providing deterministic pre-action authorization for AI agents. It ensures that security guardrails are executed before any tool, command, or action is performed by an AI agent. This crucial design prevents prompt injection attacks from bypassing established policy checks, offering a robust layer of security for AI-driven systems.

Why Use and Benefits

Securing AI agents is paramount, and APort Agent Guardrails offers several compelling advantages for developers and teams:

Deterministic Enforcement: Guardrails operate via runtime hooks, not just prompt instructions, ensuring actions are verified before execution.
Fail-Closed Defaults: Verification failures automatically block risky actions, providing a secure-by-default posture.
Explicit Rollout Mode: Use --enforcement=warn to record deny decisions while allowing actions during policy tuning, enabling safe rollout.
Auditable Decisions: Every allow or deny decision is logged with context, providing a clear audit trail.
Open Standard Artifacts: Utilizes Open Agent Passport (OAP) v1.0 passport and decision formats for transparency.
Research-Backed Outcomes: Proven effectiveness in adversarial testbeds, demonstrating 0% successful breaches under restrictive OAP policy against top-tier attempts.
Low Latency at Production Scale: Cloud API verification boasts p50 ~53ms at N=1,000, ensuring minimal performance impact.
Comprehensive Security Documentation: Detailed SECURITY.md and SECURITY_MODEL.md provide insights into the project's security posture.

Installation

Getting started with APort Agent Guardrails is straightforward, whether you're protecting a GitHub repository or integrating runtime guardrails into your AI agent framework.

Protect a GitHub Repository:
To protect your GitHub repository in 60 seconds, run:


npx @aporthq/aport-agent-guardrails github

For blocking hosted enforcement on protected branches, use:


npx @aporthq/aport-agent-guardrails github --mode hosted --branches main,staging

Install Runtime Guardrails:
For runtime hooks, you can use the interactive installer or specify your framework:


npx @aporthq/aport-agent-guardrails
# or for a specific framework, e.g., Claude Code
npx @aporthq/aport-agent-guardrails claude-code

For Python users (e.g., LangChain, CrewAI, DeerFlow), first run the Node CLI for setup, then install the Python package:


uvx --from aport-agent-guardrails aport setup --framework=langchain
# or
pip install aport-agent-guardrails
aport setup --framework=langchain

Follow the printed instructions to install framework-specific Python packages and wire the provider/callback.

Examples

After installation, APort Agent Guardrails automatically runs when your agent uses tools. You can also test policy decisions directly from the command line.

Test Policy from CLI (Node):


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

The exit code indicates the decision: 0 for ALLOW, 1 for DENY.

Check Passport Status and Audit:

Passport & Audit: Stored in your APort framework state directory (e.g., ~/.cursor/aport/, ~/.aport/langchain/aport/).
Audit Log: config_dir/aport/audit.log contains one line per decision.
Last Decision: config_dir/aport/decision.json holds the latest OAP v1.0 format decision.