skill-defender

# Skill Defender — Malicious Pattern Scanner ## When to Run ### Automatic Triggers 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 Scans one skill directory for malicious patterns. Produces JSON or human-readable output. ### `scripts/aggregate_scan.py` — Batch Scanner Scans ALL installed skills and produces a single JSON report. Includes a built-in allowlist to reduce false positives from security-related skills, API skills, and other known-safe patterns. ## How to Run ```bash # Scan a single skill (human-readable) python3 scripts/scan_skill.py /path/to/skill-dir # Scan a single skill (JSON output) python3 scripts/scan_skill.py /path/to/skill-dir --json # Scan ALL installed skills (JSON aggregate report) python3 scripts/aggregate_scan.py # With custom skills directory python3 scripts/aggregate_scan.py --skills-dir /path/to/skills # With verbose warnings python3 scripts/scan_skill.py /path/to/skill-dir --verbose # Exclude false positives python3 scripts/scan_skill.py /path/to/skill-dir --exclude "pattern1" "pattern2" ``` ### Exit Codes (scan_skill.py) - `0` = clean or informational only - `1` = suspicious (medium/high findings) - `2` = dangerous (critical findings) - `3` = error ### Output Format (aggregate_scan.py) ```json { "skills": [ { "name": "skill-name", "verdict": "clean|suspicious|dangerous|error", "findingsCount": 0, "findings": [] } ], "summary": "All 37 skills passed with no significant issues.", "totalSkills": 37, "cleanCount": 37, "suspiciousCount": 0, "dangerousCount": 0, "errorCount": 0, "timestamp": "2026-02-02T06:00:00+00:00" } ``` ## 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`, `~/.openclaw/skills` - **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