safeclaw: Agent for Claude Code

Skill Scanner — Static Security Analysis for AI Skill Definitions

Overview

The Skill Scanner provides proactive, pre-execution security analysis of markdown skill definitions. While SafeClaw's runtime Threat Analysis Engine (TC-* categories) classifies activities as they happen, the Skill Scanner inspects skill files *before* they're loaded — catching hidden threats that are invisible to human reviewers but fully processed by LLMs.

This is a stateless, local-only analysis tool. No database, no Socket.IO, no persistence. User pastes or uploads markdown → backend runs 15 analyzers → structured findings returned instantly.

Threat Landscape

The scanner is designed to detect attack vectors documented in recent research:

• Hidden-comment injection ("When Skills Lie", arXiv:2602.10498) — HTML comments containing instructions are invisible in rendered markdown but fully processed by LLMs, causing malicious tool calls
• Supply chain poisoning (Snyk ToxicSkills, ClawHavoc) — Malicious skills on public registries delivering credential theft, reverse shells, and memory poisoning via base64-encoded commands
• Cross-tool chaining (Invariant Labs) — Multi-step attack patterns where individually benign instructions combine to exfiltrate data
• Invisible Unicode (Promptfoo) — Zero-width characters that encode instructions invisible to human review
• Argument injection (Trail of Bits) — GTFOBINS-style flag exploitation via tool arguments

Architecture

SkillScannerPage.tsx
    │
    │  POST /api/skill-scanner/scan  { content: string }
    │
    ▼
routes.ts
    │  Zod validation (skillScanRequestSchema: min 1, max 500K chars)
    │
    ▼
scanSkillDefinition(content)           apps/cli/src/lib/skill-scanner.ts
    │
    ├── scanHiddenContent()            SK-HID  — HTML comments, zero-width Unicode, CSS hiding, bidi overrides
    ├── scanPromptInjection()          SK-INJ  — Override directives, role reassignment, model tokens
    ├── scanShellExecution()           SK-EXE  — curl|bash, eval, exec, reverse shells, language one-liners
    ├── scanDataExfiltration()         SK-EXF  — Paste sites, webhooks, raw IP URLs (reuses EXFILTRATION_URLS)
    ├── scanEmbeddedSecrets()          SK-SEC  — 17 credential types (reuses scanForSecrets())
    ├── scanSensitiveFileRefs()        SK-SFA  — .ssh/, .env, .aws/, /etc/passwd (reuses SENSITIVE_PATH_RULES)
    ├── scanMemoryPoisoning()          SK-MEM  — SOUL.md, MEMORY.md, CLAUDE.md, .cursorrules modifications
    ├── scanSupplyChainRisk()          SK-SUP  — External scripts, npm/pip/gem install, raw GitHub URLs
    ├── scanEncodedPayloads()          SK-B64  — Base64 >40 chars, atob/btoa, hex sequences, piped decode
    ├── scanImageExfiltration()        SK-IMG  — Exfil query params, raw IP images, variable interpolation
    ├── scanSystemPromptExtraction()   SK-SYS  — "reveal system prompt", "repeat words above"
    ├── scanArgumentInjection()        SK-ARG  — $(), ${}, backticks, shell metachar chains, GTFOBINS flags
    ├── scanCrossToolChaining()        SK-XTL  — Read-then-exfiltrate, multi-step invocations, tool references
    ├── scanExcessivePermissions()     SK-PRM  — "unrestricted access", "bypass security", "no restrictions"
    └── scanSuspiciousStructure()      SK-STR  — Content >10K chars, imperative instruction density >30%
    │
    ▼
SkillScanResult
    ├── overallSeverity: ThreatLevel   (max across all findings)
    ├── findings: SkillScanFinding[]   (sorted CRITICAL → LOW)
    ├── summary: { critical, high, medium, low }
    ├── scannedAt, contentLength, scanDurationMs