clawhub-skill-scanner

# Skill Security Audit

**MANDATORY** security check before installing external skills.

Inspired by the ClawHavoc campaign that compromised 341 malicious skills on ClawHub.

## When to Use

Run this audit **BEFORE** any skill installation:
- `clawhub install <skill>`
- Manual skill download/copy
- Skills from GitHub, URLs, or untrusted sources

## Quick Start

```bash
# Scan a skill folder
python3 scripts/scan_skill.py /path/to/skill

# JSON output for automation
python3 scripts/scan_skill.py /path/to/skill --json

# Exit code 0 only if SAFE
python3 scripts/scan_skill.py /path/to/skill --install-if-safe
```

## What It Detects

### 🔴 CRITICAL (Blocks Installation)

| Category | Patterns |
|----------|----------|
| **Reverse Shells** | `nc -e`, `bash /dev/tcp`, Python socket shells |
| **Curl-Pipe-Bash** | `curl \| bash`, `wget && chmod +x` |
| **Credential Access** | ~/.ssh, ~/.aws, ~/.openclaw, .env files |
| **Data Exfiltration** | Discord/Slack webhooks, POST with secrets |
| **Malicious Domains** | glot.io, pastebin (known malware hosts) |
| **Persistence** | crontab, systemd, LaunchAgents, .bashrc |
| **Command Injection** | eval(), exec(), subprocess shell=True |
| **Obfuscation** | base64 decode pipes, pickle, marshal |

### 🟡 WARNING (Review Required)

Only patterns that are suspicious regardless of skill type:
- Raw socket usage (unusual for most skills)
- Dynamic code compilation
- File/directory deletion
- Screenshot/keyboard capture libraries
- Low-level system calls (ctypes)

### Philosophy

We intentionally **don't warn** on common patterns like:
- HTTP requests (normal for API skills)
- API key references (normal for integration skills)
- File writes (normal for data skills)
- Environment variable access (normal for config)

This reduces noise so real threats stand out.

## Risk Scoring

```
CRITICAL findings × 30 = Base score
WARNING findings × 3 (capped at 10) = Warning contribution
```

| Score | Level | Action |
|-------|-------|--------|
| 0-2...

# 🛡️ ClawHub Skill Scanner

Security scanner for [OpenClaw](https://openclaw.ai) and [ClawHub](https://clawhub.com) skill installations.

**Detect malicious patterns before they compromise your system.**

Developed in response to the [ClawHavoc campaign](https://www.esecurityplanet.com/threats/hundreds-of-malicious-skills-found-in-openclaws-clawhub/) (Feb 2026) that compromised 341 malicious skills on ClawHub.

## 🚀 Quick Start

```bash
# Install via ClawHub
clawhub install clawhub-skill-scanner

# Or clone directly
git clone https://github.com/amir-ag/clawhub-skill-scanner.git
```

## 📖 Usage

```bash
# Scan a skill folder
python3 scripts/scan_skill.py /path/to/skill

# JSON output for automation
python3 scripts/scan_skill.py /path/to/skill --json

# Exit code 0 only if SAFE (for CI/CD)
python3 scripts/scan_skill.py /path/to/skill --install-if-safe
```

## 🔍 What It Detects

### 🔴 CRITICAL (Blocks Installation)

| Category | Examples |
|----------|----------|
| **Reverse Shells** | `nc -e`, `bash /dev/tcp`, Python socket shells |
| **Curl-Pipe-Bash** | `curl \| bash`, `wget && chmod +x` |
| **Credential Access** | ~/.ssh, ~/.aws, ~/.openclaw, .env files |
| **Data Exfiltration** | Discord/Slack webhooks, POST with secrets |
| **Malicious Domains** | glot.io, pastebin (known malware hosts) |
| **Persistence** | crontab, systemd, LaunchAgents, .bashrc |
| **Command Injection** | eval(), exec(), subprocess shell=True |
| **Obfuscation** | base64 decode pipes, pickle, marshal |

### 🟡 WARNING (Review Required)

Only patterns that are suspicious regardless of skill type:
- Raw socket usage
- Dynamic code compilation  
- File/directory deletion
- Screenshot/keyboard capture libraries

## 📊 Risk Scoring

| Score | Level | Action |
|-------|-------|--------|
| 0-20 | 🟢 SAFE | Auto-approve |
| 21-50 | 🟡 CAUTION | Review findings |
| 51-80 | 🔶 DANGER | Detailed review required |
| 81-100 | 🔴 BLOCKED | Do NOT install |

## 📋 Sample Output

```
═════════════════════...