SleuthCo/clawshield-public
GitHub: SleuthCo/clawshield-public
ClawShield 是面向 AI 代理的安全代理网关，通过多层防御扫描并拦截提示注入、PII 与密钥泄露。
Stars: 125 | Forks: 16
# ClawShield
**AI 代理的安全代理。** 位于 [OpenClaw](https://github.com/openclaw/openclaw) 前面，扫描每条消息是否存在提示注入、PII 泄露和密钥泄露——在它们到达模型或离开网络之前进行拦截。
内置 5 个专业 AI 代理、仪表板以及 YAML 策略引擎。一条命令即可启动。
```
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Browser │────▶│ ClawShield │────▶│ OpenClaw │
│ (you) │◀────│ Security Proxy │◀────│ Gateway │
└──────────────┘ └──────────────────┘ └──────────────┘
▪ Prompt injection ▪ Claude, GPT,
detection LM Studio
▪ PII/secrets redaction ▪ Multi-agent
▪ Policy enforcement routing
▪ Audit logging ▪ RAG knowledge
```
## 快速启动（Docker）
**前提条件：** [Docker](https://docs.docker.com/get-docker/) 和 [Anthropic API 密钥](#getting-an-anthropic-api-key)。
```
# 1. 克隆仓库
git clone https://github.com/SleuthCo/clawshield-public.git
cd clawshield-public
# 2. 设置 API 密钥
cp standalone/.env.template standalone/.env
# 编辑 standalone/.env 并粘贴您的 Anthropic API 密钥
# 3. 启动
cd standalone
docker compose up -d
```
在浏览器中打开 **http://localhost:18801**。你将看到 ClawShield 仪表板，其中包含 5 个可聊天的 AI 代理。
仅此而已。ClawShield 正在扫描你与代理之间的所有流量。
## 获取 Anthropic API 密钥
ClawShield 使用 Claude（通过 Anthropic API）作为默认语言模型。以下是获取密钥的方法：
1. 访问 [console.anthropic.com](https://console.anthropic.com/) 并注册（或登录）
2. 点击左侧边栏的 **API Keys**
3. 点击 **Create Key**
4. 输入名称（例如 "clawshield"）并点击 **Create**
5. 复制密钥——它以 `sk-ant-` 开头
6. 将其粘贴到你的 `standalone/.env` 文件中：
ANTHROPIC_API_KEY=sk-ant-your-key-here
**费用：** Anthropic 按令牌计费。一次典型的聊天会话费用约为几美分。新账户可获得 5 美元免费信用。详细信息请参见 [anthropic.com/pricing](https://www.anthropic.com/pricing)。
**使用其他模型？** ClawShield 兼容任何 OpenAI 兼容的 API（GPT、LM Studio、Ollama 等）。请编辑 `standalone/config/openclaw.json` 指向你偏好的提供者。
## 安装选项
### 选项 1：Docker（推荐）
所有组件在单个容器中运行——ClawShield 代理 + OpenClaw 网关 + 5 个代理。
请参考上方的 [快速启动](#quickstart-docker)。
### 选项 2：预编译二进制文件
从 [GitHub Releases](https://github.com/SleuthCo/clawshield-public/releases) 下载最新版本：
| 平台 | 文件 |
|----------|------|
| Windows | `clawshield-proxy-windows-amd64.exe` |
| Linux x64 | `clawshield-proxy-linux-amd64` |
| Linux ARM64 | `clawshield-proxy-linux-arm64` |
| macOS Apple Silicon | `clawshield-proxy-darwin-arm64` |
| macOS Intel | `clawshield-proxy-darwin-amd64` |
然后运行交互式设置向导：
```
# 下载设置向导
chmod +x clawshield-setup-*
# 运行向导 — 它会一步步引导您完成所有流程
./clawshield-setup-linux-amd64
```
该向导将：
- 要求输入你的 Anthropic API 密钥
- 配置你的代理
- 生成 OpenClaw 配置
- 创建启动/停止脚本
### 选项 3：从源码构建
需要 [Go 1.24+](https://go.dev/dl/)。
```
git clone https://github.com/SleuthCo/clawshield-public.git
cd clawshield-public
# 构建代理
cd proxy/cmd/clawshield-proxy
go build -o clawshield-proxy
# 构建设置向导
cd ../../clawshield-setup
go build -o clawshield-setup
# 运行设置
./clawshield-setup
```
## 包含内容
### 可观测性
ClawShield 暴露了一个与 Prometheus 兼容的 `/metrics` 端点，用于实时监控：
```
curl http://localhost:18789/metrics
```
关键指标：
- `clawshield_requests_total` — 已评估的总请求数
- `clawshield_decisions_allowed_total` / `_denied_total` / `_redacted_total` — 决策结果
- `clawshield_scanner_detections_total{scanner,action}` — 按扫描器类型统计的检测
- `clawshield_evaluation_duration_seconds` — 评估延迟直方图
- `clawshield_active_connections` — 当前 WebSocket 连接数
- `clawshield_crosslayer_events_*` — 跨层事件总线活动
### 安全代理
ClawShield 的核心。一个拦截用户与 AI 网关之间所有流量的 HTTP 反向代理。
**扫描器**（每个都会生成带有规则 ID 和脱敏匹配片段的结构化取证审计记录）：
- **提示注入检测** — 阻止越狱尝试、指令覆盖、角色操纵
- **PII 脱敏** — 检测并脱敏电子邮件、电话号码、SSN、信用卡
- **密钥检测** — 捕获 API 密钥、令牌、密码，防止泄露
- **漏洞扫描** — 标记 SQL 注入、SSRF、路径遍历、命令注入、XSS
- **恶意软件分析** — 检测可执行文件、脚本、压缩炸弹、已知签名
**生产强化（第 3 层）：**
- 使用 Go 原生 eBPF 监控替代 Python/BCC 依赖——单一编译二进制文件
- 优雅降级：当 eBPF 不可用时自动回退到 `/proc` 轮询（无需 `CAP_BPF`、旧内核或容器）
- 健康检查系统：各层状态报告（健康/降级/宕机）用于所有 3 层防御
- 事件管道可靠性：丢失计数、背压日志、已发布/丢弃事件指标
- 动态 DNS 重新解析：防止 CDN IP 轮换导致规则失效
- 启动时能力检测：内核版本、BTF 支持、root/CAP_BPF 检查
**策略热重载：**
- 基于文件观察的热重载——修改 `policy.yaml` 后，变更在 5 秒内生效，无需重启
- 内容哈希版本控制——每个策略版本都会生成基于 SHA256 的版本 ID，并记录在审计日志中
- 影子/金丝雀模式——在强制生效前以仅日志模式测试新策略
- 策略差异——每次重载都会记录确切变更（允许列表添加、扫描器开关等）
- 原子交换——正在进行的请求继续使用旧策略，新请求使用新策略
**流式响应扫描：**
- 对 SSE 和 NDJSON 流进行实时分块扫描——无缓冲延迟
- 滑动重叠窗口（200 字符）——捕获跨越分块边界的模式
- 从请求到响应的上下文传递——减少误报（例如代码生成响应可能包含脚本模式）
- 对流输出中的密钥和 PII 进行逐块脱敏
**策略引擎**——基于 YAML、拒绝优先：
```
default_action: deny
scanners:
prompt_injection:
enabled: true
action: block
pii:
enabled: true
action: redact
secrets:
enabled: true
action: block
domain_allowlist:
- "api.anthropic.com"
- "api.openai.com"
```
更多示例请参见 [policy/examples/](policy/examples/)。
### 5 个 AI 代理
每个代理都有专门的角色和独立的 RAG 知识库：
| 代理 | 角色 | 知识 |
|-------|------|-----------|
| **Anvil** | 软件开发 | 语言、架构、DevOps、测试、安全编码 |
| **Shield** | 安全工程 | NIST、MITRE ATT&CK、OWASP、零信任、威胁建模 |
| **Harbor** | 云工程 | AWS、Azure、GCP、Kubernetes、IaC、网络 |
| **Beacon** | 通信 | 危机沟通、内容策略、执行简报 |
| **Lens** | 研究与分析 | OSINT、结构化分析、认知偏差、情报 |
### 审计日志
每个请求和响应都会记录到本地 SQLite 数据库，包含：
- 时间戳、源 IP、请求方法
- 扫描器决策（允许/拒绝/脱敏）及原因
- **决策可解释性**——每个拒绝/脱敏决策的结构化取证详情，包括触发哪个扫描器、匹配了哪条规则、脱敏的匹配片段以及置信度
- 完整的请求/响应负载（可配置）
- 通过内置审计 CLI 查询：
```
clawshield-audit --db /var/lib/clawshield/audit.db --last 50
clawshield-audit --db /var/lib/clawshield/audit.db --blocked-only
clawshield-audit --db /var/lib/clawshield/audit.db --scanner injection
clawshield-audit --db /var/lib/clawshield/audit.db --rule-id sqli
```
完整架构请参见 [docs/audit-log-format.md](docs/audit-log-format.md)，取证查询详情请参见 [Decision Explainability](docs/audit-log-format.md#decision-explainability)。
**SIEM 集成：**
- 关键和高严重性事件实时转发到企业 SIEM 系统
- [OCSF v1.1](https://schema.ocsf.io/) Detection Finding 格式，实现通用 SIEM 兼容性
- Syslog（基于 TCP/TLS 的 RFC 5424）和 Webhook（HTTPS POST）传输
- 可配置严重性阈值——默认仅转发高（4）和严重（5）告警
- 配置详情参见 [docs/audit-log-format.md](docs/audit-log-format.md#siem-integration)
### 网络防火墙（可选）
基于 iptables 的出口防火墙，限制代理可访问的域名/IP：
<_BLOCK_7/>
### eBPF 监控（可选）
内核级系统调用监控，用于检测可疑代理行为：
```
sudo python3 ebpf/cmd/clawshield-ebpf/main.py --config ebpf/config/default.yaml
```
可检测：进程炸弹、敏感文件访问、权限提升、异常网络连接。
## 架构
ClawShield 采用 **纵深防御** 架构，由三个安全层通过跨层事件总线连接：
```
Layer 1: Application (ClawShield Proxy)
▪ Scans message content
▪ Enforces YAML policies
▪ Logs all decisions
Layer 2: Network (ClawShield Firewall)
▪ iptables egress rules
▪ Domain/IP allowlist
▪ Blocks unapproved connections
▪ Dynamic temporary rules from cross-layer events
Layer 3: Kernel (ClawShield eBPF)
▪ Syscall monitoring
▪ Behavioral anomaly detection
▪ Real-time alerts
```
各层独立工作。若某一层被绕过，其他层仍可提供保护。
### 跨层事件总线
三个层通过基于 Unix 套接字的事件总线通信，实现**自适应安全响应**：
```
┌──────────────┐ ┌──────────────┐
│ eBPF │──── Unix Socket ────────▶│ Proxy │
│ (Layer 3) │ /tmp/clawshield- │ (Layer 1) │
│ Produces: │ events.sock │ Produces: │
│ • privesc │ │ • injection │
│ • port_scan │◀── Adaptive Controller ──│ • malware │
│ • file_access│ │ • vuln_scan │
└──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ Firewall │
│ (Layer 2) │
│ Consumes: │
│ • temp block│
│ rules │
└──────────────┘
```
**自适应反应示例：**
| 触发条件 | 自动响应 |
|---------|-------------------|
| eBPF 检测到权限提升 | 代理在 5 分钟内将注入敏感度提升至 `high` |
| eBPF 检测到端口扫描 | 代理在 10 分钟内限制域名访问 |
| 代理在 60 秒内阻止 3 次以上注入 | 默认动作强制设为 `deny`，持续 15 分钟 |
| 代理检测到响应中的恶意软件 | 防火墙添加临时 IP 阻断规则 |
在策略 YAML 中添加 `adaptive` 部分以启用跨层集成。完整示例请参见 [policy/examples/adaptive_crosslayer.yaml](policy/examples/adaptive_crosslayer.yaml)。
## 生产部署
在真实服务器上部署并启用 TLS，请参考 [docs/install-guide.md](docs/install-guide.md)。
`deploy/` 目录包含：
- `cloud-init.yaml` — 强化虚拟机配置（SSH 锁定、fail2ban、nftables、auditd）
- `docker-compose.yml` — 完整生产栈（含 Nginx TLS 终止）
- `nginx/conf.d/` — 生产级 Nginx 配置（速率限制、安全头、WebSocket 代理）
- `deploy.sh` — 自动化部署脚本
- `smoke-test.sh` — 部署后验证
## 配置
### 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | 是 | 你的 Anthropic API 密钥（`sk-ant-...`） |
| `GATEWAY_AUTH_TOKEN` | 否 | 共享认证令牌（未提供时自动生成） |
| `CLAWSHIELD_PORT` | 否 | 主机端口（默认：18801） |
| `CLAWSHIELD_STUDIO_URL` | 否 | Studio 深链接基础 URL |
### 文件
| 文件 | 用途 |
|------|---------|
| `standalone/config/openclaw.json` | OpenClaw 网关配置（模型、代理、认证） |
| `standalone/config/policy.yaml` | ClawShield 安全策略 |
| `standalone/agents/*/` | 代理配置及知识库 |
## 测试
```
# 单元测试
go test ./proxy/...
go test ./firewall/...
# 集成测试
go test ./integration/...
```
## 许可证
Apache 2.0
## 感谢
基于 [OpenClaw](https://github.com/openclaw/openclaw) 构建。灵感来源于传统网络安全架构在 AI 代理场景中的应用。
标签：AI安全, Chat Copilot, ClawShield, Docker, Docker镜像, eBPF监控, EVTX分析, Go代理, iptables防火墙, Lerna, NIDS, PII脱敏, RAG知识库, YAML策略引擎, 多智能体, 安全代理, 安全防御评估, 审计日志, 容器化, 提示注入防护, 数据脱敏, 日志审计, 策略执行, 纵深防御, 自定义请求头, 请求响应过滤, 请求拦截, 零日漏洞检测