Safe Guardian

A safe security layer plugin for OpenClaw that intercepts dangerous tool calls (exec, write, edit) through multi-layer blacklist/whitelist filtering and inte...

Security Scan

The package largely implements a local blacklist/whitelist logger as described, but the SKILL.md claims LLM-based intent validation and API-key usage that are not implemented, and the code will unconditionally overwrite local config files — these mismatches and surprising persistence behavior warrant caution.

Purpose & Capability

Name/description match the code's primary behavior: local blacklist/whitelist checks, intent heuristic, and audit logging. However the README/SKILL.md repeatedly claims 'LLM-based intent validation' and shows an 'llm.apiKey' field; the included code performs only local regex checks and does not call any external LLM or use API keys. That claim is inconsistent with the implementation.

Instruction Scope

SKILL.md shows code samples calling guardian.checkToolCall('exec', { command: '...' }) and demonstrates an API-key-driven LLM config. The shipped implementation exposes checkToolCall(toolCall) which expects a single string (test.js uses a single string). The SKILL.md examples and the real API do not match. Additionally, SKILL.md suggests LLM intent validation and apiKey configuration, but the runtime instructions do not correspond to the actual code paths — giving the agent incorrect runtime expectations.

Install Mechanism

No external install script or remote downloads are present; package is self-contained JavaScript with package.json and local config files. There is no network-downloading install step. This is low installation risk.

Credentials

SKILL.md references an LLM model and apiKey (e.g., qwen2.5:3b and 'apiKey'), implying credential usage, but the package declares no required env vars and the code does not read environment variables or make network calls. The documentation promising external LLM integration is not reflected in code, which is a mismatch that could mislead users about what secrets are needed or used.

Persistence & Privilege

The module writes files on initialization and will create ./config and ./logs directories. Critically, initialize() always calls createDefaultBlacklist(), which unconditionally writes ./config/blacklist.json with default rules and replaces any existing file — this can overwrite user-managed config without warning. The package does not request elevated system privileges, but its file-write behavior is potentially destructive and surprising.

What to consider before installing

This package implements local blacklist/whitelist checks and logging, but there are several red flags you should consider before installing or enabling it: - Documentation mismatch: SKILL.md repeatedly describes LLM-based intent validation and shows an apiKey field, but the shipped code performs only local regex checks and does not use any API keys or network calls. Treat LLM-related claims as unimplemented until the author updates the code. - API mismatch: Examples in the README call checkToolCall with a tool type and options object, while the actual implementation expects a single string. Your integrations may break if you rely on the documented API. - Silent overwrite risk: Initializing SafeGuardian will unconditionally write ./config/blacklist.json (createDefaultBlacklist), overwriting any existing blacklist file in that path. Run it in a sandbox first — do not run from a directory containing important configs or as root. - File writes and logs: The module creates ./config and ./logs/guardian and appends to a log file. Ensure the working directory is safe and that log/config locations are acceptable for your environment. - Testing recommendations: Run the package in an isolated environment (container or VM) and review behavior: confirm whether it overwrites configs, verify API semantics, and ensure it won’t be invoked with sensitive working directories. If you expect LLM-based intent checks, request that the author implement and document secure LLM integration (network calls, explicit env var requirements, and opt-in behavior) before trusting the skill for production use. Given these inconsistencies, do not deploy this skill to production or give it autonomous privileges until the author resolves the documentation/implementation mismatches and provides safer initialization behavior (e.g., only create default config when no config file exists, or prompt/backup existing config).

📖 功能描述

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: 可能是以下原因：

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

解决方案：

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

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)

• 🎉 初始版本发布