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 installation)

## LLM Options

```bash
skill-scan scan-hub slug --llm        # Always run deep analysis (layers 4-5)
skill-scan scan-hub slug --llm-auto   # LLM only if pattern scan finds MEDIUM+
skill-scan scan-hub slug --llm-only   # Skip patterns, LLM analysis only
```

Provider auto-detected from environment:
- `OPENAI_API_KEY` -> gpt-4o-mini
- `ANTHROPIC_API_KEY` -> claude-sonnet-4-5

## For the Agent

When the user asks to install a skill from ClawHub, follow this workflow:

1. **Scan first** — run `skill-scan scan-hub <slug>` BEFORE installing
2. **Check the result**:
   - If **LOW risk** (exit code 0): proceed with installation
   - If **MEDIUM risk**: show findings to the user and ask whether to proceed
   - If **HIGH or CRITICAL risk**: block installation and show the report
3. **Report** — always show the user the scan summary (score, risk level, finding count)

### Alert Format

When a scan finds MEDIUM or higher risk:

```
🛡️ Skill-Scan Alert: {RISK_LEVEL} ({SCORE}/100)
Skill: {slug}
Findings: {count} issue(s) detected
Top threat: {highest severity finding title}
Action: Installation blocked pending review.
```

## AGENTS.md Integration

To integrate skill-scan into your agent's workflow, add ONE of the following templates to your `AGENTS.md` (or equivalent agent instructions file).

### Option A: Automatic Scanning (Recommended)

All ClawHub skill installs are automatically scanned before installation. No manual step needed.

```markdown
## Skill-Scan — Automatic Pre-Install Security Scanning

BEFORE installing any skill from ClawHub, you MUST scan it with skill-scan first. This is non-negotiable — never skip the scan.

### Workflow

1. When the user asks to install a skill (e.g. `clawhub install <slug>`), run the scan FIRST:
   ```bash
   skill-scan scan-hub <slug>
   ```
2. **Check the exit code and output**:
   - **Exit code 0 (LOW risk)** — proceed with `clawhub install <slug>`
   - **Exit code 1 (MEDIUM risk)** — show findings to the user, ask whether to proceed
   - **Exit code 1 (HIGH/CRITICAL risk)** — BLOCK installation, show the full report
3. **Never install a HIGH or CRITICAL risk skill** without explicit user override
4. **Always show the scan summary** to the user before proceeding with installation

### Periodic Audits

When asked to audit installed skills, batch scan the skills directory:
```bash
skill-scan batch {skillsDir}
```

### LLM Deep Analysis

For high-stakes installs or when pattern scan returns MEDIUM, escalate to LLM analysis:
```bash
skill-scan scan-hub <slug> --llm-auto
```
```

### Option B: Manual On-Demand Scanning

Skills are only scanned when the user explicitly asks. Installation proceeds without automatic checks.

```markdown
## Skill-Scan — On-Demand Skill Security Scanning

skill-scan is available to audit skill packages for security threats. Use it when the user requests a security scan.

### Commands

- **Scan a ClawHub skill**: `skill-scan scan-hub <slug>`
- **Scan a local skill**: `skill-scan scan /path/to/skill`
- **Batch scan installed skills**: `skill-scan batch {skillsDir}`
- **Deep analysis with LLM**: add `--llm` or `--llm-auto` to any scan command

### Risk Levels

- **LOW (80-100)** — safe, no significant threats
- **MEDIUM (50-79)** — review findings, use caution
- **HIGH (20-49)** — serious threats, do not install
- **CRITICAL (0-19)** — multiple critical threats, do not install

### When the User Asks to Scan

1. Run the appropriate scan command
2. Show the scan summary (score, risk level, finding count)
3. If MEDIUM+, list the top findings with severity and description
4. Let the user decide what to do
```

## Install-Time Setup

When this skill is first installed, ask the user:

> **How should skill-scan integrate with your workflow?**
>
> 1. **Automatic** (Recommended) — Every `clawhub install` is scanned first. HIGH/CRITICAL installs are blocked automatically.
> 2. **Manual** — Scanning only happens when you explicitly ask for it.

Based on their choice, add the corresponding template (Option A or Option B above) to the project's `AGENTS.md`.

## Detection Categories

**Execution threats** — `eval()`, `exec()`, `child_process`, dynamic imports

**Credential theft** — `.env` access, API keys, tokens, private keys, wallet files

**Data exfiltration** — `fetch()`, `axios`, `requests`, sockets, webhooks

**Filesystem manipulation** — Write/delete/rename operations

**Obfuscation** — Base64, hex, unicode encoding, string construction

**Prompt injection** — Jailbreaks, invisible characters, homoglyphs, roleplay framing, encoded instructions

**Behavioral signatures** — Compound patterns: data exfiltration, trojan skills, evasive malware, persistent backdoors

## Requirements

- Python 3.10+
- `httpx>=0.27` (for LLM API calls only)
- API key only needed for `--llm` modes (static analysis is self-contained)

## Related Skills

- **input-guard** — External input scanning
- **memory-scan** — Agent memory security
- **guardrails** — Security policy configuration