skill-scan – OpenClaw Skill

---

name: skill-scan description: Security scanner for OpenClaw skill packages. Scans skills for malicious code, evasion techniques, prompt injection, and misaligned behavior BEFORE installation. Use to audit any skill from ClawHub or local directories.

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

# 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

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.

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

skill-scan batch {skillsDir}

LLM Deep Analysis

For high-stakes installs or when pattern scan returns MEDIUM, escalate to LLM analysis:

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

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:

# 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

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

Alerting (OpenClaw)

Send alert on MEDIUM+ risk using configured OpenClaw channel:

OPENCLAW_ALERT_CHANNEL=slack skill-scan scan /path/to/skill --alert

Optional target for channels that require a recipient:

OPENCLAW_ALERT_CHANNEL=slack OPENCLAW_ALERT_TO=@security skill-scan scan /path/to/skill --alert

Alert only on HIGH/CRITICAL:

OPENCLAW_ALERT_CHANNEL=slack skill-scan scan /path/to/skill --alert --alert-threshold HIGH

Scan from ClawHub

skill-scan scan-hub some-skill-slug

Check Arbitrary Text

skill-scan check "some suspicious text"

Batch Scan

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, no significant threats
• MEDIUM (50-79) - Moderate risk, review needed
• HIGH (20-49) - Serious threats detected
• CRITICAL (0-19) - Multiple critical threats, do not use

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

Output Formats

skill-scan scan path/            # Formatted text report (default)
skill-scan scan path/ --json     # Raw JSON
skill-scan scan path/ --compact  # Single-line summary
skill-scan scan path/ --quiet    # Score + verdict only

LLM Options

skill-scan scan path/ --llm        # Always run layers 4-5
skill-scan scan path/ --llm-only   # Skip pattern analysis, LLM only
skill-scan scan path/ --llm-auto   # LLM only if pattern analysis finds MEDIUM+

Provider auto-detected from environment:

• OPENAI_API_KEY -> gpt-4o-mini
• ANTHROPIC_API_KEY -> claude-sonnet-4-5

Environment Variables

Create a .env file in the repository root with any needed keys:

Variable	Required For	Description
OPENAI_API_KEY	LLM scanning	OpenAI API key (uses gpt-4o-mini)
ANTHROPIC_API_KEY	LLM scanning	Anthropic API key (alternative to OpenAI)
PROMPTINTEL_API_KEY	MoltThreats integration	PromptIntel API key
OPENCLAW_ALERT_CHANNEL	Alerts	OpenClaw channel name for alerts
OPENCLAW_ALERT_TO	Alerts	Optional recipient/target for channels that require one

Static analysis requires no keys — it works out of the box.

Files

skill-scan/
├── pyproject.toml                  # Package metadata (v0.3.0)
├── TESTING.md                      # Eval approach and results
├── rules/
│   └── dangerous-patterns.json     # 60+ regex detection rules
├── skill_scan/
│   ├── cli.py                      # CLI entry point
│   ├── scanner.py                  # Core scanning engine
│   ├── models.py                   # Data classes for findings
│   ├── reporter.py                 # Report formatting
│   ├── ast_analyzer.py             # Layer 2: JS/TS evasion detection
│   ├── prompt_analyzer.py          # Layer 3: Prompt injection detection
│   ├── llm_analyzer.py             # Layer 4: LLM deep analysis
│   ├── alignment_analyzer.py       # Layer 5a: Code vs description matching
│   ├── meta_analyzer.py            # Layer 5b: Meta-analysis
│   └── clawhub.py                  # ClawHub registry integration
├── tests/                          # Unit tests
├── evals/                          # Evaluation framework
└── test-fixtures/                  # 26 test cases (safe + malicious)

Requirements

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

Testing

python3 -m pytest tests/ -v
python3 evals/eval_runner.py
python3 evals/eval_runner.py --llm       # With LLM layers

Static analysis results: 100% precision, 86% recall across 26 fixtures.

Exit Codes

• 0 - LOW risk
• 1 - MEDIUM risk
• 2 - HIGH risk
• 3 - CRITICAL risk

Uninstalling

1. Remove the AGENTS.md section

During installation, one of two sections was added to your workspace AGENTS.md:

• ## Skill-Scan — Automatic Pre-Install Security Scanning (Option A), or
• ## Skill-Scan — On-Demand Skill Security Scanning (Option B)

Delete whichever section was added.

2. Uninstall the Python package

pip uninstall skill-scan

3. Remove the skill directory

rm -rf skills/skill-scan

4. Clean up environment variables

Remove from your .env (if no other skill uses them):

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• PROMPTINTEL_API_KEY
• OPENCLAW_ALERT_CHANNEL
• OPENCLAW_ALERT_TO

skill-scan does not create any files in the workspace outside its own directory.

Related Skills

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