name: skill-security-analyzer-v2
description: Comprehensive security analysis for Claude Code skills with P0-P3 enhancements. Detects malicious code, obfuscation, YAML injection, typosquatting, time bombs, sandbox escapes, and 40+ attack patterns. Use for analyzing skills before installation or auditing existing skills.
version: 2.0

Skill Security Analyzer v2.0

Overview

Enhanced security scanner for Claude Code skills implementing all P0-P3 recommendations. Detects 40+ malicious patterns including indirect execution, advanced encoding, shell injection, time bombs, typosquatting, environment manipulation, and sandbox escapes.

Version 2.0 Improvements:
- ✅ P0: Indirect execution detection (getattr, import)
- ✅ P0: Expanded file type coverage (scans ALL text files)
- ✅ P0: Advanced encoding detection (ROT13, zlib, XOR, AST)
- ✅ P0: Enhanced subprocess detection (bash -c, python -c, perl -e)
- ✅ P0: Actual YAML parsing with SafeLoader
- ✅ P1: Data flow analysis across files
- ✅ P1: Typosquatting detection with Levenshtein distance
- ✅ P1: Time bomb pattern detection
- ✅ P1: Environment variable manipulation checks
- ✅ P2: Integrity verification via MANIFEST.json
- ✅ P2: Pluggable signature database
- ✅ P3: Basic anomaly detection
- ✅ P3: Dependency tree analysis

When to Use

Trigger this skill when:
- "Analyze this skill for security"
- "Check if [skill-name] is safe"
- "Audit security of installed skills"
- "Scan [file.zip] before installing"
- "Review skill vulnerabilities"

Quick Start

# Scan a single skill
python3 scripts/security_scanner.py /path/to/skill

# Scan with verbose output
python3 scripts/security_scanner.py /path/to/skill --verbose

# Scan all installed skills
python3 scripts/security_scanner.py ~/.claude/skills/ --recursive

# Output to JSON
python3 scripts/security_scanner.py /path/to/skill --output report.json

# Run test suite
python3 scripts/test_scanner.py

What It Detects

CRITICAL Threats

• Indirect Execution: getattr(os, 'system'), builtins access
• Command Injection: os.system(), eval(), exec()
• Shell Injection: subprocess with bash/python/perl -c
• YAML Injection: !!python/object/apply, code in frontmatter
• Credential Theft: Accessing .ssh/, .aws/, .git-credentials
• Sandbox Escape: Class traversal (class.bases)
• Typosquatting: request vs requests, urlib vs urllib

HIGH Severity

• Advanced Encoding: ROT13, zlib, XOR, AST manipulation
• Time Bombs: datetime conditionals near dangerous ops
• Environment Hijacking: LD_PRELOAD, PATH manipulation
• Import Hooks: sys.meta_path modifications
• Data Exfiltration: Network calls to unknown domains
• File Operations: Access outside skill directory

MEDIUM Severity

• Obfuscated Code: Base64, hex encoding
• Hardcoded Secrets: API keys, passwords in code
• Undocumented Network: HTTP requests not in SKILL.md
• Missing Validation: User input without sanitization

LOW Severity

• Missing Integrity: No MANIFEST.json checksums
• Documentation Gaps: Incomplete SKILL.md

Analysis Workflow

Phase 1: Structural Validation

• Verify SKILL.md exists
• Check integrity via MANIFEST.json
• Validate directory structure

Phase 2: YAML Frontmatter

• Parse with yaml.safe_load()
• Detect !!python directives
• Check for proto pollution

Phase 3: Comprehensive File Scanning

• Scan ALL text files (not just .py)
• Check scripts/, references/, assets/
• Scan SKILL.md content for embedded code

Phase 4: Import Analysis

• Extract all import statements
• Check for typosquatting (Levenshtein distance ≤2)
• Validate against known packages

Phase 5: Cross-File Analysis

• Track data flow between files
• Identify user input sources
• Map dangerous operation sinks

Phase 6: Anomaly Detection

• Calculate obfuscation ratio
• Flag unusual patterns
• Detect statistical outliers

Detection Examples

Indirect Execution:

# DETECTED: getattr obfuscation
func = getattr(os, 'sys' + 'tem')
func(malicious_command)

# DETECTED: __builtins__ access
exec_func = getattr(__builtins__, 'ex' + 'ec')

Advanced Encoding:

# DETECTED: ROT13
exec(codecs.decode('vzcbeg bf', 'rot_13'))

# DETECTED: zlib compression
exec(zlib.decompress(compressed_payload))

# DETECTED: AST manipulation
tree.body[0] = malicious_node

Shell Injection:

# DETECTED: bash -c without shell=True
subprocess.run(['/bin/bash', '-c', user_input])

# DETECTED: python -c execution
subprocess.run(['python3', '-c', malicious_code])

Time Bombs:

# DETECTED: Date conditional + dangerous op
if datetime.datetime.now().day == 15:
    os.system('malicious')

Typosquatting:

# DETECTED: Missing 's'
import request  # Should be 'requests'

# DETECTED: Missing 'l'
import urlib    # Should be 'urllib'

Report Format

{
  "skill": "example-skill",
  "scanner_version": "2.0",
  "timestamp": "2025-10-25T19:00:00Z",
  "summary": {
    "overall_risk": "CRITICAL",
    "total_findings": 15,
    "critical": 5,
    "high": 7,
    "medium": 3,
    "low": 0,
    "recommendation": "REJECT"
  },
  "findings": [
    {
      "severity": "CRITICAL",
      "category": "Obfuscated Execution",
      "title": "getattr accessing dangerous function",
      "location": "scripts/main.py:42",
      "evidence": "func = getattr(os, 'sys' + 'tem')",
      "impact": "Code execution via obfuscation"
    }
  ]
}

Recommendations

REJECT (Do Not Install)

• Any CRITICAL findings
• 3+ HIGH findings
• Evidence of:
• Command injection
• Credential theft
• Data exfiltration to unknown domains
• YAML injection

REVIEW (Manual Inspection Required)

• 1-2 HIGH findings
• 5+ MEDIUM findings
• Patterns requiring context:
• Documented network calls
• File operations within skill directory
• subprocess with static commands

APPROVE (Safe to Install)

• No CRITICAL/HIGH findings
• <5 MEDIUM findings
• All functionality documented
• Input validation present
• File operations scoped correctly

Testing

Run the test suite to verify scanner effectiveness:

python3 scripts/test_scanner.py

Tests 11 malicious samples covering:
1. Indirect execution (getattr)
2. File extension evasion
3. Advanced encoding
4. Shell injection
5. Time bombs
6. Typosquatting
7. Environment manipulation
8. Sandbox escapes
9. Data exfiltration
10. YAML injection
11. Import hooks

Expected: 100% detection rate on all samples.

Limitations

What This Scanner Cannot Do:
- Guarantee 100% detection (new attacks emerge constantly)
- Execute code to see runtime behavior (use --sandbox for limited testing)
- Analyze encrypted or heavily obfuscated payloads
- Detect zero-day attack patterns
- Reverse engineer compiled binaries

Best Practices:
- Use as first-pass filter, not sole security measure
- Manually review HIGH/CRITICAL findings
- When in doubt, reject installation
- Report malicious skills to marketplace
- Re-scan skills after updates

Advanced Usage

Custom Signatures

Add custom detection patterns in signatures/custom.json:

{
  "name": "Custom Patterns",
  "version": "1.0",
  "patterns": [
    {
      "pattern": "your_regex_here",
      "severity": "CRITICAL",
      "description": "Your detection description"
    }
  ]
}

Integrity Verification

Create MANIFEST.json for your skills:

{
  "version": "1.0",
  "checksums": {
    "scripts/main.py": "sha256_hash_here",
    "SKILL.md": "sha256_hash_here"
  }
}

Integration with CI/CD

#!/bin/bash
# Pre-commit hook to scan skills

for skill in skills/*; do
  python3 security_scanner.py "$skill" --output "$skill/scan_report.json"

  # Fail if CRITICAL findings
  if grep -q '"overall_risk": "CRITICAL"' "$skill/scan_report.json"; then
    echo "CRITICAL vulnerabilities in $skill"
    exit 1
  fi
done

Detection Rate

Based on test suite of 11 malicious samples:

Overall: 100% detection on known attack patterns

Version History

v2.0 (Current)
- Complete P0-P3 implementation
- 40+ detection patterns
- Test suite with 11 samples
- 100% detection rate

v1.0 (Original)
- Basic pattern matching
- 15 detection patterns
- ~60% detection rate

Support

For issues or suggestions:
- Review references/vulnerability_patterns.md
- Check references/safe_coding_practices.md
- Run test_scanner.py to verify installation

Remember: Static analysis is one layer of defense. Always practice defense-in-depth with runtime monitoring, sandboxing, and least-privilege execution.