skillguard

# SkillGuard 🛡️

AI-powered security scanner for OpenClaw skills. Analyzes skill code for malicious behaviour before you install it.

## Commands

### Scan before install (recommended)

```bash
skillguard install <skill-name>
```

Downloads the skill to a temp directory, runs AI security analysis, shows verdict, then asks for confirmation before installing via clawhub.

**Example:**
```
skillguard install my-new-skill
```

### Audit installed skills

```bash
skillguard audit
```

Scans all skills in `/usr/lib/node_modules/openclaw/skills/`, `~/.openclaw/workspace/skills/`, and `~/.openclaw/skills/`. Prints a table summary with details on any flagged skills.

### Scan a local path

```bash
skillguard scan <path>
```

Scan any local skill directory without installing. Useful for reviewing skills you've already downloaded or developed locally.

**Example:**
```
skillguard scan ./my-skill-folder
skillguard scan /usr/lib/node_modules/openclaw/skills/some-skill
```

## Risk Levels

| Level  | Meaning |
|--------|---------|
| ✅ CLEAN  | No security issues detected |
| 🟡 LOW    | Minor concerns, generally safe |
| ⚠️ MEDIUM | Review recommended before installing |
| 🚨 HIGH   | Dangerous — do not install without careful manual review |

## What Gets Checked

- **Credential theft**: Reads to `~/.ssh/`, `~/.openclaw/`, API keys, `.env` files
- **Data exfiltration**: curl/wget/fetch POSTing data to external servers
- **Reverse shells**: netcat, bash TCP redirects, socat to external IPs
- **Privilege escalation**: sudo abuse, setuid bits, writing to `/etc/`
- **Persistence**: cron installs, systemd units, `.bashrc` modifications
- **Obfuscation**: base64-piped-to-bash, eval with dynamic content
- **Package smuggling**: undisclosed npm/pip installs
- **Reconnaissance**: network scanning, system info harvesting

## Usage by the AI Agent

When the user asks to install a skill, use skillguard first:

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py instal...

# SkillGuard 🛡️

AI-powered security scanner for OpenClaw skills.

SkillGuard uses LLM analysis to detect malicious code in OpenClaw skills before you install them — catching credential theft, data exfiltration, reverse shells, and other threats.

## Quick Start

```bash
# Scan + install a skill from clawhub (safest way to install)
python3 skillguard.py install some-skill-name

# Audit all installed skills
python3 skillguard.py audit

# Scan a local skill directory
python3 skillguard.py scan /path/to/skill
```

## How It Works

1. **Collect** — Reads SKILL.md + all scripts (.sh, .py, .js, etc.) up to 100KB each
2. **Analyze** — Sends file contents to Claude Opus (or configured LLM) with a focused security prompt
3. **Report** — Displays risk level (CLEAN / LOW / MEDIUM / HIGH) + specific findings
4. **Confirm** — For `install`, asks for confirmation before proceeding

## Example Output

```
🚨 SkillGuard: suspicious-skill — Risk: HIGH
   Reads /root/.openclaw/openclaw.json and sends to external IP.

   [HIGH] Data Exfiltration: curl POST of ~/.openclaw/*.json to 45.33.32.156 [init.sh:14-22]
   [MEDIUM] Credential Theft: Reads ~/.ssh/id_rsa without disclosure [setup.sh:8]

   ⚠ HIGH RISK: This skill is dangerous to install.
Install suspicious-skill anyway? (type YES to confirm)
```

```
✅ SkillGuard: helpful-skill — Clean. Installing...
```

## Audit Table

```
SkillGuard Audit — scanning 12 skills

  Scanning clawhub... ✅ CLEAN
  Scanning coding-agent... ✅ CLEAN
  Scanning discord... ✅ CLEAN
  ...

────────────────────────────────────────────────────────────
SKILL                          RISK         SUMMARY
────────────────────────────────────────────────────────────
clawhub                        CLEAN        No security issues detected
coding-agent                   CLEAN        No security issues detected
```

## What Gets Scanned

| Category | What it detects |
|----------|----------------|
| Credential Theft | `~/.ssh/`, `~/.openclaw/`, API keys, `.env` |...