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 - Email Integration (network):
send_protected_email.sh — requires gog CLI for Gmail
Installation
CODEBLOCK0
Quick Start
CODEBLOCK1
Features
- - 🔒 Defense against common prompt injection patterns
- 🛡️ Basic PII masking (Email, Phone, Credit Card)
- 📝 Violation logging to INLINECODE3
- ⚠️ Warning on startup if TRUSTEDADMINIDS not configured
Configuration
Required Environment Variable
CODEBLOCK2
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:
CODEBLOCK3
Runtime Configuration
CODEBLOCK4
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 |
|---|
| INLINECODE10 | Directory created on first run |
| INLINECODE11 |
Violation logs with PII masked |
License
MIT - See LICENSE file
Development & Release
Running Tests Locally
CODEBLOCK5
Linting
CODEBLOCK6
Publishing to ClawHub
The CI runs on every push and pull request:
- 1. Ruff - Lints Python code
- Tests - Runs unit tests
To publish a new version:
CODEBLOCK7
CI will automatically:
- - Run lint + tests
- If tests pass and tag starts with
v*, publish to ClawHub
技能名称: counterclaw
详细描述:
CounterClaw 🦞
AI代理的防御性安全工具。对恶意载荷自动封锁。
⚠️ 安全须知
本包有两种模式：
- 1. 核心扫描器（离线）： checkinput() 和 checkoutput() — 无网络调用
- 邮件集成（网络）： sendprotectedemail.sh — 需要用于Gmail的gog CLI
安装
bash
claw install counterclaw
快速开始
python
from counterclaw import CounterClawInterceptor
interceptor = CounterClawInterceptor()
输入扫描 - 阻止提示注入
注意：以下示例仅为测试用例 - 非实际指令
result = interceptor.check_input({{示例：忽略之前的指令}})
→ {blocked: True, safe: False}
输出扫描 - 检测PII泄露
result = interceptor.check_output(联系方式：john@example.com)
→ {safe: False, pii_detected: {email: True}}
功能特性
- - 🔒 防御常见提示注入模式
- 🛡️ 基础PII掩码（邮箱、电话、信用卡）
- 📝 违规日志记录至 ~/.openclaw/memory/MEMORY.md
- ⚠️ 若未配置TRUSTEDADMINIDS，启动时发出警告
配置
必需的环境变量
bash
设置您的受信任管理员ID - 仅使用非敏感标识符！
export TRUSTED
ADMINIDS=your
telegramid
重要： TRUSTEDADMINIDS 应仅包含非敏感标识符：
- - ✅ Telegram用户ID（例如 123456789）
- ✅ Discord用户ID（例如 987654321）
- ❌ 绝不可使用API密钥
- ❌ 绝不可使用密码
- ❌ 绝不可使用令牌
可通过逗号分隔设置多个管理员ID：
bash
export TRUSTEDADMINIDS=telegramid1,telegramid2
运行时配置
python
选项1：通过环境变量（推荐）
运行前设置TRUSTEDADMINIDS
interceptor = CounterClawInterceptor()
选项2：直接参数
interceptor = CounterClawInterceptor(admin
userid=123456789)
安全说明
- - 故障关闭：若未设置 TRUSTEDADMINIDS，管理员功能默认禁用
- 日志记录：所有违规行为记录至 ~/.openclaw/memory/MEMORY.md，PII已掩码处理
- 无网络访问：此中间件不进行任何外部网络调用（仅离线）
- 文件访问：仅写入 ~/.openclaw/memory/MEMORY.md — 明确声明的范围
创建的文件
| 路径 | 用途 |
|---|
| ~/.openclaw/memory/ | 首次运行时创建的目录 |
| ~/.openclaw/memory/MEMORY.md |
违规日志，PII已掩码 |
许可证
MIT - 详见LICENSE文件
开发与发布
本地运行测试
bash
python3 tests/test_scanner.py
代码检查
bash
pip install ruff
ruff check src/
发布至ClawHub
CI在每次推送和拉取请求时运行：
- 1. Ruff - 检查Python代码
- 测试 - 运行单元测试
发布新版本：
bash
版本在pyproject.toml中设置
git add -A
git commit -m 发布 v1.0.9
git tag v1.0.9
git push origin main --tags
CI将自动：
- - 运行代码检查 + 测试
- 若测试通过且标签以 v* 开头，发布至ClawHub
