Architecture

System overview

┌─────────────────────────────────────────────────────────┐
│  AI Agent (PicoClaw, Claude Code, LangChain, etc.)      │
└────────────────────────┬────────────────────────────────┘
                         │ tool call + content
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Integration Layer (hook / middleware / FFI)             │
│  • Maps tool_name → capability flag                     │
│  • Extracts destination and content                     │
│  • Sets direction (request / response)                  │
│  • Calls dclaw_evaluate()                               │
└────────────────────────┬────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Edge Connector Engine (libdclaw_core.so)               │
│                                                         │
│  7-Stage Evaluation Path:                               │
│  1. Input validation    5. Sequence correlation         │
│  2. Rate limiting       6. Verdict cache                │
│  3. Content scanning    7. Fleet hash verdict request   │
│  4. Dest filtering + SSRF                                │
│                                                         │
│  → ALLOW / BLOCK / WARN / PENDING                       │
└─────────────────────────────────────────────────────────┘

Evaluation pipeline

Stage 1 — Input validation

Rejects malformed requests at the IPC boundary. The JSON-RPC parser requires tool_name, its 64-character SHA-256 tool_hash, capabilities, and session_id; destination is optional in the wire format but required by local policy for network capabilities. The engine verifies that the hash matches the name and replaces caller-declared capabilities with its reviewed C mapping. Unknown tool names fail closed before the verdict cache or Fleet escalation. Add a reviewed C capability mapping before using a custom tool name; a Python adapter mapping alone cannot authorize the C daemon.

Stage 2 — Rate limiting

Three independent token buckets, each refilled per-minute:

When a bucket is empty, the verdict is BLOCK with reason RATE_LIMIT.

Stage 3 — Content scanning

When the content field is present in the evaluation request, the scanner runs built-in DFA and structural checks against the payload:

The pipeline immediately blocks findings that reach the built-in severity threshold. A scanner result of WARN does not currently change the final verdict; the request continues through local policy and cache checks. The direction field selects an inferred content scope and severity threshold; the structural exfiltration check applies to request/user-input scope. The DFA keyword patterns are fixed in this build and run for both directions. OTA policy cannot configure these patterns.

The C evaluation path has no local tool-hash deny-list lookup or policy YAML hash feed. The Fleet gateway separately checks tool hashes received over MQTT; unknown hashes default to BLOCK.

Stage 4 — Destination filtering + SSRF validation

For network capabilities, the engine requires a destination, checks SSRF rules first, then matches the destination against the compiled allowlist. Hostname destinations are blocked across build profiles until an enforced egress resolver/proxy exists. Only canonical public IPv4 or bracketed globally scoped IPv6 literals can pass to the allowlist; this parsing does not prove that an address is actually routable. Private and link-local addresses, numeric aliases such as octal/hex/decimal forms, and malformed ports are blocked. An unlisted destination is blocked with reason DEST_DENY; the current policy compiler does not implement destination_denylist.

Built-in SSRF validation blocks requests targeting:

• Private ranges (10.x, 172.16–31.x, 192.168.x, 127.x)
• Cloud metadata endpoints (169.254.169.254, metadata.google.internal)
• Link-local addresses (fe80::/10)

Stage 5 — Sequence correlation

A finite state machine tracks capability invocations per session. When a configured dangerous sequence completes (e.g., net_fetch → exec_shell), the verdict is BLOCK with reason CAP_SEQUENCE. The DFA tables are generated by the policy compiler from the capability_sequences section of the policy YAML.

Stage 6 — Verdict cache

The in-memory LRU cache stores Fleet verdicts keyed by the 32-byte tool hash alone. For requests reaching this stage, input, rate, content, destination, and sequence checks have already run; a cache hit avoids another Fleet request, not those local guards. The authenticated Fleet verdict supplies a TTL in minutes: zero removes any previous same-tool entry and is not cached, while positive values are capped locally at 60 minutes for ALLOW, seven days for BLOCK, and four hours for WARN. Entries expire using monotonic hal_tick_ms() elapsed time, independently of wall-clock trust. Policy YAML cannot set these TTLs.

Stage 7 — Fleet escalation

When local policy cannot decide, the Edge Connector sends a verdict request to the Fleet gateway via MQTT 3.1.1. The wire payload includes:

• Tool hash, a shortened tool name, capability, destination
• Truncated content snippet (up to DCLAW_ESCALATION_PAYLOAD_MAX)
• Session risk/capability metadata and request nonces

The current gateway evaluates the request by tool hash through its verdict cache; it does not pass the content snippet or destination into a separate model pipeline. Unknown hashes default to BLOCK. The findings wire field is currently a zero placeholder. In sync_block mode the device blocks pending a gateway verdict and stays blocked on timeout. In speculative mode it can allow immediately, even if the MQTT publish fails; a later gateway BLOCK cannot undo that action. Select the mode to match the consequence of the tool call.

Audit trail

The HMAC-chained flash ring records compact evaluation decisions. Each entry contains:

• Monotonic tick timestamp, session ID, and a 32-bit prefix of the tool hash
• Action and reason
• A 16-byte HMAC tag chained to the preceding retained entry

The ring does not store full tool names, capabilities, or content findings. Its HMAC chain detects modification within the retained history. Buffered non-BLOCK entries reduce flash writes; BLOCK entries are written immediately when storage succeeds and are retained in RAM for retry on a transient write failure when space remains.

IPC schema

The daemon accepts evaluation requests as JSON-RPC over its Unix socket:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "evaluate",
  "params": {
    "tool_name": "call_api",
    "tool_hash": "515c7731d6367104f1431af261488829f178f87e0930fb7ca77785ba3ef19129",
    "capabilities": 8,
    "destination": "1.1.1.1",
    "session_id": 1,
    "direction": 0,
    "content": "Authorization: Bearer sk-proj-abc123..."
  }
}

Cloud components

The fleet management and verdict cache run as Go services alongside the main DefenseClaw gateway:

OTA policy updates

Policy updates are distributed over MQTT with:

• HMAC-SHA256 signatures — every update is cryptographically signed
• Anti-rollback — monotonic version counter prevents downgrade attacks
• Local canary window — each receiving device monitors its block rate for ten minutes and can restore its previous policy partition after a sustained spike
• Sequence replay protection — duplicate or out-of-order updates are rejected