Skill Defender — Malicious Pattern Scanner

When to Run

Automatic Triggers

1. 1. New skill installed — Immediately run scan_skill.py against it before allowing use
2. Skill updated — Re-scan after any file changes in a skill directory
3. Periodic audit — Run batch scan on all installed skills when requested

Manual Triggers

• - User says "scan skill X" → scan that specific skill
• User says "scan all skills" → batch scan all skills
• User says "security check" or "audit skills" → same as above

Scripts

scripts/scan_skill.py — Single Skill Scanner

scripts/aggregate_scan.py — Batch Scanner

How to Run

CODEBLOCK0

Exit Codes (scan_skill.py)

• - 0 = clean or informational only
• INLINECODE4 = suspicious (medium/high findings)
• INLINECODE5 = dangerous (critical findings)
• INLINECODE6 = error

Output Format (aggregate_scan.py)

CODEBLOCK1

Auto-Detection

Both scripts auto-detect paths:

• - Skills directory: Detected from script location (walks up to find skills/ parent), falls back to ~/clawd/skills, ~/skills, INLINECODE10
• Scanner script: aggregate_scan.py finds scan_skill.py co-located in the same directory

Handling Results

✅ Clean (verdict: "clean")

• - No action needed — skill is safe

⚠️ Suspicious (verdict: "suspicious")

• - Warn the user with a summary of findings
• Show the category and severity of each finding

🚨 Dangerous (verdict: "dangerous")

• - Block the skill — do not proceed with installation or use
• Show the full detailed findings to the user
• Require explicit user override to proceed

Built-in Allowlist

The aggregate scanner includes an allowlist for known false positives:

• - Security scanners (skill-defender, clawdbot-security-check) — their docs/scripts contain the very patterns they detect
• Auth-dependent skills (tailscale, reddit, n8n, event-planner) — legitimately reference credential paths and API keys
• Config-aware skills (memory-setup, eightctl, summarize) — reference config paths in documentation
• Agent-writing skills (self-improving-agent) — designed to modify agent files

Pattern Reference

See references/threat-patterns.md for full documentation of all detected patterns, organized by category with explanations of why each is dangerous.

Important Notes

• - No external dependencies — standard library only (Python 3.9+)
• Fast — under 1 second per skill, ~30 seconds for a full batch of 30+ skills
• This is deterministic pattern matching (Layer 2 defense). Not LLM-based.
• False positives are possible — the allowlist and --exclude flag help
• The scanner will flag itself if scanned without the allowlist — this is expected