secucheck

Comprehensive security audit for OpenClaw. Scans 7 domains (runtime, channels, agents, cron, skills, sessions, network), supports 3 expertise levels, context-aware analysis, and visual dashboard. Read-only with localized reports.

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