openclaw-security 0.1.0

A CLI tool to analyze, audit, and fix OpenClaw security configuration issues.

OpenClaw Security Configuration Checker & Fixer

A powerful CLI tool to audit, analyze, and fix OpenClaw security configuration issues.

✨ Features

• 🔍 Comprehensive Security Audit - Checks 15+ security configurations
• 🎨 Beautiful CLI Interface - Rich terminal output with colors and tables
• 🔧 Interactive Fixes - Apply fixes one-by-one with confirmation
• ⚡ Auto-Fix Support - One-command fixes for common issues
• 📊 Detailed Reports - Export audit results to file
• 🚀 Native Integration - Uses openclaw config set and openclaw security audit

📦 Installation

From PyPI

pip install openclaw-security

With rich terminal UI (recommended):

pip install openclaw-security[rich]

Prerequisites

• Python 3.8+
• OpenClaw CLI installed (auto-detected on Windows, macOS, and Linux)
• OpenClaw config file at ~/.openclaw/openclaw.json

Platform Support

✅ Windows - Full support with:

• Automatic openclaw CLI detection (checks npm global, Program Files, and NVM paths)
• Windows-specific file permission guidance (ACLs instead of chmod)
• Correct handling of .cmd batch files

✅ macOS - Full support with:

• Auto-detection of openclaw CLI (Homebrew, NVM, npm global)
• Standard Unix permission checks (chmod)

✅ Linux - Full support with:

• Auto-detection of openclaw CLI (NVM, npm global, /usr/local/bin)
• Standard Unix permission checks (chmod)

🔍 Platform-Specific Behavior

Windows

• File Permissions: Uses Windows ACLs (Access Control Lists) instead of Unix chmod
  • The script skips permission checks on Windows
  • Manual icacls commands are provided if you want to lock down files
• CLI Detection: Automatically finds openclaw in:
  • C:\Program Files\nodejs\openclaw.cmd
  • %APPDATA%\npm\openclaw.cmd
  • NVM installation paths

macOS

• File Permissions: Standard Unix chmod checks (700 for directories, 600 for files)
• CLI Detection: Automatically finds openclaw in:
  • ~/.nvm/versions/node/v*/bin/openclaw
  • /usr/local/bin/openclaw
  • /opt/homebrew/bin/openclaw (Apple Silicon)

Linux

• File Permissions: Standard Unix chmod checks (700 for directories, 600 for files)
• CLI Detection: Automatically finds openclaw in:
  • ~/.nvm/versions/node/v*/bin/openclaw
  • ~/.local/bin/openclaw
  • /usr/local/bin/openclaw
  • ~/.npm-global/bin/openclaw

🚀 Usage

After installing, use the osc command:

Basic Audit

Run security checks only (no fixes):

osc --check

Interactive Fix Mode

Audit + interactive fix session:

osc --fix

Auto-Fix All Issues

Apply all auto-fixable issues without prompting:

osc --fix-all

Run Official Audit

Run the native openclaw security audit command:

osc --audit

# With deep scan
osc --audit --deep

Export Report

Export audit results to file:

osc --export security-report.txt

Use Custom Config

Audit a specific config file:

osc --config /path/to/openclaw.json

Combined Options

Audit, fix all, and export report:

osc --fix-all --export report.txt

🔍 Security Checks

The tool checks the following areas:

Gateway Security

• ✅ Gateway authentication configured
• ✅ Gateway token strength
• ✅ Bind mode (loopback vs LAN/tailnet)
• ✅ Trusted proxies configured

Channel Security

• ✅ Group policies (avoid "open")
• ✅ Group allowlists configured
• ✅ DM policies configured

Sandbox Security

• ✅ Sandbox mode enabled
• ✅ Workspace access (none/ro/rw)
• ✅ Sandbox scope (session/agent/shared)
• ✅ Docker capabilities dropped

Tool Security

• ✅ Tool allow/deny lists
• ✅ Elevated tools restricted
• ✅ Dangerous tools not globally allowed

Session Security

• ✅ DM session isolation (per-channel-peer)

File Security

• ✅ File permissions (~/.openclaw = 700)
• ✅ Config file permissions (600)
• ✅ Credentials directory permissions (700)

Command Security

• ✅ Bash commands disabled
• ✅ Config commands restricted
• ✅ Access groups enforced

Browser Security

• ✅ Browser tool restrictions
• ✅ Browser proxy mode

Docker Security

• ✅ Container network settings
• ✅ Container user (non-root)

Runtime Security

• ✅ Node.js version (22.12.0+ required)

Other

• ✅ Logging redaction enabled
• ✅ mDNS mode (minimal/off)

🔧 Auto-Fixable Issues

The following issues can be automatically fixed:

Issue	Fix Applied
Gateway authentication	Generates new token via openclaw doctor --generate-gateway-token
Sandbox disabled	Sets agents.defaults.sandbox.mode = "non-main"
mDNS full mode	Sets discovery.mdns.mode = "minimal"
DM isolation	Sets session.dmScope = "per-channel-peer"
Logging redaction	Sets logging.redactSensitive = "tools"
File permissions	Runs chmod 700/600 on directories/files (Unix/Linux/macOS only)
Access groups	Sets commands.useAccessGroups = true
Docker capDrop	Sets agents.defaults.sandbox.docker.capDrop = ["ALL"]

✅ Verifying Settings After Fix

After running fixes, verify your configuration:

Re-Run Security Check

osc --check

Use OpenClaw CLI Commands

openclaw config get agents.defaults.sandbox.mode
openclaw config get session.dmScope
openclaw config get discovery.mdns.mode
openclaw config get agents.defaults.sandbox.docker.capDrop

Restart Gateway (Required!)

Configuration changes require a gateway restart:

openclaw gateway restart
openclaw gateway status

⚠️ Manual Fixes Required

Some issues require manual intervention:

• Group policies: Need to manually configure allowlists in config
• Tool restrictions: Need to review and adjust tool allow/deny lists per agent
• Node.js version: Must upgrade Node.js manually
• Network exposure: Need to configure firewall rules
• Elevated tools: Need to review tools.elevated.allowFrom settings

📋 Command Reference

usage: osc [-h] [--check] [--fix] [--fix-all]
           [--audit] [--deep] [--export FILE]
           [--config FILE] [-v]

Audit and fix OpenClaw security configuration

options:
  -h, --help            Show help message and exit
  --check               Run security checks only (no fixes)
  --fix                 Run interactive fix session after checks
  --fix-all             Apply all auto-fixable issues without prompting
  --audit               Run official openclaw security audit command
  --deep                Run deep audit (with --audit flag)
  --export FILE         Export report to file
  --config FILE         Use custom config file path
  -v, --verbose         Verbose output

🔐 Security Best Practices

1. Always run openclaw security audit --deep first
2. Never bind Gateway to LAN - Use loopback or Tailscale Serve
3. Enable sandboxing for non-main sessions
4. Use strong, random gateway tokens (16+ characters)
5. Restrict elevated tools to owner only
6. Set file permissions: 700 for dirs, 600 for config files
7. Enable mention gating in groups - Require @-mentions
8. Isolate DM sessions - Use per-channel-peer scope
9. Keep logging redaction on - Unless actively debugging
10. Run this tool regularly - Especially after config changes

🐛 Troubleshooting

"openclaw command not found"

Ensure OpenClaw CLI is installed and in your PATH:

npm install -g openclaw

"Config file not found"

Check that ~/.openclaw/openclaw.json exists:

ls -la ~/.openclaw/

Rich library not found

Install with the rich extra:

pip install openclaw-security[rich]

🤝 Contributing

This tool is designed to be extensible. To add new checks:

1. Add a new check method to OpenClawSecurityChecker class
2. Call it in run_all_checks() method
3. Add corresponding fix method if applicable
4. Update this README

📄 License

MIT License - see LICENSE for details.

🙏 Credits

Built with ❤️ using:

• Rich - Beautiful terminal output
• OpenClaw - The awesome AI assistant framework

---

Made By Umer Farooq