Secucheck

# secucheck - OpenClaw Security Audit

Comprehensive security audit skill for OpenClaw deployments. Analyzes configuration, permissions, exposure risks, and runtime environment with context-aware recommendations.

---

## Summary

**secucheck** performs read-only security audits of your OpenClaw setup:

- **7 audit domains**: Runtime, Channels, Agents, Cron Jobs, Skills, Sessions, Network - **3 expertise levels**: Beginner (analogies), Intermediate (technical), Expert (attack vectors) - **Context-aware**: Considers VPN, single-user, self-hosted scenarios - **Runtime checks**: Live system state (network exposure, containers, privileges) - **Dashboard**: Visual HTML report with security score - **Localized output**: Final report matches user's language

**Never modifies configuration automatically.** All fixes require explicit user confirmation.

---

## Quick Start

### Installation ```bash clawhub install secucheck ```

### Usage Ask your OpenClaw agent: - "security audit" - "secucheck" - "run security check"

### Expertise Levels When prompted, choose your level: 1. **Beginner** - Simple analogies, no jargon 2. **Intermediate** - Technical details, config examples 3. **Expert** - Attack vectors, edge cases, CVEs

All levels run the same checks—only explanation depth varies.

### Dashboard ``` "show dashboard" / "visual report" ``` Opens an HTML report in your browser.

---

## Example Output

``` 🔒 Security Audit Results

🟡 Needs Attention

| Severity | Count | |----------|-------| | 🔴 Critical | 0 | | 🟠 High | 0 | | 🟡 Medium | 2 | | 🟢 Low | 3 |

### 🟡 Agent "molty": exec + external content processing ... ```

---

## Features

- 🔍 **Comprehensive**: Channels, agents, cron, skills, sessions, network, runtime - 👤 **3 Expertise Levels**: Beginner / Intermediate / Expert - 🌏 **Localized**: Final report in user's language - 🎯 **Attack Scenarios**: Real-world exploitation paths - ⚡ **Runtime Checks**: VPN, containers, privileges, network exposure - 🎨 **Dashboard**: Visual HTML report with security score

---

# Agent Instructions

*Everything below is for the agent executing this skill.*

---

## When to Use

Trigger this skill when: - User requests security checkup/audit - **Auto-trigger**: Installing skills, creating/modifying agents, adding/modifying cron jobs - Periodic review (recommended: weekly)

## Expertise Levels

| Level | Identifier | Style | |-------|------------|-------| | Beginner | `1`, `beginner` | Analogies, simple explanations, no jargon | | Intermediate | `2`, `intermediate` | Technical details, config examples | | Expert | `3`, `expert` | Attack vectors, edge cases, CVE references |

## Execution Flow

### Step 1: Ask Level (before running anything)

Present options in user's language. Example (English):

``` What level of technical detail do you prefer?

1. 🌱 Beginner - I'll explain simply with analogies 2. 💻 Intermediate - Technical details and config examples 3. 🔐 Expert - Include attack vectors and edge cases

📌 All levels run the same checks—only explanation depth varies. ```

**STOP HERE. Wait for user response.**

### Step 2: Run Audit

```bash bash ~/.openclaw/skills/secucheck/scripts/full_audit.sh ```

Returns JSON with findings categorized by severity.

### Step 3: Format Output

Parse JSON output and format based on user's expertise level. **Final report must be in user's language.**

#### Report Structure (Organize by Category)

``` 🔒 Security Audit Results

📊 Summary Table | Severity | Count | |----------|-------| | 🔴 Critical | X | | ...

⚡ Runtime - [findings related to RUNTIME category]

🤖 Agents - [findings related to AGENT category]

📁 Workspace - [findings related to WORKSPACE category]

🧩 Skills - [findings related to SKILL category]

📢 Channels - [findings related to CHANNEL category]

🌐 Network - [findings related to NETWORK category] ```

Group findings by their `category` field, not just severity. Within each category, show severity icon and explain.

### Step 4: Auto-Open Dashboard

After text report, automatically generate and serve dashboard:

```bash bash ~/.openclaw/skills/secucheck/scripts/serve_dashboard.sh ```

The script returns JSON with `url` (LAN IP) and `local_url` (localhost). **Use the `url` field** (not localhost) when telling the user — they may access from another device.

Example: ``` 📊 대시보드도 열었어요: http://192.168.1.200:8766/secucheck-report.html ```

If running in environment where browser can be opened, use browser tool to open it.

## Cross-Platform Support

Scripts run on Linux, macOS, and WSL. Check the JSON output for platform info:

```json { "os": "linux", "os_variant": "ubuntu", "in_wsl": false, "in_dsm": false, "failed_checks": ["external_ip"] } ```

### Platform Detection

| Field | Values | |-------|--------| | `os` | `linux`, `macos`, `windows`, `unknown` | | `os_variant` | `ubuntu`, `arch`, `dsm`, `wsl`, version string | | `in_wsl` | `true` if Windows Subsystem for Linux | | `in_dsm` | `true` if Synology DSM |

### Handling Failed Checks

If `failed_checks` array is non-empty, run fallback commands based on platform:

#### Network Info Fallbacks

| Platform | Command | |----------|---------| | Linux | `ip addr show` or `ifconfig` | | macOS | `ifconfig` | | WSL | `ip addr show` (or check Windows via `cmd.exe /c ipconfig`) | | Windows | PowerShell: `Get-NetIPAddress` | | DSM | `ifconfig` or `/sbin/ip addr` |

#### Gateway Binding Fallbacks

| Platform | Command | |----------|---------| | Linux | `ss -tlnp \| grep :18789` or `netstat -tlnp` | | macOS | `lsof -iTCP:18789 -sTCP:LISTEN` | | Windows | PowerShell: `Get-NetTCPConnection -LocalPort 18789` |

#### File Permissions Fallbacks

| Platform | Command | |----------|---------| | Linux/macOS | `ls -la ~/.openclaw` | | Windows | PowerShell: `Get-Acl $env:USERPROFILE\.openclaw` |

### Windows Native Support

If `os` is `windows` and scripts fail completely:

1. Use PowerShell commands directly: ```powershell # Network exposure Get-NetTCPConnection -LocalPort 18789 -State Listen

# File permissions Get-Acl "$env:USERPROFILE\.openclaw"

# Process info Get-Process | Where-Object {$_.Name -like "*openclaw*"} ```

2. Report what you can check and note Windows-specific limitations.

### Minimal Environments (Docker, DSM)

Some environments lack tools. Check output and supplement:

| Missing Tool | Fallback | |--------------|----------| | `curl` | `wget -qO-` | | `ss` | `netstat` | | `ip` | `ifconfig` or `/sbin/ip` | | `pgrep` | `ps aux \| grep` |

### Agent Decision Flow

``` 1. Run full_audit.sh 2. Check "failed_checks" in output 3. For each failed check: a. Identify platform from os/os_variant b. Run platform-specific fallback command c. Incorporate results into report 4. Note any checks that couldn't complete ```

## Dashboard Generation

When user requests visual report:

```bash bash ~/.openclaw/skills/secucheck/scripts/serve_dashboard.sh ```

Returns: ```json { "status": "ok", "url": "http://localhost:8766/secucheck-report.html", "pid": 12345 } ```

Provide URL directly to user.

## Detailed Check References

Read these only when deep explanation needed:

| File | Domain | |------|--------| | `checks/runtime.md` | Live system state | | `checks/channels.md` | Channel policies | | `checks/agents.md` | Agent permissions | | `checks/cron.md` | Scheduled jobs | | `checks/skills.md` | Installed skills | | `checks/sessions.md` | Session isolation | | `checks/network.md` | Network configuration |

## Attack Scenario Templates

Use these for expert-level explanations:

| File | Scenario | |------|----------| | `scenarios/prompt-injection.md` | External content manipulation | | `scenarios/session-leak.md` | Cross-session data exposure | | `scenarios/privilege-escalation.md` | Tool permission abuse | | `scenarios/credential-exposure.md` | Secret leakage | | `scenarios/unauthorized-access.md` | Access control bypass |

## Risk Levels

``` 🔴 Critical - Immediate action required. Active exploitation possible. 🟠 High - Significant risk. Should fix soon. 🟡 Medium - Notable concern. Plan to address. 🟢 Low - Minor issue or best practice recommendation. ⚪ Info - Not a risk, but worth noting. ```

## Risk Matrix

``` Tool Permissions Minimal Full ┌──────────┬──────────┐ Exposure │ 🟢 │ 🟡 │ Low │ Safe │ Caution │ ├──────────┼──────────┤ │ 🟡 │ 🔴 │ High │ Caution │ Critical │ └──────────┴──────────┘

Exposure = Who can talk to the bot (DM policy, group access, public channels) Tool Permissions = What the bot can do (exec, file access, messaging, browser) ```

## Context-Aware Exceptions

Don't just pattern match. Consider context:

| Context | Adjustment | |---------|------------| | Private channel, 2-3 trusted members | Lower risk even with exec | | VPN/Tailscale only access | Network exposure less critical | | Self-hosted, single user | Session isolation less important | | Containerized environment | Privilege escalation less severe |

Always ask about environment if unclear.

## Applying Fixes

**CRITICAL RULES:**

1. **Never auto-apply fixes.** Always show suggestions first. 2. **Warn about functional impact.** If a fix might break something, say so. 3. **Get explicit user confirmation** before any config changes.

Example flow: ``` Agent: "Changing this setting will disable exec in #dev channel. If you're using code execution there, it will stop working. Apply this fix?" User: "yes" Agent: [apply fix via gateway config.patch] ```

## Language Rules

- **Internal processing**: Always English - **Thinking/reasoning**: Always English - **Final user-facing report**: Match user's language - **Technical terms**: Keep in English (exec, cron, gateway, etc.)

## Auto-Review Triggers

Invoke automatically when:

1. **Skill installation**: `clawhub install <skill>` or manual addition 2. **Agent creation/modification**: New agent or tool changes 3. **Cron job creation/modification**: New or modified scheduled tasks

For auto-reviews, focus only on changed component unless full audit requested.

## Quick Commands

| User Request | Action | |--------------|--------| | "check channels only" | Run channels.md check | | "audit cron jobs" | Run cron.md check | | "full audit" | All checks | | "more detail" | Re-run with verbose output |

## Trust Hierarchy

Apply appropriate trust levels:

| Level | Entity | Trust Model | |-------|--------|-------------| | 1 | Owner | Full trust — has all access | | 2 | AI Agent | Trust but verify — sandboxed, logged | | 3 | Allowlists | Limited trust — specified users only | | 4 | Strangers | No trust — blocked by default |

## Incident Response Reference

If compromise suspected:

### Containment 1. Stop gateway process 2. Set gateway.bind to loopback (127.0.0.1) 3. Disable risky DM/group policies

### Rotation 1. Regenerate gateway auth token 2. Rotate browser control tokens 3. Revoke and rotate API keys

### Review 1. Check gateway logs and session transcripts 2. Review recent config changes 3. Re-run full security audit

## Files Reference

``` ~/.openclaw/skills/secucheck/ ├── SKILL.md # This file ├── skill.json # Package metadata ├── README.md # User documentation ├── scripts/ │ ├── full_audit.sh # Complete audit (JSON output) │ ├── runtime_check.sh # Live system checks │ ├── gather_config.sh # Config extraction (redacted) │ ├── gather_skills.sh # Skill security scan │ ├── gather_agents.sh # Agent configurations │ ├── serve_dashboard.sh # Generate + serve HTML report │ └── generate_dashboard.sh ├── dashboard/ │ └── template.html # Dashboard template ├── checks/ │ ├── runtime.md # Runtime interpretation │ ├── channels.md # Channel policy checks │ ├── agents.md # Agent permission checks │ ├── cron.md # Cron job checks │ ├── skills.md # Skill safety checks │ ├── sessions.md # Session isolation │ └── network.md # Network exposure ├── scenarios/ │ ├── prompt-injection.md │ ├── session-leak.md │ ├── privilege-escalation.md │ ├── credential-exposure.md │ └── unauthorized-access.md └── templates/ ├── report.md # Full report template ├── finding.md # Single finding template └── summary.md # Quick summary template ```

## Security Assessment Questions

When auditing, consider:

1. **Exposure**: What network interfaces can reach this agent? 2. **Authentication**: What verification does each access point require? 3. **Isolation**: What boundaries exist between agent and host? 4. **Trust**: What content sources are considered "trusted"? 5. **Auditability**: What evidence exists of agent's actions? 6. **Least Privilege**: Does agent have only necessary permissions?

---

**Remember:** This skill exists to make OpenClaw self-aware of its security posture. Use regularly, extend as needed, never skip the audit.