Metadata-Version: 2.4
Name: openclaw-security
Version: 0.1.0
Summary: A CLI tool to analyze, audit, and fix OpenClaw security configuration issues.
Project-URL: Homepage, https://github.com/umerfarooq/openclaw-security
Project-URL: Repository, https://github.com/umerfarooq/openclaw-security
Project-URL: Bug Tracker, https://github.com/umerfarooq/openclaw-security/issues
Author-email: Umer Farooq <support@umerfarooq.me>
License-Expression: MIT
License-File: LICENSE
Keywords: audit,cli,configuration,openclaw,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Provides-Extra: rich
Requires-Dist: rich>=13.0.0; extra == 'rich'
Description-Content-Type: text/markdown

# OpenClaw Security Configuration Checker & Fixer

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

![Python](https://img.shields.io/badge/Made%20with-Python-blue?style=for-the-badge)
![Security](https://img.shields.io/badge/Type-Security%20Audit-red?style=for-the-badge)
[![PyPI version](https://img.shields.io/pypi/v/openclaw-security?style=for-the-badge)](https://pypi.org/project/openclaw-security/)

## ✨ 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

```bash
pip install openclaw-security
```

With rich terminal UI (recommended):

```bash
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):

```bash
osc --check
```

### Interactive Fix Mode

Audit + interactive fix session:

```bash
osc --fix
```

### Auto-Fix All Issues

Apply all auto-fixable issues without prompting:

```bash
osc --fix-all
```

### Run Official Audit

Run the native `openclaw security audit` command:

```bash
osc --audit

# With deep scan
osc --audit --deep
```

### Export Report

Export audit results to file:

```bash
osc --export security-report.txt
```

### Use Custom Config

Audit a specific config file:

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

### Combined Options

Audit, fix all, and export report:

```bash
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

```bash
osc --check
```

### Use OpenClaw CLI Commands

```bash
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:

```bash
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:
```bash
npm install -g openclaw
```

### "Config file not found"
Check that `~/.openclaw/openclaw.json` exists:
```bash
ls -la ~/.openclaw/
```

### Rich library not found
Install with the rich extra:
```bash
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](LICENSE) for details.

## 🙏 Credits

Built with ❤️ using:
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output
- OpenClaw - The awesome AI assistant framework

---

**Made By Umer Farooq**
