skill-scan

# Skill-Scan — Security Auditor for Agent Skills

Multi-layered security scanner for OpenClaw skill packages. Detects malicious code, evasion techniques, prompt injection, and misaligned behavior through static analysis and optional LLM-powered deep inspection. Run this BEFORE installing or enabling any untrusted skill.

## Features

- **6 analysis layers** — pattern matching, AST/evasion, prompt injection, LLM deep analysis, alignment verification, meta-analysis
- **60+ detection rules** — execution threats, credential theft, data exfiltration, obfuscation, behavioral signatures
- **Context-aware scoring** — reduces false positives for legitimate API skills
- **ClawHub integration** — scan skills directly from the registry by slug
- **Multiple output modes** — text report (default), `--json`, `--compact`, `--quiet`
- **Exit codes** — 0 for safe, 1 for risky (easy scripting integration)

## When to Use

**MANDATORY** before installing or enabling:
- Skills from ClawHub (any skill not authored by you)
- Skills shared by other users or teams
- Skills from public repositories
- Any skill package you haven't personally reviewed

**RECOMMENDED** for periodic audits of already-installed skills.

## Quick Start

```bash
# Scan a local skill directory
skill-scan scan /path/to/skill

# Scan a skill from ClawHub before installing it
skill-scan scan-hub some-skill-slug

# Batch scan all installed skills
skill-scan batch /path/to/skills-directory

# JSON output for programmatic use
skill-scan scan-hub some-skill-slug --json

# Quiet mode (just score + verdict)
skill-scan scan-hub some-skill-slug --quiet
```

## Risk Scoring

| Risk | Score | Action |
|------|-------|--------|
| LOW | 80-100 | Safe to install |
| MEDIUM | 50-79 | Review findings before installing |
| HIGH | 20-49 | Do NOT install — serious threats detected |
| CRITICAL | 0-19 | Do NOT install — multiple critical threats |

## Exit Codes

- `0` — LOW risk (safe to proceed)
- `1` — MEDIUM or higher (block installa...

# Skill-Scan - OpenClaw Skill Security Auditor

Multi-layered security scanner for OpenClaw agent skill packages. Detects malicious code, evasion techniques, prompt injection, and misaligned behavior through static analysis and optional LLM-powered deep inspection.

## Prerequisites

- **Python 3.10+** — check with `python3 --version`
- **pip** — check with `pip3 --version` or `python3 -m pip --version`

If pip is not installed:
```bash
# Option 1: System package manager (requires sudo)
sudo apt-get install python3-pip        # Debian/Ubuntu
brew install python3                     # macOS (includes pip)

# Option 2: Bootstrap pip without sudo
python3 -m ensurepip --upgrade
```

## Quick Start

```bash
pip install -e .
skill-scan scan /path/to/skill
```

### Alerting (OpenClaw)

Send alert on MEDIUM+ risk using configured OpenClaw channel:
```bash
OPENCLAW_ALERT_CHANNEL=slack skill-scan scan /path/to/skill --alert
```

Optional target for channels that require a recipient:
```bash
OPENCLAW_ALERT_CHANNEL=slack OPENCLAW_ALERT_TO=@security skill-scan scan /path/to/skill --alert
```

Alert only on HIGH/CRITICAL:
```bash
OPENCLAW_ALERT_CHANNEL=slack skill-scan scan /path/to/skill --alert --alert-threshold HIGH
```

### Scan from ClawHub

```bash
skill-scan scan-hub some-skill-slug
```

### Check Arbitrary Text

```bash
skill-scan check "some suspicious text"
```

### Batch Scan

```bash
skill-scan batch /path/to/skills-directory
```

## Analysis Layers

| Layer | Module | Purpose | When |
|-------|--------|---------|------|
| 1 | Pattern matching | Fast regex-based detection | Always |
| 2 | AST/evasion analysis | Catches obfuscation tricks | Always |
| 3 | Prompt injection | Detects social engineering in SKILL.md | Always |
| 4 | LLM deep analysis | Semantic threat understanding | `--llm` |
| 5a | Alignment verification | Code vs description matching | `--llm` |
| 5b | Meta-analysis | Finding review and correlation | `--llm` |

## Risk Scoring

- **LOW (80-100)** - Safe...