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-miniANTHROPIC_API_KEY
-> claude-sonnet-4-5
For the Agent
When the user asks to install a skill from ClawHub, follow this workflow:
- Scan first — run
skill-scan scan-hub <slug>
BEFORE installing
- 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
- 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
- When the user asks to install a skill (e.g.
clawhub install <slug>
), run the scan FIRST:
skill-scan scan-hub <slug>
- 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
- Never install a HIGH or CRITICAL risk skill without explicit user override
- 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.
## 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
</code></pre>
<h2>Install-Time Setup</h2>
<p>When this skill is first installed, ask the user:</p>
<blockquote>
<p><strong>How should skill-scan integrate with your workflow?</strong></p>
<ol>
<li><strong>Automatic</strong> (Recommended) — Every <code>clawhub install</code> is scanned first. HIGH/CRITICAL installs are blocked automatically.</li>
<li><strong>Manual</strong> — Scanning only happens when you explicitly ask for it.</li>
</ol>
</blockquote>
<p>Based on their choice, add the corresponding template (Option A or Option B above) to the project's <code>AGENTS.md</code>.</p>
<h2>Detection Categories</h2>
<p><strong>Execution threats</strong> — <code>eval()</code>, <code>exec()</code>, <code>child_process</code>, dynamic imports</p>
<p><strong>Credential theft</strong> — <code>.env</code> access, API keys, tokens, private keys, wallet files</p>
<p><strong>Data exfiltration</strong> — <code>fetch()</code>, <code>axios</code>, <code>requests</code>, sockets, webhooks</p>
<p><strong>Filesystem manipulation</strong> — Write/delete/rename operations</p>
<p><strong>Obfuscation</strong> — Base64, hex, unicode encoding, string construction</p>
<p><strong>Prompt injection</strong> — Jailbreaks, invisible characters, homoglyphs, roleplay framing, encoded instructions</p>
<p><strong>Behavioral signatures</strong> — Compound patterns: data exfiltration, trojan skills, evasive malware, persistent backdoors</p>
<h2>Requirements</h2>
<ul>
<li>Python 3.10+</li>
<li><code>httpx>=0.27</code> (for LLM API calls only)</li>
<li>API key only needed for <code>--llm</code> modes (static analysis is self-contained)</li>
</ul>
<h2>Related Skills</h2>
<ul>
<li><strong>input-guard</strong> — External input scanning</li>
<li><strong>memory-scan</strong> — Agent memory security</li>
<li><strong>guardrails</strong> — Security policy configuration</li>
</ul>
