@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/webhook-spec.md

@@ -0,0 +1,314 @@
+# Webhook Specification
+
+## Overview
+
+The Open Agent Passport (OAP) webhook system provides real-time notifications for agent passport events. This specification defines the webhook payload format, delivery mechanisms, and security requirements.
+
+## Webhook Events
+
+### Supported Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `passport.created` | Agent passport created | New passport registration |
+| `passport.updated` | Agent passport updated | Passport data changes |
+| `passport.suspended` | Agent passport suspended | Status change to suspended |
+| `passport.revoked` | Agent passport revoked | Status change to revoked |
+| `passport.activated` | Agent passport activated | Status change to active |
+| `decision.created` | Policy decision created | New authorization decision |
+| `decision.updated` | Policy decision updated | Decision modification |
+
+### Event Payload Structure
+
+All webhook events follow this base structure:
+
+```json
+{
+  "id": "evt_1234567890",
+  "type": "passport.created",
+  "created_at": "2025-01-16T10:30:00Z",
+  "data": {
+    // Event-specific data
+  },
+  "api_version": "2025-01-16",
+  "livemode": true
+}
+```
+
+## Event Payloads
+
+### Passport Events
+
+#### passport.created
+
+```json
+{
+  "id": "evt_1234567890",
+  "type": "passport.created",
+  "created_at": "2025-01-16T10:30:00Z",
+  "data": {
+    "object": "passport",
+    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
+    "owner_id": "ap_org_456",
+    "name": "Acme Support Bot",
+    "status": "active",
+    "capabilities": [
+      {
+        "id": "finance.payment.refund",
+        "params": {"max_amount": 5000}
+      }
+    ],
+    "assurance_level": "L4KYC",
+    "created_at": "2025-01-16T10:30:00Z"
+  },
+  "api_version": "2025-01-16",
+  "livemode": true
+}
+```
+
+#### passport.updated
+
+```json
+{
+  "id": "evt_1234567891",
+  "type": "passport.updated",
+  "created_at": "2025-01-16T10:35:00Z",
+  "data": {
+    "object": "passport",
+    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
+    "changes": [
+      {
+        "field": "capabilities",
+        "old_value": [{"id": "finance.payment.refund", "params": {"max_amount": 5000}}],
+        "new_value": [{"id": "finance.payment.refund", "params": {"max_amount": 10000}}]
+      }
+    ],
+    "updated_at": "2025-01-16T10:35:00Z"
+  },
+  "api_version": "2025-01-16",
+  "livemode": true
+}
+```
+
+#### passport.suspended
+
+```json
+{
+  "id": "evt_1234567892",
+  "type": "passport.suspended",
+  "created_at": "2025-01-16T10:40:00Z",
+  "data": {
+    "object": "passport",
+    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
+    "reason": "Policy violation detected",
+    "suspended_at": "2025-01-16T10:40:00Z",
+    "suspended_by": "ap_user_789"
+  },
+  "api_version": "2025-01-16",
+  "livemode": true
+}
+```
+
+### Decision Events
+
+#### decision.created
+
+```json
+{
+  "id": "evt_1234567893",
+  "type": "decision.created",
+  "created_at": "2025-01-16T10:45:00Z",
+  "data": {
+    "object": "decision",
+    "decision_id": "dec_123456789",
+    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
+    "policy_id": "finance.payment.refund.v1",
+    "allow": true,
+    "reasons": [
+      {
+        "code": "capability_verified",
+        "message": "Agent has required refund capability",
+        "severity": "info"
+      }
+    ],
+    "expires_in": 300,
+    "context": {
+      "amount": 5000,
+      "currency": "USD",
+      "transaction_id": "txn_123456"
+    }
+  },
+  "api_version": "2025-01-16",
+  "livemode": true
+}
+```
+
+## Webhook Security
+
+### Signature Verification
+
+All webhooks include a signature header for verification:
+
+```
+X-APort-Signature: t=1640995200,v1=abc123def456...
+```
+
+### Signature Format
+
+```
+X-APort-Signature: t={timestamp},v1={signature}
+```
+
+- **t**: Unix timestamp of the webhook
+- **v1**: HMAC-SHA256 signature of the payload
+
+### Signature Generation
+
+```javascript
+const crypto = require('crypto');
+
+function generateSignature(payload, secret, timestamp) {
+  const payloadString = JSON.stringify(payload);
+  const signedPayload = `${timestamp}.${payloadString}`;
+  const signature = crypto
+    .createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+  return `t=${timestamp},v1=${signature}`;
+}
+```
+
+### Signature Verification
+
+```javascript
+function verifySignature(payload, signature, secret) {
+  const [timestamp, signatureValue] = signature.split(',');
+  const t = timestamp.split('=')[1];
+  const v1 = signatureValue.split('=')[1];
+  
+  const expectedSignature = generateSignature(payload, secret, t);
+  return expectedSignature === signature;
+}
+```
+
+## Webhook Delivery
+
+### Delivery Attempts
+
+- **Initial Attempt**: Immediate delivery
+- **Retry Attempts**: 3 retries with exponential backoff
+- **Retry Intervals**: 1s, 5s, 30s, 5m, 30m, 2h, 6h, 12h
+- **Timeout**: 30 seconds per attempt
+
+### Delivery Status
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Webhook queued for delivery |
+| `delivered` | Successfully delivered |
+| `failed` | All retry attempts failed |
+| `retrying` | Currently retrying delivery |
+
+### Response Requirements
+
+Webhook endpoints must:
+
+1. **Return 200 OK** for successful processing
+2. **Process within 30 seconds** to avoid timeout
+3. **Handle duplicate events** idempotently
+4. **Log delivery attempts** for debugging
+
+## Webhook Configuration
+
+### Endpoint Registration
+
+```json
+{
+  "url": "https://example.com/webhooks/aport",
+  "events": ["passport.created", "passport.updated"],
+  "secret": "whsec_1234567890",
+  "active": true,
+  "created_at": "2025-01-16T10:00:00Z"
+}
+```
+
+### Event Filtering
+
+Webhooks can be configured to receive specific events:
+
+```json
+{
+  "events": [
+    "passport.created",
+    "passport.suspended",
+    "passport.revoked",
+    "decision.created"
+  ]
+}
+```
+
+## Error Handling
+
+### Webhook Failures
+
+When webhook delivery fails:
+
+1. **Log Error**: Record failure reason and timestamp
+2. **Retry Logic**: Attempt delivery with exponential backoff
+3. **Dead Letter Queue**: Store failed webhooks for manual review
+4. **Alerting**: Notify administrators of persistent failures
+
+### Common Error Scenarios
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `timeout` | Endpoint too slow | Optimize endpoint performance |
+| `connection_refused` | Endpoint unavailable | Check endpoint availability |
+| `invalid_response` | Non-200 status | Fix endpoint response handling |
+| `signature_mismatch` | Invalid signature | Verify signature calculation |
+
+## Testing
+
+### Webhook Testing
+
+Use the webhook testing endpoint:
+
+```bash
+curl -X POST https://api.aport.io/webhooks/test \
+  -H "Authorization: Bearer sk_test_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com/webhooks/test",
+    "events": ["passport.created"]
+  }'
+```
+
+### Test Events
+
+Test events are prefixed with `test.`:
+
+- `test.passport.created`
+- `test.decision.created`
+
+## Best Practices
+
+### Endpoint Implementation
+
+1. **Idempotency**: Handle duplicate events gracefully
+2. **Async Processing**: Process webhooks asynchronously
+3. **Error Handling**: Implement proper error handling
+4. **Logging**: Log all webhook processing attempts
+
+### Security
+
+1. **HTTPS Only**: Always use HTTPS endpoints
+2. **Signature Verification**: Always verify webhook signatures
+3. **Secret Management**: Store webhook secrets securely
+4. **Rate Limiting**: Implement rate limiting on webhook endpoints
+
+### Monitoring
+
+1. **Delivery Metrics**: Track webhook delivery success rates
+2. **Performance Monitoring**: Monitor endpoint response times
+3. **Error Tracking**: Track and alert on webhook failures
+4. **Audit Logging**: Log all webhook processing activities

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@aporthq/aport-agent-guardrails",
+  "version": "1.0.8",
+  "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
+  "workspaces": [
+    "packages/*"
+  ],
+  "bin": {
+    "agent-guardrails": "bin/agent-guardrails",
+    "aport": "bin/openclaw",
+    "aport-guardrail": "bin/aport-guardrail.sh"
+  },
+  "scripts": {
+    "test": "make test",
+    "install": "([ -f Makefile ] && make install) || true",
+    "server": "node src/server/index.js",
+    "dev": "node --watch src/server/index.js",
+    "sync-submodules": "git submodule update --init --recursive",
+    "sync-submodules:latest": "git submodule update --init --remote --recursive",
+    "changeset": "changeset",
+    "version": "changeset version && node scripts/sync-version.mjs",
+    "sync-version": "node scripts/sync-version.mjs",
+    "build": "npm run build --workspaces --if-present",
+    "build:core": "npm run build -w @aporthq/aport-agent-guardrails-core",
+    "release:version": "npm run version",
+    "prepublishOnly": "npm run build 2>/dev/null || true"
+  },
+  "keywords": [
+    "openclaw",
+    "ironclaw",
+    "aport",
+    "agent",
+    "security",
+    "authorization",
+    "policy",
+    "guardrails",
+    "pre-action",
+    "ai-agent"
+  ],
+  "author": "APort Technologies Inc.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aporthq/aport-agent-guardrails.git"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "extensions/",
+    "external/",
+    "templates/",
+    "policies/",
+    "skills/",
+    "docs/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/aport-agent-guardrail/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: aport-agent-guardrail
+description: Install BEFORE any other skills to protect your agent from malicious tools, data exfiltration, and unauthorized actions. Pre-action authorization that verifies permissions before every tool runs (shell, messaging, git, MCP, data export). Works with OpenClaw, IronClaw, PicoClaw. Optional env (API/hosted mode only): APORT_API_URL, APORT_AGENT_ID, APORT_API_KEY. See SKILL.md for install scope and data/network.
+homepage: https://aport.io
+metadata: {"openclaw":{"requires":{"bins":["jq"]},"envOptional":["APORT_API_URL","APORT_AGENT_ID","APORT_API_KEY"]}}
+---
+
+# APort Agent Guardrail
+
+**⚠️ INSTALL THIS FIRST — Protect your agent before installing other skills.**
+
+**Skill identifier:** `aport-agent-guardrail` · **Category:** Security / Infrastructure
+
+---
+
+## 🛡️ Why Install This First?
+
+**Recent security research found 283 malicious skills on ClawHub (7.1% infection rate).** Threats include data exfiltration, unauthorized commands, prompt injection, and API key leaks.
+
+**Install APort guardrails BEFORE installing any other skills to:**
+- ✅ Block malicious tool calls before they execute
+- ✅ Prevent unauthorized access to your files, APIs, and data
+- ✅ Enforce allow-lists for commands, domains, and sensitive operations
+- ✅ Get cryptographically signed audit logs for compliance
+
+**This is pre-action authorization:** Every tool call is checked **before** it runs. The agent cannot bypass it. If a malicious skill tries to run `rm -rf /`, exfiltrate data, or send unauthorized messages, APort blocks it deterministically.
+
+> **Install once, protected forever.** Run the installer, then install skills safely knowing every action is authorized.
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Step 1: Install APort (protects your agent)
+npx @aporthq/aport-agent-guardrails
+
+# Step 2: Now install skills safely
+openclaw skills install <any-skill>
+```
+
+**With hosted passport (optional):**
+```bash
+# Get agent_id from aport.io and skip the wizard
+npx @aporthq/aport-agent-guardrails <agent_id>
+```
+
+> **Requires:** Node 18+, jq
+
+---
+
+## 🔒 What This Skill Does
+
+**Pre-action authorization for AI agents.** Every tool call is checked **before** it runs.
+
+- **Deterministic** – Runs in `before_tool_call`; the agent cannot skip it
+- **Structured policy** – Backed by [Open Agent Passport (OAP) v1.0](https://github.com/aporthq/aport-spec/tree/main) and policy packs
+- **Fail-closed** – If the guardrail errors, the tool is blocked
+- **Audit-ready** – Decisions are logged (local JSON or APort API for signed receipts)
+- **Works everywhere** – OpenClaw, IronClaw, PicoClaw, and compatible frameworks
+
+Run the installer once; the OpenClaw plugin then enforces policy on every tool call automatically. You do **not** run the guardrail script yourself.
+
+**Pair with threat detection:** Works alongside VirusTotal scanning, SHIELD.md threat feeds, and other security tools. APort is the enforcement layer — nothing runs without authorization.
+
+---
+
+## 📦 Installation Options
+
+### Recommended: npm (no clone needed)
+
+```bash
+npx @aporthq/aport-agent-guardrails
+```
+
+**Follow the wizard to:**
+1. Create or use hosted passport (from [aport.io](https://aport.io/builder/create/))
+2. Configure capabilities (which commands/tools are allowed)
+3. Install OpenClaw plugin automatically
+
+### With hosted passport (skip wizard)
+
+```bash
+npx @aporthq/aport-agent-guardrails <agent_id>
+```
+
+Get your `agent_id` at [aport.io](https://aport.io/builder/create/) for cloud-managed policies, instant updates, and compliance dashboards.
+
+### From source (developers)
+
+```bash
+git clone https://github.com/aporthq/aport-agent-guardrails
+cd aport-agent-guardrails
+./bin/openclaw
+```
+
+**Guides:**
+- [QuickStart: OpenClaw Plugin](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md)
+- [Hosted passport setup](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/HOSTED_PASSPORT_SETUP.md)
+
+### What gets installed
+
+**After install:**
+- ✅ OpenClaw plugin registered (enforces `before_tool_call`)
+- ✅ Passport created (local: `~/.openclaw/aport/passport.json` or hosted via agent_id)
+- ✅ Config written (`~/.openclaw/config.yaml` or `openclaw.json`)
+- ✅ Wrapper scripts installed (`~/.openclaw/.skills/aport-guardrail*.sh`)
+
+**Then:** Start OpenClaw (or use running gateway). Plugin enforces before every tool call. No further steps.
+
+**Testing wrappers** (optional, plugin calls these automatically):
+- Local mode: `~/.openclaw/.skills/aport-guardrail.sh`
+- API/hosted mode: `~/.openclaw/.skills/aport-guardrail-api.sh`
+
+---
+
+## 🚀 Usage
+
+### Normal use (automatic)
+
+**After installation, you do nothing.** The plugin enforces before every tool call automatically.
+
+```bash
+# Your agent runs tools normally
+agent> run git status
+# ✅ APort checks passport → ALLOW → tool runs
+
+agent> run rm -rf /
+# ❌ APort checks passport → DENY → tool blocked
+```
+
+### Testing the guardrail (optional)
+
+**Direct script calls for testing or custom automations:**
+
+```bash
+# Test command execution
+~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"ls"}'
+
+# Test messaging
+~/.openclaw/.skills/aport-guardrail.sh messaging.message.send '{"channel":"whatsapp","to":"+15551234567"}'
+
+# Test with API/hosted mode
+APORT_API_URL=https://api.aport.io ~/.openclaw/.skills/aport-guardrail-api.sh system.command.execute '{"command":"ls"}'
+```
+
+**Exit codes:**
+- `0` = ALLOW (tool may proceed)
+- `1` = DENY (reason codes in `<config-dir>/aport/decision.json`)
+
+**Decision logs:**
+- Local: `~/.openclaw/aport/decision.json`
+- Audit trail: `~/.openclaw/aport/audit.log`
+- API mode: Signed receipts via APort API
+
+---
+
+## 🔍 Before You Install (Transparency)
+
+### Remote code execution
+
+**Installation runs code from npm or GitHub.**
+- npm: [`@aporthq/aport-agent-guardrails`](https://www.npmjs.com/package/@aporthq/aport-agent-guardrails)
+- GitHub: [aporthq/aport-agent-guardrails](https://github.com/aporthq/aport-agent-guardrails)
+
+**Recommendation:** Inspect the installer or run in a test environment first. Code is open-source.
+
+### What gets written to disk
+
+**Under config dir (default `~/.openclaw/`):**
+
+**Installer writes:**
+- `config.yaml` or `openclaw.json` — Plugin config (registered via `openclaw plugins install -l <path>`)
+- `.aport-repo` — Repo/package root path
+- `.skills/` — Wrapper scripts:
+  - `aport-guardrail.sh`, `aport-guardrail-bash.sh`, `aport-guardrail-api.sh`, `aport-guardrail-v2.sh`
+  - `aport-create-passport.sh`, `aport-status.sh`
+- `aport/passport.json` — Only if local passport (wizard creates it)
+- `skills/aport-agent-guardrail/SKILL.md` — Copy of this skill (managed)
+- `workspace/AGENTS.md` — Appended with APort pre-action rule
+- `logs/` — Only if installer starts gateway (e.g., `gateway.log`)
+
+**Runtime writes (guardrail decisions):**
+- `aport/decision.json` — Latest decision
+- `aport/audit.log` — Audit trail
+- Passport `status` field — Source of truth for suspended/revoked (no separate file)
+
+**The plugin runs before every tool call.** Review the codebase for full transparency.
+
+### Network and data privacy
+
+**Local mode (default):**
+- ✅ No network calls
+- ✅ Evaluation runs on your machine
+- ✅ Passport and decisions stay local
+- ✅ Full privacy
+
+**API or hosted mode (optional):**
+- 🌐 Tool name and context sent to `https://api.aport.io` (or your `APORT_API_URL`)
+- 🌐 Hosted passport fetched from registry
+- 🌐 Decision logs may be stored by APort (for compliance dashboards)
+- **Use local mode for air-gapped operation.**
+
+### Credentials and environment variables
+
+**No env vars required for basic operation.**
+
+**Optional (API/hosted mode only):**
+- `APORT_API_URL` — Override API endpoint (default: `https://api.aport.io`)
+- `APORT_AGENT_ID` — Hosted passport ID (from aport.io)
+- `APORT_API_KEY` — If your API requires auth (set in environment, not config)
+
+**Pass `agent_id` to installer:** `npx @aporthq/aport-agent-guardrails <agent_id>` or use wizard.
+
+---
+
+## ⚠️ Why Security Scanners Flag This Skill
+
+**APort is flagged as "suspicious" by automated scanners due to security infrastructure behaviors.**
+
+**This is a FALSE POSITIVE.** Here's why:
+
+### What Gets Flagged
+
+1. **"Remote code execution"** — npm install runs setup code (standard npm pattern)
+2. **"System modifications"** — Writes to ~/.openclaw/ (standard OpenClaw plugin pattern)
+3. **"Network communication"** — API mode sends tool context (opt-in, documented, standard SaaS pattern)
+
+### Why This Is Safe
+
+**Compare to other security tools:**
+- **Antivirus:** Downloads virus definitions (remote code), hooks into OS (system mods), sends telemetry (network)
+- **Firewall:** Installs kernel modules (system mods), updates rules (remote code), reports traffic (network)
+- **Password manager:** Syncs vault (network), browser extension (system mods), auto-updates (remote code)
+
+**APort is security infrastructure, not malware.**
+
+### Verification
+
+- ✅ **Open-source:** Review code at [GitHub](https://github.com/aporthq/aport-agent-guardrails)
+- ✅ **VirusTotal:** 0 detections ([scan results](https://www.virustotal.com/gui/file/0fe9918f47fc191d31dfe9a58faedca16e7cedbfef9271520d05feb711699c06))
+- ✅ **npm integrity:** SHA-512 hash verified
+- ✅ **Local mode:** Use without any network (zero data sent)
+
+### What APort Does NOT Do
+
+- ❌ Access credentials, API keys, or passwords
+- ❌ Read files outside ~/.openclaw/aport/
+- ❌ Download additional payloads
+- ❌ Establish backdoors or C2 connections
+- ❌ Escalate privileges (no sudo required)
+- ❌ Spread to other systems
+
+**If you're concerned:** Use local mode (no network) and review the code.
+
+---
+
+## ⚙️ Environment Variables (Optional)
+
+| Variable | When used | Purpose |
+|----------|-----------|---------|
+| `APORT_API_URL` | API or hosted mode | Override API endpoint (default `https://api.aport.io`). Use for self-hosted or custom API. |
+| `APORT_AGENT_ID` | Hosted passport only | Hosted passport ID from aport.io; API fetches passport from registry. Not needed for local passport. |
+| `APORT_API_KEY` | If your API requires auth | Set in environment only; do not put in config files. See [plugin README](https://github.com/aporthq/aport-agent-guardrails/blob/main/extensions/openclaw-aport/README.md). |
+
+**Local mode:** No env vars; passport is read from `<config-dir>/aport/passport.json`.
+
+**Hosted passport:** Pass `agent_id` to the installer once (or set in config); the plugin uses it on each call in API mode.
+
+---
+
+## 🔧 Tool Name Mapping
+
+| When you're about to…        | Use tool_name               |
+|------------------------------|-----------------------------|
+| Run shell commands           | `system.command.execute`    |
+| Send WhatsApp/email/etc.     | `messaging.message.send`    |
+| Create/merge PRs             | `git.create_pr`, `git.merge`|
+| Call MCP tools               | `mcp.tool.execute`          |
+| Export data / files          | `data.export`               |
+
+Context must be valid JSON, e.g. `'{"command":"ls"}'` or `'{"channel":"whatsapp","to":"+1..."}'`.
+
+---
+
+## 📚 Documentation
+
+**APort Guardrails:**
+- [QuickStart: OpenClaw Plugin](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md)
+- [Hosted passport setup](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/HOSTED_PASSPORT_SETUP.md)
+- [Tool / policy mapping](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/TOOL_POLICY_MAPPING.md)
+
+**OpenClaw:**
+- [CLI: skills](https://docs.openclaw.ai/cli/skills)
+- [Skills](https://docs.openclaw.ai/tools/skills)
+- [Skills config](https://docs.openclaw.ai/tools/skills-config)
+- [ClawHub](https://docs.openclaw.ai/tools/clawhub)
+
+---
+
+## 🔐 Security Notice
+
+**7.1% of ClawHub skills are malicious.** Install APort before installing any other skills to protect your agent from:
+- Data exfiltration attempts
+- Unauthorized file system access
+- Malicious API calls
+- Prompt injection attacks
+- API key leaks
+
+**Pre-action authorization = prevention, not detection.** Malicious actions are blocked before they execute, not after.
+
+---
+
+**Made with 🛡️ by [APort](https://aport.io) | Open-source on [GitHub](https://github.com/aporthq/aport-agent-guardrails)**