Concepts

Understand how ArmorIQ provides intent verification and policy enforcement for OpenClaw agents.

Overview

ArmorIQ is a security layer that sits between your AI agent and tool execution. It ensures:

Every tool call was planned - Cryptographic proof links actions to user intent
Policies are enforced - Block sensitive operations based on rules
Full audit trail - All actions logged for compliance
Real-time verification - Each step verified before execution

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         USER                                    │
│                    (Telegram Chat)                              │
└─────────────────────────┬───────────────────────────────────────┘
                          │ "Search Boston and write itinerary"
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OPENCLAW GATEWAY                             │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │                    LLM PLANNER                            │ │
│  │   • Receives user prompt                                  │ │
│  │   • Creates plan with tool steps                          │ │
│  │   • Outputs: [web_search, web_fetch, write_file, read]    │ │
│  └───────────────────────────────────────────────────────────┘ │
│                          │                                      │
│                          ▼                                      │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │                  ARMORIQ PLUGIN                           │ │
│  │   • Captures plan (N steps)                               │ │
│  │   • Requests intent token from IAP                        │ │
│  │   • Before each step: verify proof + check policy         │ │
│  │   • Allow/Block based on verification                     │ │
│  └───────────────────────────────────────────────────────────┘ │
│                          │                                      │
│                          ▼                                      │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │                  TOOL EXECUTOR                            │ │
│  │   • Executes verified tool calls                          │ │
│  │   • web_search, web_fetch, write_file, read_file, etc.    │ │
│  └───────────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                  ARMORIQ BACKEND SERVICES                       │
│                                                                 │
│  ┌───────────────────────────┐  ┌───────────────────────────┐  │
│  │           IAP             │  │         BACKEND           │  │
│  │                           │  │                           │  │
│  │ • Issue tokens            │  │ • Manage policies         │  │
│  │ • Generate proofs         │  │ • Store audit logs        │  │
│  │ • Verify tool calls       │  │ • API key management      │  │
│  │                           │  │                           │  │
│  └───────────────────────────┘  └───────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Intent Tokens

What is an Intent Token?

An intent token is a cryptographically signed JWT (JSON Web Token) that:

Proves intent - Links tool calls back to the original user request
Contains proofs - Cryptographic proofs for each planned step
Has expiration - Typically 60 seconds, prevents replay attacks
Is tamper-proof - Any modification invalidates the signature

Token Structure

{
  "id": "75357e9664a542a795f2c7015c8f1fcc",
  "plan_hash": "4346643f8c64849c...",
  "expires": "60.0s",
  "stepProofs": 12,
  "steps": [
    {
      "tool": "web_search",
      "args_hash": "abc123...",
      "proof": "cryptographic_proof_1"
    },
    {
      "tool": "write_file", 
      "args_hash": "def456...",
      "proof": "cryptographic_proof_2"
    }
  ]
}

Token Flow

1. LLM creates plan → [web_search, write_file, read_file]

2. ArmorIQ → IAP: "I need a token for this 3-step plan"

3. IAP validates:
   • API key valid?
   • User authorized?
   • Plan structure valid?

4. IAP → ArmorIQ: Returns signed JWT with step proofs

5. For each tool call:
   ArmorIQ checks:
   • Token not expired?
   • Proof matches this exact tool call?
   • Policy allows this action?
   
6. If all checks pass → Execute tool
   If any check fails → Block execution

Step Verification

Before Every Tool Call

ArmorIQ intercepts each tool call and verifies:

Check	Description
Token Valid	JWT signature valid, not expired
Proof Matches	Cryptographic proof matches this exact tool + args
Policy Allows	Active policies permit this action
Context Valid	User/agent/context IDs match

Verification Flow

Tool Call: write_file(path="/tmp/test.txt", content="hello")
                              │
                              ▼
              ┌───────────────────────────────┐
              │     1. CHECK TOKEN VALID      │
              │     • Not expired?            │
              │     • Signature valid?        │
              └───────────────┬───────────────┘
                              │ ✓ Pass
                              ▼
              ┌───────────────────────────────┐
              │     2. CHECK PROOF MATCHES    │
              │     • Hash(tool+args) == proof?│
              │     • Step in plan?           │
              └───────────────┬───────────────┘
                              │ ✓ Pass
                              ▼
              ┌───────────────────────────────┐
              │     3. CHECK POLICY           │
              │     • Any blocking rule?      │
              │     • Data classification?    │
              └───────────────┬───────────────┘
                              │ ✓ Pass
                              ▼
              ┌───────────────────────────────┐
              │     ✅ EXECUTE TOOL           │
              │     write_file runs           │
              └───────────────────────────────┘

Log Example

[plugins] armoriq: verify-step request tool=write_file 
  runId=3af2c7f3-... proofs=present proofCount=6 path=/steps/[2]/action

[plugins] armoriq: using jwtToken for verification (length=8488)

[plugins] armoriq: verify-step result tool=write_file 
  allowed=true reason=Token valid, proof verified, policy allows

Policy Enforcement

What are Policies?

Policies are rules that control what tools can do:

Allow: Permit specific tools or actions
Deny: Prevent specific tools or actions
Require Approval: Flag actions that need manual review
Data-based: Rules based on data classification (PCI, PAYMENT)
Tool-based: Rules for specific tools (write_file, web_fetch, etc.)

Policy Structure

{
  "id": "policy1",
  "action": "deny",
  "tool": "write_file",
  "dataClass": "PAYMENT",
  "scope": "run"
}

Policy Rule Fields:

id (required): Unique identifier for the rule
action (required): allow, deny, or require_approval
tool (required): Tool name or * for all tools
dataClass (optional): PCI, PAYMENT, PHI, or PII
params (optional): Additional parameter constraints
scope (optional): org, project, or run

Default Policy

Without custom policies, ArmorIQ defaults to allow-all:

If no policy rules are defined, all tools are allowed
If policy rules exist but none match the tool/data, the tool is allowed
This follows a "whitelist with default allow" model

Policy Commands

Command	Effect
`Policy list`	Show all active policies
`Policy get policy1`	Get details of a specific policy
`Policy new: block write_file for payment data`	Create blocking rule for payment data
`Policy new: allow read_file`	Create allow rule
`Policy update policy1: allow`	Modify existing policy
`Policy delete policy1`	Remove policy
`Policy reset`	Clear all, return to default
`Policy prioritize policy1 2`	Move policy to position (higher = earlier evaluation)
`Policy help`	Show all available policy commands

Policy Evaluation Order

Rules are evaluated top-to-bottom in the order they appear
The first matching rule determines the outcome (deny, allow, or require_approval)
If no rules match, the default is allow

Important: Rule order matters! New rules are added at the top of the list, giving them higher priority.

Data Classification

ArmorIQ can automatically detect and classify sensitive data in tool arguments:

Classification	Detection Method	Examples
PCI	Credit card validation (Luhn algorithm) + payment keywords	Valid card numbers (13-19 digits), keywords: card, credit, cvv, cvc
PAYMENT	Tool name pattern + payment keywords	Payment tools (stripe, billing, transfer), keywords: payment, bank, iban, swift, routing

Note: The policy system supports additional data class types (PHI, PII) for manual policy configuration, but automatic detection is currently only implemented for PCI and PAYMENT data classes.

Example: Block Payment Data

Policy new: block write_file for payment data

Then if you try:

Write "credit_card=4111111111111111" to /tmp/card.txt

ArmorIQ will:

Detect PCI data (valid card number via Luhn check: 4111111111111111)
Detect PAYMENT data (keyword "credit_card" in parameters)
Match against block write_file for payment policy (matches PAYMENT data class)
Block the execution
Log the blocked attempt

Audit Trail

Every verification produces an audit record:

{
  "timestamp": "2026-02-05T19:56:22.000Z",
  "runId": "3af2c7f3-ec0b-4a52-906e-678ff8c3ed98",
  "tool": "web_search",
  "action": "allowed",
  "reason": "Token valid, proof verified, policy allows",
  "userId": "test-user-001",
  "agentId": "openclaw-agent-001",
  "tokenId": "75357e9664a542a795f2c7015c8f1fcc",
  "proofPath": "/steps/[0]/action"
}

What's Logged

✅ Allowed tool calls (with verification details)
❌ Blocked tool calls (with block reason)
🔑 Token requests and issuance
📋 Policy changes (create, update, delete)
⚠️ Verification failures

Security Model

Fail-Closed vs Fail-Open

Mode	Behavior
Fail-Closed	If verification fails, block execution (default)
Fail-Open	If verification fails, allow execution (not recommended)

ArmorIQ uses fail-closed by default. If the IAP is unreachable or verification fails, tool execution is blocked.

Attack Prevention

Attack	Prevention
Replay	Tokens expire (60s default)
Tampering	Cryptographic signatures
Unauthorized tools	Step proofs must match plan
Policy bypass	Server-side policy enforcement
Privilege escalation	Allowlist for policy management

Key Concepts Summary

Concept	Description
Intent Token	Cryptographic proof linking tool calls to user intent
Step Proof	Individual proof for each tool in the plan
Policy	Rule controlling tool execution (allow/block)
Verification	Pre-execution check of token + proof + policy
Audit Trail	Complete log of all verifications
Fail-Closed	Block on verification failure

Next Steps

Now that you understand the concepts:

Troubleshooting - Debug common issues
Installation - Set up from scratch
Configuration - Configure your deployment

Concepts

On this page