octoguard-openclaw-security-supervision

用途

OctoGuard（章鱼卫士）是专为 OpenClaw AI 智能体设计的安全治理与审计系统。它位于外部用户与 OpenClaw 之间，作为安全网关拦截所有请求，在请求到达 AI 智能体之前通过安全策略引擎进行检测，从而对用户对话命令、工具调用和执行结果提供实时检测、策略控制与告警通知。系统以非侵入方式运行，不修改 OpenClaw 的核心功能。

请求流向为：用户请求 → OctoGuard 安全网关 → 策略引擎 → OpenClaw → AI 智能体，同时产生审计日志与告警。

主要能力

基于策略的拦截：配置规则以阻止敏感文件访问、危险操作和高风险行为。
Token 监控：实时跟踪 token 使用量并支持阈值告警。
审计日志：记录所有 OpenClaw 事件、允许的动作和被阻止的尝试。
可视化策略管理：基于 Web 的仪表盘用于管理安全策略。
OpenClaw 网关控制：监控和控制 OpenClaw 网关状态。
多通道告警：通过钉钉、企业微信和邮件推送通知。
安全仪表盘：全面可视化 OpenClaw 安全态势。

使用方式

前置条件

Node.js（v14+）
MySQL 数据库
正在运行的 OpenClaw 实例
钉钉/企业微信 webhook（可选，用于告警）

后端安装

# Clone the repository
git clone https://github.com/O-ozzz/OctoGuard--Free-OpenClaw-Security-Supervision-System.git
cd OctoGuard--Free-OpenClaw-Security-Supervision-System

# Install backend dependencies
cd backend
npm install

# Configure database connection
# Edit config/database.js

数据库配置（config/database.js）：

module.exports = {
  host: process.env.DB_HOST || 'localhost',
  port: process.env.DB_PORT || 3306,
  user: process.env.DB_USER || 'root',
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME || 'octoguard',
  connectionLimit: 10,
  waitForConnections: true,
  queueLimit: 0
};

环境变量（.env）：

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=octoguard

# Server
PORT=3000
NODE_ENV=production

# OpenClaw Gateway
OPENCLAW_HOST=localhost
OPENCLAW_PORT=8080
OPENCLAW_API_KEY=your_openclaw_key

# Alert Webhooks
DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN
WECHAT_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
EMAIL_TO=security-team@company.com

初始化数据库并启动后端：

# Run database migrations
npm run migrate

# Start backend server
npm start
# Backend runs on http://localhost:3000

前端安装

# Install frontend dependencies
cd ../frontend
npm install

# Configure API endpoint
# Edit .env or config file
echo "VITE_API_BASE_URL=http://localhost:3000" > .env

# Build and run frontend
npm run build
npm run preview
# Or for development
npm run dev

核心 API

安全策略管理：

创建安全策略：POST /api/policies
列出启用的策略：GET /api/policies
切换策略状态：PATCH /api/policies/:id

请求拦截：通过中间件调用策略引擎评估请求，若动作为 block 则记录审计日志、发送告警并返回 403；否则记录允许日志并放行。

Token 监控：

跟踪 token 使用：POST /api/tokens/track
获取 token 统计：GET /api/tokens/stats
设置 token 阈值告警：POST /api/tokens/threshold

审计日志：

查询审计日志：GET /api/audit/logs
导出审计报告：GET /api/audit/export（支持 csv 或 json）

常见安全策略模式

资料中给出了四类示例策略：

文件系统保护：阻止对 /etc、/root、.ssh、.pem、.key、password、secret 等敏感路径与凭据的访问。
网络请求过滤：阻止对内部网络地址（10.x、172.16-31.x、192.168.x、localhost、127.0.0.x）的请求。
命令执行防护：阻止危险 shell 命令，如 rm -rf、dd if=、mkfs、format、sudo、su、写入 /dev/sd、管道到 sh、nc -l、iptables 等。
数据外泄检测：组合规则，检测先读取 database/backup/export/dump 类文件、随后在 5 分钟内发起 http_request 或 ftp_upload 的连续行为。

告警配置

钉钉：通过 DINGTALK_WEBHOOK 发送 markdown 格式告警消息。
邮件：使用 nodemailer 通过 EMAIL_HOST、EMAIL_PORT、EMAIL_USER、EMAIL_PASSWORD、EMAIL_TO 发送 HTML 告警邮件。

策略引擎实现

策略引擎按优先级加载启用的策略，逐条检查工具调用条件（工具名、正则模式匹配参数内容）和用户输入条件，命中则返回对应动作、原因和策略名，否则返回 allow。

OpenClaw 网关控制

获取状态：请求 OpenClaw 的 /health 端点，返回 running/stopped 及健康信息。
关闭网关：向 /admin/shutdown 发送带 X-API-Key 的 POST 请求。

故障排查

策略未拦截请求：检查策略优先级与条件，可使用调试函数打印策略条件、测试请求与匹配结果。
告警未发送：验证 webhook 配置（资料原文在此处截断，后续内容暂未提供）。

适用场景

适用于需要对 OpenClaw AI 智能体进行安全治理与审计的场景，例如：限制智能体访问敏感文件与凭据、阻止危险系统命令、防止对内部网络的访问、检测潜在数据外泄行为、监控 token 消耗并设置告警、保留完整的操作审计记录，以及通过钉钉、企业微信或邮件及时接收安全告警。

限制

需要 Node.js（v14+）与 MySQL 数据库，并需已有运行中的 OpenClaw 实例。
钉钉/企业微信 webhook 为可选，仅用于告警。
资料未提供收费、价格、平台兼容性、性能指标或效果保证等信息。
故障排查部分原文在“Verify webhook configuration”处截断，后续内容暂未提供。