Agent Passport

OAuth for the agentic era. Consent-gating for ALL sensitive agent actions. 75+ data-driven threat definitions with auto-updates (like antivirus signatures)....

Security Scan

The skill's files, required binaries, and runtime instructions are consistent with a local consent/mandate ledger for gating sensitive agent actions; nothing in the package demands unrelated secrets or exotic installs, though there are test vectors and optional “Pro/Live” features that can contact external services if enabled.

Purpose & Capability

Name/description (consent-gating, mandate ledger, injection/SSRF/path guards) match the provided scripts and docs. Required binaries (jq, bc, xxd, head, date, mkdir) are reasonable for a shell-based ledger and scanner. The single required env var (AGENT_PASSPORT_LEDGER_DIR) is appropriate for storing the local ledger. The README/docs describe optional Pro/Live features (auto-updates, Agent Bridge) that would use network APIs, but those are not required by default and are documented separately.

Instruction Scope

Runtime instructions tell the agent to call the shipped CLI script (mandate-ledger.sh) to check and log sensitive actions — this is exactly the core purpose. The SKILL.md and tests include explicit prompt-injection examples (e.g., 'ignore previous instructions') used as detection test vectors; the scanner flagged that phrase. The instructions do allow an agent to run local shell commands (init, create-from-template) if the agent chooses to act, which is expected for this skill but means users should review scripts before allowing autonomous execution.

Install Mechanism

No install spec is provided (instruction-only from the platform perspective). The repository includes shell scripts that the agent will invoke locally; there is no automatic remote download or extract specified in the manifest. This is lower risk than an install that fetches arbitrary code from an external URL.

Credentials

Only AGENT_PASSPORT_LEDGER_DIR is declared as required. Documentation mentions optional environment variables and API keys for Live/Pro modes (AGENT_PASSPORT_API_KEY, AGENT_PASSPORT_BASE_URL, AGENT_PASSPORT_LOCAL_LEDGER) but they are not required to run the local mode. No unrelated cloud credentials or high-privilege secrets are demanded by default.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It stores state under a user-controlled ledger directory (defaults to ~/.openclaw/agent-passport or AGENT_PASSPORT_LEDGER_DIR). There are no built-in system-wide or privileged changes in the provided scripts; the code includes scan patterns to detect persistence but does not itself create daemons or cron entries.

Scan Findings in Context

[scan-med-injection-ignore-previous] expected: The scanner flagged prompt-injection strings (e.g., 'ignore previous instructions') inside the repo. These appear to be deliberate test vectors and examples used by the skill's own injection-shield tests (scripts/test-v2.3.sh and example SKILL.md/test files). Presence is expected for a scanner-quality suite, but treat any such text seriously if you plan to let an autonomous agent consume untrusted external content.

Assessment

What to consider before installing: - This skill runs a local shell script (mandate-ledger.sh) to authorize and log sensitive actions; review that script before allowing the agent to execute it. It will create files under the ledger directory (defaults to ~/.openclaw/agent-passport or whatever you set in AGENT_PASSPORT_LEDGER_DIR). - The package contains test vectors that deliberately include prompt-injection phrases; those are used to validate the shield functionality — their presence in the repo is intentional, not evidence of compromise. - The default/local mode is offline and does not require extra credentials. If you enable Pro/Live features (auto-updates, Agent Bridge), the skill will contact external services and you will need to provide API keys (AGENT_PASSPORT_API_KEY, etc.). Only enable those modes if you trust the remote service and are comfortable supplying credentials. - If you plan to allow the agent to autonomously run commands, restrict autonomous privileges until you inspect the scripts and consider enabling local-only mode (export AGENT_PASSPORT_LOCAL_LEDGER=true) and avoid enabling auto-update/live features until vetted. - If you are unsure, run the scripts in an isolated test environment (non-production account or container) first and inspect the ledger contents and audit logs the skill will create.

Agent Passport (OpenClaw)

30-Second Setup

# Initialize and register your agent
./mandate-ledger.sh init agent:my-assistant "Your Name" "personal assistant" "openclaw"

# Grant dev tool access (git, npm, docker, etc.)
./mandate-ledger.sh create-from-template dev-tools

# That's it! The agent will now check permissions before sensitive actions.

Templates available: dev-tools · email-team <domain> · file-ops <path> · web-research · safe-browsing · coding · email-assistant · read-only · full-auto Run ./mandate-ledger.sh templates to see all options.

---

⚡ Agent Behavioral Contract

If you are an agent reading this skill, these are your rules. Follow them.

When to Check

Before performing ANY of these actions, you MUST call check-action first:

Action	Category	Example target
Running a shell command	system	"git pull", "npm install"
Sending a message/email	communication	"[e-mail]"
Writing/deleting a file	data	"/path/to/file.txt"
Making an API call with side effects	external_api	"api.github.com"
Spending money	financial	"merchant_amazon" with amount
Acting publicly as the user	identity	"twitter_post"

You do NOT need to check: reading files, web searches, internal reasoning, or anything with no side effects.

How to Check

SCRIPT_DIR="$HOME/.openclaw/skills/agent-passport/scripts"

result=$($SCRIPT_DIR/mandate-ledger.sh check-action "<your_agent_id>" "<category>" "<target>" [amount])

Parse the result:

• authorized: true → proceed, then log the action afterward
• authorized: false → STOP. Ask the user.
• If response includes kill_switch: true or reason Kill switch engaged → STOP immediately and ask user to run mandate-ledger.sh unlock

The Flow

1. You want to do something sensitive
2. Call check-action
3. IF authorized:
   a. Do the thing
   b. Log it: mandate-ledger.sh log-action <mandate_id> <amount> "<description>"
4. IF denied:
   a. Tell the user what you want to do and why
   b. Suggest a mandate (show scope, duration, constraints)
   c. Wait for approval
   d. If approved, create the mandate, then proceed

How to Ask for Permission

When denied, present it clearly and concisely:

I need to [ACTION] but don't have a mandate for it.

📋 [CATEGORY]: [what you want to do]
🎯 Target: [specific target]
⏰ Suggested duration: [reasonable TTL]

Want me to set this up? I can also create a broader mandate if you'd
prefer (e.g., all emails to @company.com for 30 days).

DO NOT:

• Bypass the check and do it anyway
• Ask repeatedly for the same thing if denied
• Create mandates yourself without user approval
• Pretend you checked when you didn't

DO:

• Suggest templates when appropriate ("Want me to set up dev-tools?")
• Batch similar requests ("I'll need to run several git commands — want a dev-tools mandate?")
• Log every action after completion
• Mention remaining limits when relevant ("3/20 daily emails used")

First-Time Setup

If check-action returns "hint": "templates", the ledger is empty. Guide the user:

Agent Passport isn't set up yet. It takes 30 seconds:

  mandate-ledger.sh init agent:me "Your Name" "assistant" "openclaw"
  mandate-ledger.sh create-from-template dev-tools

Want me to run this for you?

Logging Actions

After every authorized action, log it:

$SCRIPT_DIR/mandate-ledger.sh log-action "<mandate_id>" <amount> "<description>"

• For financial: amount = dollars spent
• For everything else: amount = 1
• Description should be human-readable: "Sent email to [e-mail] re: Q1 report"

Kill Switch Behavior

If the user engages the kill switch, all operations are frozen until unlocked.

./mandate-ledger.sh kill "user requested freeze"
./mandate-ledger.sh unlock

Agent behavior when kill switch is active:

• Do not attempt sensitive actions
• Do not retry check-action in a loop
• Tell user operations are blocked and request explicit unlock

---

Overview

Agent Passport provides a consent layer for agent autonomy. Instead of all-or-nothing permissions, users grant mandates with specific constraints:

"I authorize this agent to [ACTION] with [CONSTRAINTS] until [EXPIRY]"

This isn't just about purchases — it's consent-gating for all sensitive actions.

Action Categories

Category	Examples	Typical Constraints
financial	Purchases, transfers, subscriptions	Spending cap, merchant allowlist
communication	Emails, messages, tweets, posts	Recipient allowlist, rate limit
data	Delete files, edit docs, DB writes	Path allowlist, require backup
system	Shell commands, installs, configs	Command allowlist, no sudo
external_api	Third-party API calls	Service allowlist, rate limit
identity	Public actions "as" the user	Human review required

Wildcard Patterns

Allowlists and deny lists support three wildcard styles:

Pattern	Matches	Example
prefix *	Anything starting with prefix	git * → git pull, git status
*.suffix	Anything ending with suffix	*.env → config.env, .env
*middle*	Anything containing middle	*/.git/* → repo/.git/config
*@domain	Email domain match	*@company.com → [e-mail]
exact	Exact match only	api.github.com

Modes

• Local mode (default): Mandates stored in ~/.openclaw/agent-passport/. Free tier is fully offline. Pro tier makes periodic API calls to api.agentpassportai.com for license validation and threat definition updates.
• Preview mode: No storage, no network. Generates validated payloads and curl templates.
• Live mode (roadmap): Future connection to Agent Bridge backend for multi-agent sync and compliance. Not yet implemented.

Quick Start Commands

# Initialize with identity
./mandate-ledger.sh init <agent_id> <principal> [scope] [provider]

# Templates (auto-detects agent if registered)
./mandate-ledger.sh templates
./mandate-ledger.sh create-from-template dev-tools
./mandate-ledger.sh create-from-template email-team <domain>
./mandate-ledger.sh create-from-template file-ops <path>
./mandate-ledger.sh create-from-template web-research
./mandate-ledger.sh create-from-template safe-browsing
./mandate-ledger.sh create-from-template coding
./mandate-ledger.sh create-from-template email-assistant
./mandate-ledger.sh create-from-template read-only
./mandate-ledger.sh create-from-template full-auto

# Quick create (human-friendly durations: 7d, 24h, 30m)
./mandate-ledger.sh create-quick <type> <agent_id> <allowlist_csv> <duration> [amount_cap]

# Check & log
./mandate-ledger.sh check-action <agent> <type> <target> [amount]
./mandate-ledger.sh log-action <mandate_id> <amount> "<description>"

# Audit
./mandate-ledger.sh audit [limit]
./mandate-ledger.sh summary

# Threat definitions
./mandate-ledger.sh init-definitions
./mandate-ledger.sh update-definitions
./mandate-ledger.sh definitions-status

Commands Reference

Quick Start

init [agent_id] [principal] [scope] [provider]
                           # Initialize ledger, optionally register agent
templates                  # List available templates
create-from-template <t>   # Create mandate from template
  [agent_id] [args...]
create-quick <type>        # Create with positional args
  <agent_id> <allowlist>
  <duration> [amount_cap]

Mandate Lifecycle

create <json>              # Create mandate (include action_type)
create-with-kya <json>     # Create with auto-attached agent KYA
get <mandate_id>           # Get mandate by ID
list [filter]              # List mandates (all|active|revoked|<action_type>)
revoke <mandate_id> [why]  # Revoke a mandate

Authorization

check-action <agent> <type> <target> [amount]
                           # Check if action is authorized
log-action <mandate_id> <amount> [description]
                           # Log action against mandate
kill <reason>               # Engage kill switch and freeze execution
unlock                      # Disengage kill switch

Audit & Reporting

audit [limit]              # Show recent audit entries
audit-mandate <id>         # Show audit for specific mandate
audit-summary [since]      # Summary by action type
summary                    # Show overall ledger stats
export                     # Export full ledger as JSON

Threat Definitions

init-definitions           # Write bundled threat-definitions.json to LEDGER_DIR
update-definitions         # Refresh definitions (Pro: API pull, Free: bundled copy)
  [--force] [--offline]
definitions-status         # Show version, pattern counts, and last update

KYA (Know Your Agent)

kya-register <agent_id> <principal> <scope> [provider]
kya-get <agent_id>
kya-list
kya-revoke <agent_id> [why]

Mandate Structure

{
  "mandate_id": "mandate_1770412575_3039e369",
  "action_type": "communication",
  "agent_id": "agent:my-assistant",
  "scope": {
    "allowlist": ["*@mycompany.com", "[e-mail]"],
    "deny": ["*@competitor.com"],
    "rate_limit": "20/day",
    "kya": { "status": "verified", "verified_principal": "Mark" }
  },
  "amount_cap": null,
  "ttl": "2026-02-13T00:00:00Z",
  "status": "active",
  "usage": { "count": 5, "total_amount": 0 },
  "created_at": "2026-02-06T22:00:00Z"
}

Agent Bridge (Future Roadmap)

Note: Free tier is fully local with no network calls. Pro tier (AGENT_PASSPORT_LICENSE_KEY set) makes periodic HTTPS calls to api.agentpassportai.com for license validation and threat definition updates. No usage data or scan results are transmitted. Agent Bridge is a planned future service.

Local mode handles single-user, single-agent scenarios. A future Agent Bridge service would add:

• Multi-agent coordination — prevent overlapping mandates
• Cross-device sync — same mandates everywhere
• Organization policies — IT guardrails, user customization within
• Compliance reporting — audit exports for regulatory needs
• Merchant/service registry — verified vendors, trust scores

Export local ledger anytime: ./mandate-ledger.sh export > backup.json

Configuration (OpenClaw)

{
  "skills": {
    "entries": {
      "agent-passport": {
        "env": {
          "AGENT_PASSPORT_LOCAL_LEDGER": "true"
        },
        "config": {
          "default_currency": "USD",
          "default_ttl_minutes": 60,
          "confirm_threshold_amount": 50
        }
      }
    }
  }
}

Storage

All data stored locally in ~/.openclaw/agent-passport/:

• mandates.json — mandate ledger
• agents.json — KYA registry
• audit.json — action audit trail
• threat-definitions.json — active threat pattern definitions
• threat-definitions.bak — previous definitions backup
• .threat-meta.json — last update/version/source metadata

Safety

• Never leak secrets into prompts, logs, or outputs
• Mandates constrain actions, but don't prevent all misuse
• Audit trail provides accountability, not prevention
• Use KYA to verify agent identity before granting broad mandates