# openclaw-security-guardrails

> OpenClaw 运行时安全防护 — 实时检测密钥泄露、Prompt 注入、数据外泄，并通过纵深防御强化 Agent 安全

![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)
![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)

[English](./README.md) | 中文

## 为什么需要这个？

AI Gateway 面临一系列独特的安全攻击向量，记录在 [OWASP LLM Top 10 2025](https://owasp.org/www-project-top-10-for-large-language-model-applications/) 和 [MITRE ATLAS](https://atlas.mitre.org/) 中：

| 威胁 | 安全框架引用 | 本包对应 Hook |
|------|------------|-------------|
| Prompt 注入 | OWASP LLM01, MITRE AML.T0051 | `prompt-injection-detector` |
| 敏感数据泄露 | OWASP LLM02 | `secrets-scanner`, `secret-redactor` |
| Markdown 数据外泄 | CVE-2025-32711, CVE-2025-53773 | `exfiltration-detector` |
| 不安全的 Gateway 配置 | OWASP LLM08 | `startup-checker` |
| Agent 安全规则 | 纵深防御 | `security-bootstrap` |
| 合规与审计 | — | `audit-logger` |

## 安装

```bash
openclaw plugins install openclaw-security-guardrails
```

或本地克隆安装：

```bash
git clone https://github.com/shanggqm/openclaw-security-guardrails
openclaw plugins install ./openclaw-security-guardrails
```

## 架构

```
┌─────────────────────────────────────────────────────┐
│                     纵深防御架构                       │
├──────────┬──────────┬──────────┬──────────┬─────────┤
│ 第 0 层   │ 第 1 层   │ 第 1 层   │ 第 1 层   │ 第 2 层  │
│ Bootstrap│ 输入扫描  │ 输出扫描  │ 配置审计  │ 输出脱敏 │
│ 注入      │          │          │          │         │
├──────────┼──────────┼──────────┼──────────┼─────────┤
│ security │ prompt-  │ exfiltr- │ startup  │ secret  │
│ bootstrap│ injection│ ation-   │ checker  │ redactor│
│          │ detector │ detector │          │         │
│          │ secrets  │          │          │         │
│          │ scanner  │          │          │         │
├──────────┼──────────┼──────────┼──────────┼─────────┤
│ agent:   │ message: │ message: │ gateway: │ message:│
│ bootstrap│ received │ sent     │ startup  │ sent    │
└──────────┴──────────┴──────────┴──────────┴─────────┘
                   audit-logger (全事件)
```

## Hooks 一览

### 🔒 security-bootstrap（安全引导注入）— v0.2 新增

通过 `agent:bootstrap` 事件将 `SECURITY.md` 安全规则注入 Agent 上下文。

**事件**: `agent:bootstrap`

注入规则包括：禁止执行破坏性命令、禁止暴露凭证、报告注入攻击（`[SECURITY_FLAG]` 标记）、禁止数据外泄、敏感操作前确认。

> **注意**：这是软防御（纵深防御层）。LLM 在对抗性压力下可能忽略注入的规则。

---

### 🔐 secret-redactor（密钥脱敏告警）— v0.2 新增

扫描出站 AI 消息中的密钥泄露和 `[SECURITY_FLAG]` 标记。

**事件**: `message:sent`

- 检测 12+ 种密钥类型
- 监控 `security-bootstrap` 注入的 `[SECURITY_FLAG]` 标记
- 推送分类告警
- 记录到审计日志

---

### 🔑 secrets-scanner（密钥扫描器）

扫描所有收发消息中的泄露凭证，使用 21+ 正则规则。

**事件**: `message:received`, `message:sent`

---

### 🛡️ prompt-injection-detector（注入检测器）

防御 Prompt 注入、越狱尝试和 Unicode 隐蔽攻击。

**事件**: `message:received`, `message:preprocessed`

---

### 🚫 exfiltration-detector（外泄检测器）

**v0.2 改进**：智能 data URI 分析——合法小图片不再误报。

**事件**: `message:sent`

---

### 📋 audit-logger（审计日志）

**事件**: `message:received`, `message:sent`, `command:*`, `gateway:startup`, `agent:bootstrap`

**日志位置**: `~/.openclaw/security/audit.jsonl`（可通过 `OPENCLAW_SECURITY_LOG_DIR` 自定义）

---

### 🏥 startup-checker（启动检查器）

**v0.2 改进**：使用正确的深层配置路径，检查项从 5 个扩展到 7 个。

**事件**: `gateway:startup`

## 竞品对比

| 项目 | 类型 | 硬拦截 | 输出扫描 | AI 分析 | 纯本地 |
|------|------|--------|---------|---------|--------|
| **本项目 (v0.2)** | Hook Pack | ❌ | ✅ | ✅ (bootstrap) | ✅ |
| Knostic openclaw-shield | Plugin | ⚠️ | ✅ | ❌ | ✅ |
| ClawReins | Plugin | ✅ | ❌ | ❌ | ✅ |
| OpenGuardrails | Skill + Cloud | 部分 | ✅ | ✅ | ❌ |

## 性能

- 所有检测：**< 20ms**
- Bootstrap 注入：**< 2ms**
- **零 npm 依赖** — 仅使用 Node.js 内置 API
- 审计写入异步，不阻塞消息流

## 开发

```bash
npm install
npm test  # 90 个测试用例
npm run build
```

## 许可证

MIT © 2026 [shanggqm](https://github.com/shanggqm)