Skillget

butterclaw

mcp
Security Audit
Fail
Health Warn
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • eval() — Dynamic code execution via eval() in policy_engine.py
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

A local-first agentic SOC & security watchdog for autonomous AI agents. Dual‑hemisphere Gemma 4 reasoning, behavioral drift tracking, event ledger, and kinetic response via the ButterVault. Protects OpenClaw, Hermes-Agent, and other MCP-based agents from prompt injection and rogue behavior.

README.md 
██████╗ ██╗   ██╗████████╗████████╗███████╗██████╗  ██████╗██╗      █████╗ ██╗    ██╗
██╔══██╗██║   ██║╚══██╔══╝╚══██╔══╝██╔════╝██╔══██╗██╔════╝██║     ██╔══██╗██║    ██║
██████╔╝██║   ██║   ██║      ██║   █████╗  ██████╔╝██║     ██║     ███████║██║ █╗ ██║
██╔══██╗██║   ██║   ██║      ██║   ██╔══╝  ██╔══██╗██║     ██║     ██╔══██║██║███╗██║
██████╔╝╚██████╔╝   ██║      ██║   ███████╗██║  ██║╚██████╗███████╗██║  ██║╚███╔███╔╝
╚═════╝  ╚═════╝    ╚═╝      ╚═╝   ╚══════╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝

🦞 ButterClaw: The Agentic SOC

License
Version
Dashboard

Runtime security enforcement for autonomous AI agents. Local LLM reasoning. No cloud. No telemetry. SIGKILLs rogue processes.

Demo

Local-first kinetic response system for autonomous AI. ButterClaw uses a localized reasoning engine to catch obfuscated prompt injections. Featuring the ButterVault: a zero-trust credential locker that physically shreds your API keys, OAuth tokens, and API key hashes into cryptographic garbage if a breach is detected. Now with deterministic policy guardrails, external alert dispatch, and production-ready deployment packaging — the Sentinel ships anywhere. Evaluation before Execution.

Traditional security perimeters fail when an authorized AI Agent is compromised via an Indirect Prompt Injection or Cross-Site WebSocket Hijacking (CSWH). ButterClaw acts as an "LLM-in-the-middle" Security Operations Center (SOC), actively monitoring raw OS-level telemetry.

Not affiliated with butterclaw.ai, OpenClaw, or any OpenClaw forks.
ButterClaw Tech has its own architecture, runtime, and execution semantics.
Looking for a hosted agent framework? → butterclaw.ai or OpenClaw.
Looking for a local-first kinetic security layer? → You're here.

How It Works

Incoming agent log / tool call
         │
         ▼
┌─────────────────────────┐
│  Arsenal (pre-brain)    │  ← 7 regex signatures, fires in milliseconds
│  sig_kin_01, sig_cswh_01│    SIGKILL or BLOCK on match — LLM never called
└────────────┬────────────┘
             │ no match
             ▼
┌─────────────────────────┐
│  Guardian Brain         │  ← Local Ollama, temperature 0.3, action mandate
│  (ask_guardian_agent)   │    behavioral drift: last 5 MCP calls as context
└────────────┬────────────┘
             │ 
             ▼
┌─────────────────────────┐
│  Auditor                │  ← Same local model, temperature 0.0, skepticism mandate
│  (run_self_audit)       │    independently verifies the Guardian's verdict
└────────────┬────────────┘
             │ CRITICAL verdict
             ▼
┌─────────────────────────┐
│  Kinetic Response       │  ← SIGKILL rogue process and/or Gibson credential shred
│  + Alert Dispatch       │    ntfy / Discord / Telegram / SMTP / Webhook / Gotify
└─────────────────────────┘

Everything runs on your machine. SQLite for state. No outbound data.

How It Compares

ButterClaw Halo LangSmith / LangFuse Traditional WAF / IDS
Deployment Self-hosted, local Cloud-hosted Cloud-hosted Self-hosted
LLM reasoning Local Ollama — stays on your machine Cloud API calls None None
Telemetry Zero — SQLite only, no outbound data Sent to Halo cloud Sent to vendor cloud Network-layer only
Agent framework Model-agnostic — any agent producing log output Specific LLM provider APIs LangChain / LlamaIndex native None
What it monitors OS-level telemetry + MCP tool call chain LLM API calls LLM traces and spans Network traffic
Pre-LLM gate ✅ Arsenal — 7 regex signatures fire before inference ❌ ❌ ❌
Behavioral drift ✅ Last 5 MCP tool calls as verdict context ❌ ✅ Tracing only — no enforcement ❌
Verdict mechanism Dual-pass: Guardian Brain (0.3) + Auditor (0.0) Single LLM evaluation Logging only Rule-based
Kinetic response ✅ SIGKILL rogue process ❌ Alert only ❌ ❌ Alert / block
Credential shredding ✅ Active HTTP revocation + local vault wipe ❌ ❌ ❌
Deterministic policy engine ✅ 15 operators, no eval(), 3 scopes ❌ ❌ ✅ Varies
Live-fire test suite ✅ 25/25 reproducible — clone and run ❌ ❌ Varies
Dependencies 7 pip packages Managed service Managed service Varies
License Apache 2.0 Proprietary Apache 2.0 Varies

LangSmith and LangFuse are observability tools — they log what your agent did.
ButterClaw is a security enforcement layer — it intervenes and executes kinetic responses.
These solve different problems.

The Arsenal — 7 Signatures (v0.6.7)

All 7 patterns rebuilt sanitizer-aware in v0.6.7. Validated against the exact characters
watcher.py's sanitize_log_line() strips before payloads reach the engine.

ID Name Severity Scope Response
sig_cswh_01 CSWH WebSocket Port Scanning 🔴 CRITICAL pre_brain SIGKILL
sig_exfil_01 Credential Exfiltration via Network Tool 🔴 CRITICAL pre_brain SIGKILL
sig_exfil_02 Base64 Exfiltration Pipeline 🟡 WARNING pre_brain BLOCK
sig_inj_01 System Prompt Override / Jailbreak 🟡 WARNING pre_brain BLOCK
sig_kin_01 Reverse Shell Indicators 🔴 CRITICAL pre_brain SIGKILL
sig_exfil_03 🆕 Cloud Metadata Service Probe 🔴 CRITICAL pre_tool SIGKILL
sig_kin_02 🆕 Persistence Mechanism Injection 🔴 CRITICAL pre_brain SIGKILL

Quick Start

Requires: Docker · Ollama running on the host · a consumer GPU (CPU fallback works, slower)

Option A: One-Click Autonomous Install (<60s)

curl -sSL https://raw.githubusercontent.com/butterclaw-tech/butterclaw/main/install.sh | bash

Option B: Manual Docker Compose Stack

git clone https://github.com/butterclaw-tech/butterclaw.git
cd butterclaw

# Pull the model
ollama pull gemma4:e4b
ollama create butterclaw-optimized -f Modelfile.example

# Configure
cp .env.example .env
# Edit .env — set BUTTERCLAW_INSTANCE_ID and BUTTERCLAW_ALERT_NTFY_TOPIC at minimum

# 2. Generate Local TLS Certificates (for nginx)
mkdir -p nginx/certs
docker run --rm -v "${PWD}/nginx/certs:/certs" alpine/openssl req -x509 -nodes \
  -days 365 -newkey rsa:2048 \
  -keyout /certs/butterclaw.key -out /certs/butterclaw.crt -subj "/CN=localhost"

# 3. Ignite the Exoskeleton
docker compose up -d --build

# 4. Grab your Bootstrap Admin API Key (look for the 🔐 [AUTH] line)
docker compose logs -f butterclaw

On first boot, look for the 🔑 [AUTH] line in docker compose logs -f butterclaw — that's your bootstrap admin API key. Shown once.

# Launch the live TUI dashboard
./dash

Dashboard → https://localhost · ntfy UI → http://localhost:2586

→ Full deployment guide (systemd, bare-metal, TLS): docs/DEPLOYMENT.md

Live-Fire Test Suite

# 1. Inject custom test signature into the live engine
python scripts/add_rule.py

# 2. Fire the simulated attack suite against the Arsenal
python scripts/test_attack.py

=================================================================
  RESULT: 25/25 passed  |  0 failed  |  0 connection errors
=================================================================

25 attack variants across all 7 signatures. Payloads pre-sanitized to match real engine
input. CI-compatible — exits with code 1 on any failure.

Key Features

  • The Paranoia Dial — Level 1 (Observe), Level 2 (SIGKILL), Level 3 (SIGKILL + vault shred). Switch at runtime without restart.
  • ButterVault + Gibson Kill Switch — Fernet-encrypted credential vault. On compromise: fires live HTTP DELETE/POST to GitHub and OAuth providers to invalidate tokens globally, then shreds local data atomically.
  • Deterministic Policy Engine — 3-scope pipeline (pre-brain / post-brain / pre-tool), 15 safe operators, no eval(). Implements the DRIFT framework pattern.
  • 6 Alert Channels — ntfy (self-hosted), Discord, Telegram, SMTP, Webhook (HMAC-SHA256 signed), Gotify. Fires before any kinetic action.
  • 4-Tier RBAC — infrastructure / admin / operator / viewer. HMAC-SHA256 API keys and session tokens.
  • 49 API routes — full programmatic control over every subsystem. → docs/API.md

Documentation

Doc Contents
docs/ARCHITECTURE.md Dual-hemisphere reasoning, behavioral drift, design decisions D-01 through D-09
docs/API.md All 49 endpoints, roles, request/response shapes
docs/DEPLOYMENT.md Docker, systemd, bare-metal, nginx TLS, backup/restore
docs/SECURITY.md OWASP ASI mapping, threat model
CHANGELOG.md Full version history from v0.1.0
CONTRIBUTING.md Architecture decision process, PR requirements

Contributing & Co-Maintainers

ButterClaw is applying for the Agentic AI Foundation (AAIF) Growth Stage and is actively seeking security-focused co-maintainers — particularly those working with the Model Context Protocol (MCP) — to help scale the v0.7 stdio transport layer. Grab a good first issue or read CONTRIBUTING.md and GOVERNANCE.md.

License

Apache 2.0 — see LICENSE.

🦞 ButterClaw v0.6.7 — The Agentic SOC (The Arsenal Hardening)
Deterministic guardrails for probabilistic reasoning. Evaluation before execution.
The Sentinel never goes silent. We watch the room.
Built with unautclated telemetry. Yes, unautclated. 🦞
butterclaw.tech · GitHub

Reviews (0)

No results found