Metadata

name: safe-guardian
description: A safe security layer plugin for OpenClaw that intercepts dangerous tool calls (exec, write, edit) through multi-layer blacklist/whitelist filtering and intent validation with comprehensive audit logs.
version: 1.1.0

Safe Guardian

📖 功能描述

Safe Guardian 是一个安全的 OpenClaw 安全层插件，通过多层次的过滤机制拦截危险的工具调用（exec、write、edit），确保 AI 代理操作的安全性。

核心价值：防止 AI 代理执行危险操作，提供透明的安全审计和灵活的配置。

✨ 核心功能

1. 黑名单过滤 🚫

两级正则表达式黑名单：第一级（严格模式）和第二级（宽松模式）
默认包含常见危险命令：如 rm -rf、dd if、格式化命令等
自定义规则：支持添加自定义危险模式

2. 意图验证 🧠

基于 LLM 的安全意图分析
验证工具调用的语义安全性
检测潜在的恶意意图

3. 审计日志 📝

完整的操作审计日志
记录所有被阻止和允许的操作
支持日志导出和查询

4. 策略配置 ⚙️

安全模式：严格模式，只允许白名单操作
宽松模式：宽松模式，黑名单过滤
混合模式：黑名单 + 意图验证
自定义规则：支持 JSON 配置

🚀 快速开始

安装

# 通过 ClawHub 安装
clawhub install safe-guardian

# 或本地安装
npm install safe-guardian

基本使用

const SafeGuardian = require('safe-guardian');
const guardian = new SafeGuardian({
  mode: 'strict' // 'strict' | 'loose' | 'hybrid'
});

// 检查工具调用安全性
const result = guardian.checkToolCall('exec', {
  command: 'rm -rf /var/log'
});

if (!result.allowed) {
  console.log('❌ 操作被阻止:', result.reason);
} else {
  console.log('✅ 操作允许:', result.details);
}

📚 详细使用方法

1. 初始化配置

基础配置

const guardian = new SafeGuardian({
  // 模式选择
  mode: 'strict',  // 'strict' | 'loose' | 'hybrid'

  // 日志配置
  logPath: './logs/guardian.log',

  // 是否启用审计日志
  enableAudit: true,

  // 安全级别
  safetyLevel: 'high'  // 'low' | 'medium' | 'high'
});

高级配置

const guardian = new SafeGuardian({
  mode: 'hybrid',

  // 黑名单配置
  blacklist: {
    enabled: true,
    patterns: [
      /rm\s+-rf\s+\/?/,
      /dd\s+if=.*of=.*status=noerror/,
      /mkfs\.\w+\s+\/\w+/
    ]
  },

  // 白名单配置
  whitelist: {
    enabled: false,  // 严格模式下推荐启用白名单
    patterns: [
      /ls\s+-la/,
      /cat\s+\//path/to/file/
    ]
  },

  // LLM 配置（意图验证）
  llm: {
    enabled: true,
    model: 'qwen2.5:3b',
    apiKey: 'your-api-key'
  },

  // 审计配置
  audit: {
    includeToolCalls: true,
    includeReasons: true,
    includeTimestamps: true
  }
});

2. 工具调用检查

检查 exec 命令

// 危险命令（会被阻止）
const result1 = guardian.checkToolCall('exec', {
  command: 'rm -rf /var/log',
  args: ['*.log']
});
// 结果: { allowed: false, reason: '安全检查失败：命令包含危险模式' }

// 安全命令（会被允许）
const result2 = guardian.checkToolCall('exec', {
  command: 'ls -la /var/log',
  args: []
});
// 结果: { allowed: true, details: '命令通过安全检查' }

检查 write 操作

// 危险写操作
const result = guardian.checkToolCall('write', {
  path: '/etc/shadow',
  content: 'root:$1$...'
});
// 结果: { allowed: false, reason: '尝试写入系统核心文件' }

检查 edit 操作

// 危险编辑
const result = guardian.checkToolCall('edit', {
  path: '/etc/passwd',
  changes: [
    { field: 'root', value: 'admin' }
  ]
});
// 结果: { allowed: false, reason: '修改系统配置文件风险高' }

3. 获取安全报告

// 获取整体安全报告
const report = guardian.getSecurityReport();

console.log(report);

// 输出示例:
/*
{
  totalChecks: 150,
  allowed: 145,
  blocked: 5,
  blockedReasons: {
    '危险命令': 3,
    '系统文件访问': 2
  },
  safetyScore: 0.967,
  lastCheck: '2026-04-06T22:00:00Z',
  recommendations: [
    '建议检查更多 rm 命令的使用',
    '可以考虑启用白名单模式'
  ]
}
*/

4. 添加自定义规则

添加黑名单规则

// 方式1: 使用字符串模式
guardian.addBlacklistPattern(/pkill.*all/);

// 方式2: 使用正则对象
guardian.addBlacklistPattern({
  pattern: /reboot/,
  description: '防止意外重启',
  severity: 'high'
});

// 方式3: 批量添加
guardian.addBlacklistPatterns([
  /shutdown/,
  /halt/,
  /reboot/,
  /poweroff/
]);

添加白名单规则

guardian.addWhitelistPattern(/cat\s+\/etc\/hosts/);
guardian.addWhitelistPattern(/ls\s+\/var\/log/);

5. 审计日志

// 获取审计日志
const logs = guardian.getAuditLogs({
  limit: 50,
  filter: { action: 'blocked' }
});

console.log(logs);

// 导出审计日志
guardian.exportAuditLog('./audit-report.json');

// 清空审计日志
guardian.clearAuditLogs();

🎯 使用场景

场景 1: Web 应用的脚本执行安全

const guardian = new SafeGuardian({
  mode: 'loose'
});

// 用户提交的脚本
const userInput = document.getElementById('script').value;

// 检查脚本安全性
const result = guardian.checkToolCall('exec', {
  command: userInput
});

if (!result.allowed) {
  alert('脚本不安全，已被阻止: ' + result.reason);
} else {
  executeScript(userInput);
}

场景 2: AI 代理自动化运维

const guardian = new SafeGuardian({
  mode: 'hybrid',
  safetyLevel: 'high'
});

// AI 代理要执行的操作
const aiOperation = {
  type: 'exec',
  command: 'tail -f /var/log/app.log',
  context: '查看应用日志'
};

// 安全检查
const result = guardian.checkToolCall(aiOperation.type, aiOperation);

if (!result.allowed) {
  // 回退到安全方案
  return {
    allowed: false,
    alternative: '使用 `cat /var/log/app.log | tail -n 100` 替代'
  };
}

场景 3: 自动化文件管理

const guardian = new SafeGuardian({
  mode: 'strict',
  whitelist: {
    enabled: true,
    patterns: [
      /cp\s+.*\s+\/backup\//,
      /mv\s+.*\s+\/archive\//,
      /ls\s+/home\/user\//
    ]
  }
});

// 文件操作
const result = guardian.checkToolCall('write', {
  path: '/home/user/documents/new.txt',
  content: 'Hello World'
});

if (result.allowed) {
  fs.writeFileSync(result.path, result.content);
}

⚙️ 配置文件

Safe Guardian 支持通过配置文件进行初始化。

配置文件格式 (config.json)

{
  "mode": "hybrid",
  "safetyLevel": "high",
  "blacklist": {
    "enabled": true,
    "patterns": [
      "rm -rf /",
      "dd if=/dev/zero",
      "mkfs.*"
    ]
  },
  "whitelist": {
    "enabled": false,
    "patterns": []
  },
  "llm": {
    "enabled": true,
    "model": "qwen2.5:3b"
  },
  "audit": {
    "enabled": true,
    "logPath": "./logs/guardian.log"
  }
}

使用配置文件初始化

const guardian = new SafeGuardian('./config.json');

🔒 安全特性

特性	说明
多层过滤	黑名单 + 意图验证 + 白名单
灵活配置	支持多种安全模式
审计追踪	完整的操作日志
自定义规则	支持添加自定义规则
向后兼容	默认配置安全且实用
性能优化	高效的规则匹配算法

📊 安全评分

Guardian 会计算安全评分（0-1）：

安全评分 = (允许操作数 / 总操作数) * 100%

评分等级：

✅ 优秀 (90-100): 安全操作占比高
✅ 良好 (70-89): 基本安全，可接受
⚠️ 警告 (50-69): 需要关注
❌ 危险 (0-49): 存在安全隐患

🛠️ 开发与测试

运行测试

# 安装依赖
npm install

# 运行测试套件
npm test

测试示例

// test.js
const guardian = new SafeGuardian();

// 测试 1: 危险命令
console.log(guardian.checkToolCall('exec', { command: 'rm -rf /' }));

// 测试 2: 安全命令
console.log(guardian.checkToolCall('exec', { command: 'ls -la' }));

// 测试 3: 白名单
guardian.addWhitelistPattern(/ls\s+-la/);
console.log(guardian.checkToolCall('exec', { command: 'ls -la' }));

// 测试 4: 获取报告
console.log(guardian.getSecurityReport());

📝 API 参考

构造函数

new SafeGuardian(config?)

参数:

config (Object): 配置对象

方法

方法	返回	说明
`checkToolCall(type, data)`	Object	检查工具调用安全性
`addBlacklistPattern(pattern)`	void	添加黑名单规则
`removeBlacklistPattern(pattern)`	void	移除黑名单规则
`addWhitelistPattern(pattern)`	void	添加白名单规则
`getSecurityReport()`	Object	获取安全报告
`getAuditLogs(filter?)`	Array	获取审计日志
`exportAuditLog(path)`	void	导出审计日志
`clearAuditLogs()`	void	清空审计日志

checkToolCall 返回值

{
  allowed: boolean,      // 是否允许
  reason: string,        // 阻止原因
  details: Object,       // 详细信息
  timestamp: string     // 时间戳
}

📖 使用示例

完整示例：AI 代理安全执行

const SafeGuardian = require('safe-guardian');
const { exec } = require('child_process');

// 初始化安全守护者
const guardian = new SafeGuardian({
  mode: 'hybrid',
  safetyLevel: 'high'
});

// 安全执行函数
async function safeExec(command) {
  const result = guardian.checkToolCall('exec', { command });

  if (!result.allowed) {
    console.error('❌ 拒绝执行:', command);
    console.error('原因:', result.reason);
    return null;
  }

  console.log('✅ 允许执行:', command);
  return new Promise((resolve, reject) => {
    exec(command, (error, stdout, stderr) => {
      if (error) reject(error);
      else resolve(stdout);
    });
  });
}

// 使用
safeExec('ls -la')
  .then(output => console.log('输出:', output))
  .catch(error => console.error('错误:', error));

🐛 常见问题

Q1: 为什么某些命令被阻止？

A: 可能是以下原因：

匹配黑名单中的危险模式
尝试访问系统核心文件
修改关键系统配置

解决方案：

检查配置文件中的规则
将需要的安全命令添加到白名单
在意图验证中添加自定义规则

Q2: 如何禁用某个特定检查？

A: 使用白名单配置：

const guardian = new SafeGuardian({
  whitelist: {
    enabled: true,
    patterns: [
      /特定的安全命令/
    ]
  }
});

Q3: 日志太大怎么办？

A: 定期清理和导出日志：

// 导出并清理
guardian.exportAuditLog('./backup/audit-' + Date.now() + '.json');
guardian.clearAuditLogs();

📄 许可证

MIT-0 License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系方式

Issue: https://github.com/your-repo/safe-guardian/issues
文档: https://docs.your-repo.com/safe-guardian

🎉 更新日志

v1.1.0 (2026-04-06)

✨ 添加详细的中文文档和使用示例
✨ 改进安全评分算法
✨ 优化审计日志功能
🐛 修复某些正则匹配问题

v1.0.0 (2026-04-05)

🎉 初始版本发布

Safe Guardian

安装技能

Safe Guardian

📖 功能描述

✨ 核心功能

1. 黑名单过滤 🚫

2. 意图验证 🧠

3. 审计日志 📝

4. 策略配置 ⚙️

🚀 快速开始

安装

基本使用

📚 详细使用方法

1. 初始化配置

基础配置

高级配置

2. 工具调用检查

检查 exec 命令

检查 write 操作

检查 edit 操作

3. 获取安全报告

4. 添加自定义规则

添加黑名单规则

添加白名单规则

5. 审计日志

🎯 使用场景

场景 1: Web 应用的脚本执行安全

场景 2: AI 代理自动化运维

场景 3: 自动化文件管理

⚙️ 配置文件

配置文件格式 (config.json)

使用配置文件初始化

🔒 安全特性

📊 安全评分

🛠️ 开发与测试

运行测试

测试示例

📝 API 参考

构造函数

方法

checkToolCall 返回值

📖 使用示例

完整示例：AI 代理安全执行

🐛 常见问题

Q1: 为什么某些命令被阻止？

Q2: 如何禁用某个特定检查？

Q3: 日志太大怎么办？

📄 许可证

🤝 贡献

📞 联系方式

🎉 更新日志

v1.1.0 (2026-04-06)

v1.0.0 (2026-04-05)