@agentlair/defenseclaw

OpenClaw plugin that adds AgentLair identity verification to DefenseClaw.

DefenseClaw governs what agents can do (policy enforcement, threat detection). AgentLair governs who the agent is and how it behaves. This plugin wires them together — identity verification, trust-score gating, and behavioral telemetry — without touching your policy YAML.

Proposed in cisco-ai-defense/defenseclaw#121.

What it does

On every before_tool_call event:

1. (optional) Verify AAT JWT — extracts the agent's Agent Authentication Token from ctx.sessionKey, verifies the EdDSA signature against AgentLair's JWKS endpoint, and rejects expired or tampered tokens.
2. Check trust score — calls GET /v1/trust/:agentId/check to get the agent's behavioral trust score (0–100).
3. Gate execution — if the score is below trustThreshold:
   • enforce mode (default): block the tool call.
   • observe mode: log a warning and allow execution.

On every after_tool_call event (fire-and-forget):

4. Report telemetry — POSTs a structured event to POST /v1/events so AgentLair can update the agent's behavioral profile.

Installation

npm install @agentlair/defenseclaw
# or
bun add @agentlair/defenseclaw

Configuration

Add to your openclaw.config.json:

{
  "plugins": [
    {
      "package": "@agentlair/defenseclaw",
      "config": {
        "agentlairApiKey": "al_live_...",
        "agentId": "acc_abc123",
        "trustThreshold": 40,
        "mode": "enforce",
        "verifyAat": true,
        "reportTelemetry": true
      }
    }
  ]
}

Options

| Key | Type | Default | Description | |-----|------|---------|-------------| | agentlairUrl | string | https://agentlair.dev | AgentLair base URL | | agentlairApiKey | string | — | API key (al_live_...). Or set AGENTLAIR_API_KEY. | | agentId | string | — | Fallback agent ID (acc_...). Used when ctx.agentId is not set. Or set AGENTLAIR_AGENT_ID. | | jwksUrl | string | {agentlairUrl}/.well-known/jwks.json | JWKS endpoint for AAT verification | | trustThreshold | number | 40 | Minimum trust score [0–100] required to execute tools | | mode | observe\|enforce | enforce | enforce blocks; observe logs only | | failOpen | boolean | false | Allow tool calls when AgentLair is unreachable | | verifyAat | boolean | true | Verify AAT JWT signature before trust check | | reportTelemetry | boolean | true | Report post-call events to /v1/events |

Environment variables

AGENTLAIR_URL=https://agentlair.dev
AGENTLAIR_API_KEY=al_live_...
AGENTLAIR_AGENT_ID=acc_abc123

Trust thresholds

AgentLair trust scores map to ATF maturity levels:

| Score | Level | |-------|-------| | 0–39 | intern | | 40–64 | junior | | 65–84 | senior | | 85–100 | principal |

The default threshold of 40 corresponds to the junior ATF level — agents must have demonstrated baseline behavioral consistency, restraint, and transparency before they can invoke tools.

Architecture

OpenClaw runtime
  │
  ├── before_tool_call
  │     │
  │     ├─① AgentLair JWKS  ←── verify AAT JWT (EdDSA/Ed25519)
  │     │
  │     ├─② AgentLair /v1/trust/:id/check  ←── get trust score
  │     │
  │     └─③ block (enforce) or warn (observe) if score < threshold
  │
  └── after_tool_call (fire-and-forget)
        │
        └─④ AgentLair /v1/events  ←── report outcome for behavioral profile

How it relates to DefenseClaw's architecture

DefenseClaw's sidecar inspects what a tool call contains (prompt injection, policy violations, data leakage). @agentlair/defenseclaw asks who is making the call and whether that agent has earned the right to execute. The two checks complement each other:

| Layer | DefenseClaw | AgentLair | |-------|------------|-----------| | Identity | ❌ | ✅ AAT verification | | Content | ✅ threat scanning | ❌ | | Policy | ✅ block/allow lists | ✅ trust tiers | | Audit | ✅ local | ✅ behavioral profile |

Integration with the DefenseClaw plugin API

This package implements the OpenClaw plugin API. The default export is a PluginEntry function that registers before_tool_call and after_tool_call hooks:

import type { PluginApi } from '@openclaw/plugin-sdk';
import agentLairPlugin from '@agentlair/defenseclaw';

export default function(api: PluginApi) {
  agentLairPlugin(api);
}

License

MIT