🔍 Skill Scanner

Security scanner for AI agent skills — detect threats before you install.

---

Why This Exists

AI agent skills (SKILL.md files and their associated scripts) are powerful extensions that give agents new capabilities. But recent research has shown serious security risks in skill marketplaces:

• Snyk found that 13.4% of skills on ClawHub contain critical security issues (source)
• Cisco found that 26% of 31,000 analyzed agent skills contain vulnerabilities (source)
• VirusTotal found hundreds of malicious skills delivering infostealer malware (source)
• NIST issued an RFI on securing AI agent systems (source)

Skill Scanner is a free, open-source tool that scans skills before you install them.

---

Quick Start

# Scan a skill directory
python3 scripts/scan_skill.py /path/to/skill-directory

# Scan a single SKILL.md
python3 scripts/scan_skill.py /path/to/SKILL.md

# Scan from a URL
python3 scripts/scan_skill.py --url https://raw.githubusercontent.com/user/repo/main/skills/my-skill/SKILL.md

# Scan all skills recursively
python3 scripts/scan_skill.py /path/to/skills/ --recursive

# Output as JSON
python3 scripts/scan_skill.py /path/to/skill --format json --output report.json

# Fail if HIGH or above findings (for CI/CD)
python3 scripts/scan_skill.py /path/to/skill --fail-on high

No dependencies required. Runs on Python 3.8+ with only the standard library.

---

What It Detects

Category	What It Finds
🎯 Prompt Injection	Instruction overrides, safety bypasses, role manipulation, hidden Unicode text
🔑 Credential Exposure	Hardcoded API keys, credentials in LLM context, environment variable harvesting
📡 Data Exfiltration	Silent outbound requests, webhooks, base64-obfuscated URLs, C2 patterns
💀 Malicious Execution	curl|sh, eval/exec, obfuscated scripts, persistence mechanisms, binary downloads
🔗 Supply Chain	Remote markdown fetching, unverified dependencies, missing metadata, path traversal

---

Severity Levels

Level	Icon	Meaning
CRITICAL	🔴	Active malware, confirmed exfiltration, remote code execution
HIGH	🟠	Credential exposure, suspicious shell commands, silent network calls
MEDIUM	🟡	Remote content fetching, broad permissions, unverified dependencies
LOW	🔵	Minor hygiene issues, missing metadata
INFO	ℹ️	Observations, not vulnerabilities

---

CI/CD Integration

GitHub Actions

name: Scan Skills
on: [push, pull_request]

jobs:
  skill-security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Scan all skills
        run: |
          python3 skill-scanner/scripts/scan_skill.py ./skills/ \
            --recursive \
            --format json \
            --output scan-results.json \
            --fail-on high
      - name: Upload scan results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: skill-scan-results
          path: scan-results.json

---

Project Structure

skill-scanner/
├── SKILL.md                          # Skill definition (for use as a Claude skill)
├── README.md                         # This file
├── LICENSE                           # MIT License
├── scripts/
│   ├── scan_skill.py                 # Main scanner script
│   └── rules.py                      # Detection rules engine
└── references/
    └── detection-rules.md            # Full rule catalog and documentation

---

Adding Custom Rules

Edit scripts/rules.py and add a new rule to build_rules():

rules.append(Rule(
    id="CUSTOM-001",
    severity=Severity.HIGH,
    category=Category.MALICIOUS_EXECUTION,
    title="My custom detection",
    description="What this detects and why.",
    patterns=[
        re.compile(r'your-regex-pattern', re.I),
    ],
    recommendation="What to do about it."
))

---

Limitations

This is a static analysis tool — a first line of defense, not a silver bullet:

• Pattern matching can be evaded by sophisticated obfuscation
• Cannot evaluate runtime behavior
• Natural language prompt injection may require LLM-based semantic analysis
• Does not replace manual code review for high-value deployments

For maximum security, combine with manual review, sandboxed execution, and network monitoring.

---

Contributing

PRs welcome! Areas that need help:

• New detection rules for emerging attack patterns
• LLM-based semantic analysis for natural language prompt injection
• Integration with VirusTotal or other scanning APIs
• Test suite with known-malicious and known-safe skill samples

---

License

MIT — use it, fork it, improve it.

---

Credits

Built with insights from the security research community:

• Snyk — ToxicSkills research and MCP-Scan
• Cisco — AI Defense Skill Scanner
• VirusTotal — Code Insight malware analysis
• 1Password — Supply chain attack documentation
• Alice — AI Skills Security Scanner

---

Scan before you install. Every time.