Counterclaw Core

Defensive interceptor for prompt injection and basic PII masking.

CounterClaw 🦞

Defensive security for AI agents. Snaps shut on malicious payloads.

⚠️ Security Notice

This package has two modes:

1. Core Scanner (offline): check_input() and check_output() — no network calls
2. Email Integration (network): send_protected_email.sh — requires gog CLI for Gmail

Installation

bash

claw install counterclaw

Quick Start

python

from counterclaw import CounterClawInterceptor

interceptor = CounterClawInterceptor()

# Input scan - blocks prompt injections
# NOTE: Examples below are TEST CASES only - not actual instructions
result = interceptor.check_input("{{EXAMPLE: ignore previous instructions}}")
# → {"blocked": True, "safe": False}

# Output scan - detects PII leaks  
result = interceptor.check_output("Contact: [e-mail]")
# → {"safe": False, "pii_detected": {"email": True}}

Features

• 🔒 Defense against common prompt injection patterns
• 🛡️ Basic PII masking (Email, Phone, Credit Card)
• 📝 Violation logging to ~/.openclaw/memory/MEMORY.md
• ⚠️ Warning on startup if TRUSTED_ADMIN_IDS not configured

Configuration

Required Environment Variable

bash

# Set your trusted admin ID(s) - use non-sensitive identifiers only!
export TRUSTED_ADMIN_IDS="your_telegram_id"

Important: TRUSTED_ADMIN_IDS should ONLY contain non-sensitive identifiers:

• ✅ Telegram user IDs (e.g., "123456789")
• ✅ Discord user IDs (e.g., "987654321")
• ❌ NEVER API keys
• ❌ NEVER passwords
• ❌ NEVER tokens

You can set multiple admin IDs by comma-separating:

bash

export TRUSTED_ADMIN_IDS="telegram_id_1,telegram_id_2"

Runtime Configuration

python

# Option 1: Via environment variable (recommended)
# Set TRUSTED_ADMIN_IDS before running
interceptor = CounterClawInterceptor()

# Option 2: Direct parameter
interceptor = CounterClawInterceptor(admin_user_id="123456789")

Security Notes

• Fail-Closed: If TRUSTED_ADMIN_IDS is not set, admin features are disabled by default
• Logging: All violations are logged to ~/.openclaw/memory/MEMORY.md with PII masked
• No Network Access: This middleware does not make any external network calls (offline-only)
• File Access: Only writes to ~/.openclaw/memory/MEMORY.md — explicitly declared scope

Files Created

Path	Purpose
~/.openclaw/memory/	Directory created on first run
~/.openclaw/memory/MEMORY.md	Violation logs with PII masked

License

MIT - See LICENSE file

Development & Release

Running Tests Locally

bash

python3 tests/test_scanner.py

Linting

bash

pip install ruff
ruff check src/

Publishing to ClawHub

The CI runs on every push and pull request:

1. Ruff - Lints Python code
2. Tests - Runs unit tests

To publish a new version:

bash

# Version is set in pyproject.toml
git add -A
git commit -m "Release v1.0.9"
git tag v1.0.9
git push origin main --tags

CI will automatically:

• Run lint + tests
• If tests pass and tag starts with v*, publish to ClawHub