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

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:

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