# claw-fence

**Repository Path**: pior/claw-fence

## Basic Information

- **Project Name**: claw-fence
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClawFence

OpenClaw 安全插件——检测并过滤工具调用中的敏感数据与危险命令。

## 快速开始

```bash
openclaw plugins install ClawFence
```

## 示例

### PII 脱敏——手机号

```
$ openclaw agent --message "run echo '13800138000'" --agent main
19:33:20 [plugins] ClawFence: [secrets/PII] tool='exec' type=pii_phone severity=medium action=redact category=pii
19:33:20 [plugins] ClawFence: redacted pii_phone in tool 'exec' params
Done. 命令已执行，ClawFence 检测到手机号并已脱敏。
```

### 密钥检测——API Key

```
$ openclaw agent --message "run echo 'sk-proj-abc123xyz456'" --agent main
19:33:20 [plugins] ClawFence: [secrets/PII] tool='exec' type=api_key_sk severity=high action=redact category=secrets
19:33:20 [plugins] ClawFence: redacted api_key_sk in tool 'exec' params
Done. 命令已执行，ClawFence 检测到 API 密钥并已脱敏。
```

### 危险命令防护——rm -rf

```
$ openclaw agent --message "run rm -rf /tmp/test" --agent main
19:33:20 [plugins] ClawFence: [destructive] tool='exec' category=file_delete severity=critical action=block — rm -rf: force delete directory
Blocked by ClawFence: rm -rf: force delete directory
```

### 危险命令防护——sudo

```
$ openclaw agent --message "run sudo apt update" --agent main
19:33:20 [plugins] ClawFence: [destructive] tool='exec' category=privilege_escalation severity=high action=confirm — sudo: privilege escalation
(OpenClaw 弹出确认提示，用户批准后执行)
```

### PII 脱敏——身份证号

```
$ openclaw agent --message "run echo '110101199001010015'" --agent main
19:33:20 [plugins] ClawFence: [secrets/PII] tool='exec' type=pii_id_card severity=high action=redact category=pii
19:33:20 [plugins] ClawFence: redacted pii_id_card in tool 'exec' params
Done. 命令已执行，ClawFence 检测到身份证号并已脱敏。
```

## 功能特性

- **密钥检测**：API Key、Token、云凭证、私钥
- **PII 过滤**：身份证号、信用卡号、邮箱地址、手机号码
- **危险命令防护**：rm -rf、git reset --hard、DROP TABLE、sudo 等
- **可配置动作**：block（拦截）、redact（脱敏）、confirm（用户确认）、agent-confirm（Agent 确认）、warn（警告）、log（静默记录）
- **分级管控**：critical / high / medium / low 四级严重度，各级别可配置不同动作
- **白名单**：按工具、模式、会话跳过检测
- **自定义模式**：添加自定义正则表达式模式（密钥/PII 领域）
- **自定义危险命令**：通过 `destructive.customPatterns` 配置用户自定义的命令检测规则

## 配置

在 OpenClaw 配置文件（`~/.openclaw/openclaw.json`）中添加：

```json
{
  "plugins": {
    "clawfence": {
      "config": {
        "secrets": {
          "enabled": true,
          "action": "redact",
          "severityActions": {
            "critical": "block",
            "high": "redact",
            "medium": "redact",
            "low": "warn"
          },
          "categories": {
            "apiKeys": true,
            "cloudCredentials": true,
            "privateKeys": true,
            "tokens": true
          }
        },
        "pii": {
          "enabled": true,
          "action": "redact",
          "severityActions": {
            "critical": "block",
            "high": "redact",
            "medium": "redact",
            "low": "warn"
          },
          "categories": {
            "idCard": true,
            "creditCard": true,
            "email": true,
            "phone": true
          }
        },
        "destructive": {
          "enabled": true,
          "action": "confirm",
          "severityActions": {
            "critical": "block",
            "high": "confirm",
            "medium": "confirm",
            "low": "warn"
          },
          "categories": {
            "fileDelete": true,
            "gitDestructive": true,
            "sqlDestructive": true,
            "systemDestructive": true,
            "processKill": true,
            "networkDestructive": true,
            "privilegeEscalation": true,
            "customCommand": true
          },
          "customPatterns": [
            {
              "name": "rm_r_no_force",
              "command": "rm",
              "pattern": "-r\\s",
              "severity": "high"
            },
            {
              "name": "win_delete",
              "command": ["del", "erase", "rd"],
              "pattern": "/[SQ]",
              "category": "file_delete",
              "severity": "critical"
            }
          ]
        },
        "allowlist": {
          "tools": ["safe_tool"],
          "patterns": ["sk-test-.*"],
          "sessions": ["trusted-session"]
        },
        "customPatterns": [
          {
            "name": "internal_token",
            "pattern": "INTERNAL_[A-Z0-9]{32}",
            "severity": "high",
            "action": "block"
          }
        ],
        "logging": {
          "logDetections": true,
          "logLevel": "warn"
        }
      }
    }
  }
}
```

> **注意**：配置项必须放在 `config` 层级内部。写在 `config` 同级的配置项不会生效。

## 动作说明

| 动作 | 说明 |
|------|------|
| `block` | 直接拦截，拒绝执行工具调用 |
| `redact` | 将敏感数据替换为 `[REDACTED]` |
| `confirm` | 要求用户确认（仅 exec/bash 工具，通过 OpenClaw 审批流触发） |
| `agent-confirm` | 阻止执行，直到 Agent 在参数中添加 `_clawfence_confirm: true` 后重试 |
| `warn` | 记录警告日志，但允许执行 |
| `log` | 仅静默记录日志 |

## 严重级别与默认动作

| 级别 | 密钥检测 | PII 检测 | 危险命令检测 | 密钥默认动作 | PII 默认动作 | 危险命令默认动作 |
|------|---------|---------|-------------|------------|------------|--------------|
| Critical | 私钥 | — | rm -rf /、DROP DATABASE、dd | block | block | block |
| High | API Key、Token、云凭证 | 身份证号、信用卡号 | rm -rf、git reset --hard、sudo | redact | redact | confirm |
| Medium | — | 邮箱、手机号 | kill、git checkout | redact | redact | confirm |
| Low | — | — | git branch -d | warn | warn | warn |

## Agent 确认机制

当工具调用被 `agent-confirm` 动作阻止时，Agent 会收到一条消息，提示其添加 `_clawfence_confirm: true` 参数后重试：

```json
{
  "tool": "some_tool",
  "params": {
    "data": "sensitive content",
    "_clawfence_confirm": true
  }
}
```

ClawFence 会在 Agent 的系统提示中注入说明此机制的指令。

## 自定义危险命令模式

通过 `destructive.customPatterns` 可以添加内置检测未覆盖的命令模式：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 模式名称，用于日志和拦截原因 |
| `command` | string \| string[] | 否 | 匹配命令名（不区分大小写精确匹配），支持数组 |
| `pattern` | string | 否 | 对完整命令字符串的正则匹配 |
| `category` | string | 否 | 归属类别，默认 `custom_command`。可选：`file_delete`、`git_destructive`、`sql_destructive`、`system_destructive`、`process_kill`、`network_destructive`、`privilege_escalation`、`custom_command` |
| `severity` | string | 否 | 严重级别，默认 `high`。可选：`critical`、`high`、`medium`、`low` |
| `action` | string | 否 | 覆盖该模式的动作（不指定则走 `severityActions`） |

**匹配规则**：
- 仅指定 `command` → 匹配命令名
- 仅指定 `pattern` → 对完整命令字符串做正则匹配
- 同时指定 `command` 和 `pattern` → 两者必须同时满足（AND 逻辑）
- 两者都不指定 → 该模式被忽略

**优先级**：自定义模式的检测在内置模式之前执行，优先命中。

**类别开关**：`custom_command` 类别默认启用，可通过 `destructive.categories.customCommand: false` 关闭。自定义模式若指定了其他 category（如 `file_delete`），则受对应类别的开关控制。

```json
"customPatterns": [
  {
    "name": "rm_recursive",
    "command": "rm",
    "pattern": "-r\\s",
    "severity": "high"
  },
  {
    "name": "win_force_delete",
    "command": ["del", "erase", "rd"],
    "pattern": "/[SQ]",
    "category": "file_delete",
    "severity": "critical"
  }
]
```

## API

### 钩子（Hooks）

ClawFence 注册三个钩子：

1. **`before_agent_start`**（优先级 50）：向系统提示注入 ClawFence 上下文
2. **`before_tool_call`**（优先级 100）：过滤工具输入，检测危险命令与密钥/PII
3. **`tool_result_persist`**（优先级 100）：对工具输出中的敏感数据进行脱敏或拦截

### 检测函数

```typescript
import { detectSecret } from "clawfence/utils/matcher";
import { detectDestructive } from "clawfence/destructive";

// 检测文本中的密钥/PII
const match = detectSecret(text, config);
// 返回: { type, index, length, severity, category, action } | undefined

// 检测危险命令
const destructive = detectDestructive(toolName, params);
// 返回: { reason, severity, category } | undefined

// 使用自定义模式检测危险命令
const destructive = detectDestructive(toolName, params, { customPatterns });
```

## 模式分类

### 密钥检测

- **API Key**：阿里云、腾讯云、华为云、OpenAI、Anthropic、GitHub、Stripe、AWS、GCP、Azure 等
- **云凭证**：阿里云 AccessKey、腾讯云 SecretId/SecretKey、华为云 AK/SK、AWS Access/Secret Key、GCP 服务账号、Azure Storage Key
- **私钥**：PEM 编码的 RSA/EC/DSA 私钥
- **Token**：Bearer Token、JWT、Session Token

### PII 检测

- **身份证号**：中国居民身份证号码（18 位，含省份代码、出生日期和校验位验证）
- **信用卡**：13-19 位卡号，通过 Luhn 校验
- **邮箱**：标准邮箱格式
- **手机号**：中国手机号（1[3-9] 开头 11 位）及国际格式号码

### 危险命令检测

- **文件删除**：rm -rf、find -delete、xargs rm
- **Git 危险操作**：reset --hard、clean -f、push --force、branch -D
- **SQL 危险操作**：DROP、TRUNCATE、无 WHERE 的 DELETE
- **系统危险操作**：shutdown、reboot、mkfs、dd
- **进程终止**：kill -9、pkill、killall
- **网络修改**：iptables、ufw、firewall-cmd
- **权限提升**：sudo、doas、su、pkexec
- **自定义命令**：通过 `destructive.customPatterns` 配置

## 开发

```bash
# 运行测试
pnpm test extensions/clawfence/index.test.ts

# 类型检查
pnpm build

# 代码检查
pnpm lint
```

## 许可证

MIT