octoguard-openclaw-security-governance

# OctoGuard OpenClaw Security Governance > Skill by [ara.so](https://ara.so) — Security Skills collection. OctoGuard is a security governance and audit system designed for OpenClaw (Lobster AI). It monitors user conversations, tool invocations, and execution results in real-time, enforcing security policies and sending alerts when high-risk behaviors are detected. The system operates as a transparent proxy without modifying OpenClaw's core functionality. ## What It Does - **Policy-Based Interception**: Blocks sensitive file access, dangerous operations, and high-risk commands before execution - **Token Monitoring**: Tracks token consumption across sessions with threshold-based alerting - **Audit Logging**: Records all events processed through OpenClaw including allowed and blocked actions - **Alert Notifications**: Sends notifications via DingTalk, WeChat Work, and Email when security events occur - **Visual Dashboard**: Provides security posture visualization and OpenClaw gateway control - **Non-Invasive Design**: Works alongside OpenClaw without code modifications ## Architecture OctoGuard consists of: - **Backend**: Node.js-based policy engine and API server - **Frontend**: Vue.js dashboard for policy management and monitoring - **Database**: Stores policies, audit logs, and token metrics - **Security Proxy**: Intercepts and evaluates OpenClaw requests ## Installation ### Prerequisites ```bash # Node.js 14+ required node --version # Database (MySQL/PostgreSQL) # OpenClaw must be installed and accessible ``` ### Backend Setup ```bash # Clone the repository git clone https://github.com/O-ozzz/OctoGuard--Free-OpenClaw-Security-Supervision-System.git cd OctoGuard--Free-OpenClaw-Security-Supervision-System/backend # Install dependencies npm install # Configure environment cp .env.example .env ``` ### Environment Configuration Edit `backend/.env`: ```bash # Server Configuration PORT=3000 NODE_ENV=production # Database Connection DB_TYPE=mysql DB_HOST=localhost DB_PORT=3306 DB_NAME=octoguard DB_USER=${DB_USERNAME} DB_PASSWORD=${DB_PASSWORD} # OpenClaw Integration OPENCLAW_HOST=localhost OPENCLAW_PORT=8080 OPENCLAW_API_KEY=${OPENCLAW_API_KEY} # Alert Notifications DINGTALK_WEBHOOK=${DINGTALK_WEBHOOK_URL} WECHAT_WEBHOOK=${WECHAT_WEBHOOK_URL} EMAIL_SMTP_HOST=smtp.gmail.com EMAIL_SMTP_PORT=587 EMAIL_USER=${EMAIL_ADDRESS} EMAIL_PASSWORD=${EMAIL_APP_PASSWORD} EMAIL_RECIPIENTS=security@company.com # Token Monitoring TOKEN_THRESHOLD_WARNING=100000 TOKEN_THRESHOLD_CRITICAL=200000 ``` ### Database Initialization ```bash # Run migrations npm run migrate # Seed initial policies (optional) npm run seed ``` ### Start Services ```bash # Start backend cd backend npm start # Start frontend (separate terminal) cd frontend npm install npm run serve ``` ### Production Deployment ```bash # Build frontend cd frontend npm run build # Use PM2 for backend npm install -g pm2 cd backend pm2 start server.js --name octoguard pm2 save pm2 startup ``` ## Configuration ### Proxy Setup Configure OpenClaw to route through OctoGuard: ```javascript // openclaw-config.js module.exports = { proxy: { enabled: true, host: 'localhost', port: 3000, path: '/api/proxy' }, security: { auditEnabled: true, blockingMode: true } } ``` ### Policy Engine Configuration Create security policies via API or dashboard: ```javascript // policy-config.js const policyExamples = { // Block sensitive file access fileSecurity: { name: "Block Sensitive File Access", type: "file_access", enabled: true, rules: [ { pattern: "/etc/passwd", action: "block", severity: "critical" }, { pattern: ".*\\.env$", action: "block", severity: "high" }, { pattern: "/home/.*/.ssh/.*", action: "block", severity: "critical" } ] }, // Block dangerous commands commandSecurity: { name: "Block Dangerous Commands", type: "command_execution", enabled: true, rules: [ { pattern: "rm -rf", action: "block", severity: "critical" }, { pattern: "curl.*\\|.*bash", action: "block", severity: "high" }, { pattern: "chmod 777", action: "warn", severity: "medium" } ] } }; ``` ## API Usage ### Create Security Policy ```javascript const axios = require('axios'); async function createPolicy(policy) { try { const response = await axios.post('http://localhost:3000/api/policies', { name: policy.name, type: policy.type, enabled: policy.enabled, rules: policy.rules, alertOnBlock: true, notificationChannels: ['dingtalk', 'email'] }, { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } }); console.log('Policy created:', response.data.id); return response.data; } catch (error) { console.error('Failed to create policy:', error.response?.data); throw error; } } // Example usage createPolicy({ name: "Block Database Dumps", type: "command_execution", enabled: true, rules: [{ pattern: "mysqldump|pg_dump", action: "block", severity: "high" }] }); ``` ### Query Audit Logs ```javascript async function getAuditLogs(filters = {}) { const params = new URLSearchParams({ page: filters.page || 1, limit: filters.limit || 50, action: filters.action || '', // 'blocked', 'allowed', 'warned' severity: filters.severity || '', startDate: filters.startDate || '', endDate: filters.endDate || '' }); const response = await axios.get( `http://localhost:3000/api/audit/logs?${params}`, { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } } ); return response.data; } // Get blocked events from last 24 hours const blocked = await getAuditLogs({ action: 'blocked', startDate: new Date(Date.now() - 86400000).toISOString() }); ``` ### Monitor Token Usage ```javascript async function getTokenMetrics() { const response = await axios.get( 'http://localhost:3000/api/tokens/metrics', { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } } ); const { total, sessions, threshold, alerts } = response.data; console.log(`Total tokens: ${total}`); console.log(`Active sessions: ${sessions.length}`); console.log(`Threshold: ${threshold.warning}/${threshold.critical}`); if (total > threshold.critical) { console.warn('CRITICAL: Token usage exceeds threshold!'); } return response.data; } // Set up periodic monitoring setInterval(async () => { const metrics = await getTokenMetrics(); // Custom logic here }, 300000); // Every 5 minutes ``` ### Control OpenClaw Gateway ```javascript async function controlGateway(action) { const response = await axios.post( 'http://localhost:3000/api/gateway/control', { action }, // 'stop', 'start', 'restart', 'status' { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } } ); return response.data; } // Check gateway status const status = await controlGateway('status'); console.log('OpenClaw status:', status.running ? 'Running' : 'Stopped'); // Emergency shutdown if (criticalThreatDetected) { await controlGateway('stop'); console.log('Gateway shut down for security'); } ``` ## Common Patterns ### Real-Time Request Monitoring ```javascript const WebSocket = require('ws'); function monitorRequests() { const ws = new WebSocket('ws://localhost:3000/api/monitor/stream', { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } }); ws.on('message', (data) => { const event = JSON.parse(data); switch (event.type) { case 'request': console.log(`[${event.timestamp}] Request: ${event.command}`); break; case 'blocked': console.error(`[BLOCKED] ${event.command} - Reason: ${event.reason}`); // Send to SIEM break; case 'token_threshold': console.warn(`Token usage: ${event.usage}/${event.threshold}`); break; } }); ws.on('error', (error) => { console.error('WebSocket error:', error); }); } monitorRequests(); ``` ### Dynamic Policy Updates ```javascript async function updatePolicyRules(policyId, newRules) { const response = await axios.patch( `http://localhost:3000/api/policies/${policyId}`, { rules: newRules }, { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } } ); console.log(`Policy ${policyId} updated`); return response.data; } // Add new rule to existing policy const currentPolicy = await axios.get( `http://localhost:3000/api/policies/${policyId}` ); currentPolicy.data.rules.push({ pattern: "nc -l", action: "block", severity: "high" }); await updatePolicyRules(policyId, currentPolicy.data.rules); ``` ### Custom Alert Handler ```javascript async function setupCustomAlerts() { const response = await axios.post( 'http://localhost:3000/api/alerts/webhook', { url: process.env.CUSTOM_WEBHOOK_URL, events: ['blocked', 'critical'], format: 'json', headers: { 'X-Custom-Auth': process.env.WEBHOOK_SECRET } }, { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } } ); return response.data; } // Your webhook endpoint receives: // { // "event": "blocked", // "timestamp": "2026-06-04T18:10:31Z", // "severity": "critical", // "command": "rm -rf /", // "policy": "Block Dangerous Commands", // "user": "external_user_123" // } ``` ### Bulk Policy Management ```javascript async function bulkPolicyOperation(operation, policyIds) { const response = await axios.post( 'http://localhost:3000/api/policies/bulk', { operation, // 'enable', 'disable', 'delete' policyIds }, { headers: { 'Authorization': `Bearer ${process.env.OCTOGUARD_API_KEY}` } } ); return response.data; } // Disable all policies temporarily for maintenance const allPolicies = await axios.get('http://localhost:3000/api/policies'); const policyIds = allPolicies.data.map(p => p.id); await bulkPolicyOperation('disable', policyIds); // Re-enable after maintenance await bulkPolicyOperation('enable', policyIds); ```