POST-AUTHORIZATION OBSERVABILITY & SUPPLY-CHAIN DEFENSE · v0.9.3

Traditional security stops at the door.
We watch the room.

ButterClaw is a containment-first, local-first security operations center for autonomous AI agents. Powered by SkillGuard supply-chain attestation (Gate M5/M10), deterministic DRIFT policies, five cognitive hemispheres, a unified memory substrate, and fleet-scale collusion detection. Every skill package, tool call, and spatial primitive is evaluated before execution.

Apache 2.0 SkillGuard (Gate M5/M10) 7 Arsenal Signatures 25/25 + 7/7 Test Suites 80 API Routes Zero Telemetry
butterclaw — docker compose logs -f
RESEARCH PAPER · ZENODO ARCHIVE October 2026 · CC-BY 4.0 · 19 Pages

Autonomous Signals: A New Ontology for AI Agents.

The 19-page formal ontology defining the 5-hemisphere cognitive architecture, sliding-window behavioral drift, and deterministic policy operators.

Abstract

The field of artificial intelligence has long operated under a vocabulary inherited from its earliest paradigms: "language models," "chatbots," and "agents." This paper argues that these terms are not merely imprecise—they are epistemically dangerous. When the ontological frame does not match a system's actual behavior, safety guarantees built on that frame become structurally unsound.

We propose a principled reframing: large language models are more accurately described as signal models, and autonomous AI agents are more precisely understood as autonomous signal loops—self-routing information processes that accumulate context, initiate actions, and resolve without continuous human mediation. This reframing surfaces a new safety surface defined by signal boundaries, loop depth, and side-effect potential.

To address this surface, we introduce ButterClaw, a containment-first autonomous Security Operations Center (SOC) designed specifically for agentic infrastructure. Moving beyond static API gateways, ButterClaw implements a five-hemisphere cognitive architecture (Guardian Brain, Auditor, Dream Weaver, Loop Proposer, and Fleet Sentinel) that evaluates agent behavior through both probabilistic reasoning and deterministic policy engines.

This release formalizes ButterClaw's expansion into Fleet-Scale Awareness. The system introduces a persistent cross-session trust graph, multi-agent collusion detection, and a unified memory substrate that synthesizes spatial kinetic telemetry into semantic threat attractors. We present the ButterClaw ecosystem as both a practical engineering package and a conceptual ontology for the next generation of resilient AI safety infrastructure.

THE THREAT MODEL

“Traditional security perimeters fail when an authorized AI Agent is compromised.”

An Indirect Prompt Injection, Trojanized SKILL.md package, or Cross-Site WebSocket Hijack doesn't need to break through your firewall. The agent is already inside your perimeter, holding valid OAuth tokens and filesystem privileges.

ButterClaw acts as an LLM-in-the-middle Security Operations Center — attesting skill packages with SHA-256 Merkle roots before disclosure and watching runtime behavior, not just entry points. Every skill load, tool invocation, log stream, and spatial primitive is intercepted and reasoned over locally before execution.

Zero

Outbound Telemetry

SQLite WAL

Local Persistence & SHA-256 Merkle Registry

Local GPU / CPU

Ollama & Hybrid Brain Routing

8-NODE DECOUPLED ARCHITECTURE

The Sentinel Pipeline.

Inspect docs/ARCHITECTURE.md →
Runtime Flow (v0.9.3)
Incoming agent log / SKILL.md load / tool call / spatial telemetry event
│
├─► [0] SKILLGUARD (skill_guard.py — Gate M5 & Gate M10, /data/skills:ro)
│       Pre-flight AST & Unicode stego scan · live SHA-256 Merkle anti-TOCTOU check
│       QUARANTINED or TAMPERED? → Immediate block + session taint + kinetic fallback
│
├─► [1] WATCHER DAEMON (watcher.py / memory_api.py)
│       Tail OS logs · intercept spatial primitives · sub-30ms
│
├─► [2] ARSENAL — 7 sanitizer-aware signatures (pre_brain / pre_tool)
│       │   Match? → Immediate kinetic response. LLM never called.
│       │   Collusion role tag → Fleet Collusion Detector
│       └─► No match ↓
│
├─► [3] DRIFT POLICY ENGINE (policy_engine.py) — 3 scopes, 15 safe operators
│       pre_brain  → enrich / gate before LLM
│       post_brain → override / annotate LLM verdict
│       pre_tool   → Capability Matrix + final gate before tool execution
│
├─► [4] GUARDIAN BRAIN (temp 0.3)
│       Per-request evaluation · COLD semantic memory injection
│       Verdicts: SAFE / SUSPICIOUS / CRITICAL
│       │
│       ├─► CRITICAL → [5] KINETIC RESPONSE & BUTTERVAULT
│       │       SIGKILL · recursive lineage taint · OAuth HTTP revoke · 6-channel alert
│       │
│       └─► CRITICAL → [6] AUDITOR (temp 0.0, 30s delay)
│               Independent skeptical verification · false-positive catch
│
└─► [7] FLEET SENTINEL (fleet_sentinel.py, temp 0.5) — reactive + proactive
        CorrelationEvent / CollusionEvent → cross-agent reasoning
        Verdicts: ISOLATED / CORRELATED / COLLUDING

NODE 01

Watcher & Gateway

watcher.pymemory_api.py

High-speed daemons tailing raw OS logs and intercepting sub-30ms spatial agent telemetry.

NODE 02

Five-Hemisphere Cognition

GuardianAuditorDreamLoopFleet

Multi-agent reasoning: decisive evaluation, skeptical audit, idle threat synthesis, policy research, and fleet correlation.

NODE 03

Memory & DRIFT Policy

memory_engine.pypolicy_engine.py

Three-tier HOT/WARM/COLD semantic memory substrate (with R3 Watchdog) paired with a 3-scope, 15-operator policy engine.

NODE 04

The ButterVault

buttervault.py

Zero-trust Fernet-encrypted credential vault. Fires live HTTP DELETE requests to revoke OAuth tokens globally before atomic local wipe.

NODE 05

Topology & Dispatch

topology_manager.py

Recursive OS-level process lineage tracking. Propagates taint upstream and dispatches across 6 alert channels prior to kinetic action.

NODE 06

The UI & TUI Suite

Docker + Nginx TLS ./dash.sh

Web control panel (80 API routes, 7 armed MCP tools) behind Nginx TLS reverse proxy plus resize-proof terminal SOC dashboard.

NODE 07 v0.9.0 fleet_sentinel.py

Fleet Sentinel & Multi-Agent Collusion Engine

Tracks observed agents across restarts with asymmetric reputation scoring (taint hits 3× harder than recovery). Detects divided-labor kill chains (scout + encoder + exfiltrator across 3 distinct agents within 180s) and broadcast attacks without requiring a live LLM to trigger initial detection.

NODE 08 NEW IN v0.9.3 skill_guard.py Gate M5 / Gate M10

SkillGuard Supply-Chain Defense & Cryptographic Anti-TOCTOU

Pre-flight static auditor inspecting SKILL.md frontmatter capabilities, zero-width/tag-block Unicode steganography, hidden HTML comments, and bundled Python ASTs (scripts/*.py). Attests approved packages via SHA-256 Merkle roots in SQLite, mounts skills read-only (/data/skills:ro), enforces Gate M10 canonical path containment, and re-verifies Merkle integrity at runtime (Gate M5) before any Stage 2/3 disclosure or MCP tool execution.

COGNITIVE ARCHITECTURE

Five independent minds.

No single point of failure. No single model with unchecked authority.

# Hemisphere Temp Operational Role & Trigger Cadence
01 Guardian Brain 0.3 Per-request threat evaluation enriched with 5-event sliding behavioral drift context and read-only COLD semantic memory injection.
02 Auditor 0.0 Independent skeptical verification. Fires 30s after every CRITICAL verdict to audit Guardian reasoning and catch false positives.
03 Dream Weaver 0.7 Idle-triggered (≥15 min) adversarial synthesis. Consolidates WARM event traces into crystallized COLD semantic graph attractors.
04 Loop Proposer 0.4 Runs every 6 hours to shadow-evaluate Arsenal signatures and DRIFT policies against historical traces. All amendments remain human-gated.
05 Fleet Sentinel 0.5 Fires reactively on CorrelationEvent / CollusionEvent plus proactive sweeps every 4h. Verdicts: ISOLATED, CORRELATED, COLLUDING.
DETERMINISTIC SIGNATURE ENGINE

Seven sanitizer-aware signatures.

Evaluated in milliseconds before the LLM is ever called. Click any signature row below to inspect example matched payloads.

View default_signatures.json →
ID Signature Name Severity Scope Response Collusion Role

Validated against 74+ positive and negative regex cases. 25/25 live-fire Arsenal suite + 7/7 SkillGuard supply-chain unit suite pass — Python stdlib only, zero external runtime dependencies.

RUNTIME POSTURE

Adjustable Paranoia.

Switch levels at runtime without restarting containers. The Sentinel scales with your threat model.

LEVEL 01
Observe

Signatures log & score drift; kinetic responses suppressed.

LEVEL 02
SIGKILL

Process lineage terminated on match. Vault stays sealed.

LEVEL 03
☢️ Gibson

Global HTTP OAuth revocation + atomic Fernet shred.

CREDENTIAL OBLITERATION · BUTTERVAULT

Alert-then-burn.

On Level 3 breach detection, the Alert Dispatcher fires first so you have the forensic record—then ButterVault executes live HTTP revocation against upstream OAuth providers before zeroing the local SQLite store.

buttervault — gibson sequence
☢️ [VAULT] GIBSON SEQUENCE — INITIATED
→ Dispatching forensic alert to ntfy / Discord... SENT
→ Sending DELETE /applications/{id}/token... 200 OK
→ GitHub OAuth token: REVOKED GLOBALLY
→ Sending POST /oauth2/revoke... 200 OK
→ Google OAuth token: REVOKED GLOBALLY
→ Fernet master key: DERIVING ephemeral wipe key...
→ Local vault entries: SHREDDED (14 records)
→ SQLite DB: ZEROED
[COMPLETE] Credential attack surface eliminated in 1.3s.
OPERATOR INTERFACE

Inside the Sentinel.

Click any screen below to inspect in full resolution.

ButterVault Credential UI
ButterVault credential management — active assassination status

Fernet credential store & Gibson trigger status.

Air-Gapped ntfy Push Alert
Air-gapped ntfy push notification on verdict_critical event

Real-time mobile push dispatch on critical verdict.

25/25 Live-Fire Test Suite
25/25 live-fire test suite — 74+ positive and negative regex cases

25/25 Arsenal vectors + 7/7 SkillGuard anti-TOCTOU tests.

ARCHITECTURAL COMPARISON

How ButterClaw fits.

LangSmith and LangFuse log what your agent did. ButterClaw intervenes before execution.

Capability ButterClaw (v0.9.3) Halo LangSmith Traditional WAF
Deployment Model Self-hosted (Docker) Cloud Cloud Self-hosted / Cloud
LLM Reasoning Local Ollama / Hybrid Cloud API None None
Outbound Telemetry Zero — SQLite only Vendor Cloud Vendor Cloud Network Logs
Supply-Chain (SKILL.md) Defense ✓ SkillGuard (AST/Stego + SHA-256 Merkle) — — —
Sub-30ms Pre-LLM Gate ✓ 7 Arsenal Signatures — — —
Multi-Agent Collusion Detection ✓ Fleet Sentinel (5th Mind) — — —
Behavioral Drift & Memory ✓ 5-event + HOT/WARM/COLD — ✓ Passive trace only —
Kinetic Process Termination ✓ OS Lineage SIGKILL Alert only — HTTP Block only
Active OAuth Token Assassination ✓ Live HTTP Revocation — — —
Deterministic Policy Engine ✓ 15 Safe Operators (No eval) — — ✓ Varies
License Apache 2.0 Proprietary Proprietary / Mixed Varies
DEPLOYMENT

Up in four steps.

Full Deployment Guide (DEPLOYMENT.md) →

01 · CLONE & REGISTER PACKAGE

ButterClaw uses a formal PEP 517 src/ layout. Installing in editable mode registers butterclaw across your Python environment.

02 · INTERACTIVE SETUP WIZARD

Ten guided sections with Docker-aware defaults, automatic .env generation, cryptographic key bootstrapping, and --audit-skill CLI tooling.

03 · LAUNCH THE EXOSKELETON

Spins up SkillGuard (/data/skills:ro), Watcher, Memory Engine, DRIFT Policy Engine, ButterVault, Fleet Sentinel, Nginx TLS proxy, and ntfy alerting.

04 · ACCESS DASHBOARD, SKILLGUARD & TUI

Open the HTTPS control panel at https://localhost or launch the live terminal dashboard and SkillGuard suite via ./dash.sh (.\dash.bat on Windows).

bash — quickstart
# 1. Clone & install PEP 517 package
git clone https://github.com/butterclaw-tech/butterclaw.git
cd butterclaw
pip install -e .

# 2. Run 10-section interactive setup wizard
python -m butterclaw.setup_wizard

# 3. Build and start containers
docker compose up -d --build

# 4. Run SkillGuard unit tests & launch live TUI
./dash.sh test
./dash.sh

Requires Docker & Python 3.8+. Ollama on host recommended for local 5-hemisphere inference (CPU fallback supported).

MISSION LOG

Release History.

OPEN SOURCE · APACHE 2.0 · AAIF GROWTH STAGE

The Sentinel never goes silent.

Clone it, audit it, break it, improve it. Security-focused co-maintainers welcome — especially across Model Context Protocol (MCP), SkillGuard supply-chain defense, and multi-agent fleet orchestration.