Skill Security Scanner

Protect your OpenClaw installation from malicious skills. This scanner performs static analysis on skill code to detect:

• Code Execution Threats: eval, exec, os.system, subprocess calls
• Data Exfiltration: Hidden network requests, suspicious URLs, IP connections
• System Compromise: File deletion, permission changes, privilege escalation
• Credential Theft: Environment variable access, secret harvesting
• Cryptojacking: Mining malware, suspicious compute patterns
• Obfuscation: Hidden code, base64 encoding, minification
• Spyware: Keyloggers, screen capture, surveillance features

Quick Start

# Basic scan
python scripts/security_scanner.py /path/to/skill

# Strict mode (catches more suspicious patterns)
python scripts/security_scanner.py /path/to/skill --strict

# Save JSON report
python scripts/security_scanner.py /path/to/skill --format json -o report.json

# Generate markdown report
python scripts/security_scanner.py /path/to/skill --format markdown -o report.md

Understanding Results

Verdict Levels

Verdict	Emoji	Meaning	Action
PASS	🟢	No critical issues found	Safe to install
REVIEW	🟡	Some concerns, review recommended	Check findings before installing
WARNING	🟠	High-risk patterns detected	Strongly reconsider installation
REJECT	🔴	Critical threats identified	DO NOT INSTALL

Security Score

• 90-100: Excellent - minimal risk
• 70-89: Good - minor issues
• 50-69: Fair - requires review
• 0-49: Poor - significant risks

Detection Rules

Critical (🔴)

Rule	Description	Example
EXEC001	Code execution functions	eval(), exec(), compile()
SUSPICIOUS001	Keylogger functionality	pynput, keyboard modules
SUSPICIOUS003	Cryptocurrency mining	mining, bitcoin, stratum+tcp

High (🟠)

Rule	Description	Example
EXEC002	System command execution	os.system(), subprocess.call()
NET002	Raw socket connections	socket.connect()
ENV001	Sensitive credential access	os.environ['PASSWORD']
OBF001	Code obfuscation	Base64, hex-encoded code
SUSPICIOUS002	Screen capture	pyautogui.screenshot()
NET004	Short URL usage	bit.ly, tinyurl links

Medium (🟡)

Rule	Description	Example
NET001	HTTP network requests	requests.get(), fetch()
ENV002	Environment enumeration	os.environ.items()
FILE001	File deletion	os.remove(), shutil.rmtree()
DATA001	Unsafe deserialization	pickle.loads(), yaml.load()
NET003	Hardcoded IP addresses	Direct IP in URLs
OBF002	Base64 encoded blocks	Large base64 strings

Low/Info (🔵/⚪)

Rule	Description
FILE002	File write operations
CRYPTO001	Cryptographic operations
DOC001	Insufficient documentation
DOC002	Missing security statements

Workflow

Before Installing a New Skill

1. Download the skill to a temporary directory

2. Run the security scanner

3. Review the verdict:

   • 🟢 PASS: Proceed with installation
   • 🟡 REVIEW: Examine findings, verify legitimate use
   • 🟠 WARNING: Only install from trusted sources
   • 🔴 REJECT: Do not install

4. For 🟡/🟠 findings, manually review the flagged code

5. Confirm the skill's behavior matches its documentation

Before Updating an Existing Skill

1. Run scanner on the new version
2. Compare results with previous version's scan
3. Check for new critical/high findings
4. Review any new network/file operations

Automated Integration

Add to your skill installation workflow:

import subprocess
import sys

def safe_install_skill(skill_path):
    # Run security scan
    result = subprocess.run(
        ['python', 'scripts/security_scanner.py', skill_path, '--format', 'json'],
        capture_output=True,
        text=True
    )
    
    import json
    report = json.loads(result.stdout)
    
    if report['summary']['verdict'] == 'REJECT':
        print("❌ Installation blocked: Critical security issues found")
        return False
    
    if report['summary']['verdict'] == 'WARNING':
        response = input("⚠️ High-risk patterns detected. Install anyway? (y/N): ")
        if response.lower() != 'y':
            return False
    
    # Proceed with installation
    return True

Handling False Positives

Some legitimate skills may trigger warnings:

• Network requests: Skills that fetch data from APIs
• File operations: Skills that modify documents
• Encryption: Skills handling sensitive data

When you trust the source and understand the functionality, you can:

1. Review the specific code flagged
2. Verify it matches the documented purpose
3. Manually approve if confident

Reporting Issues

If you find a skill with confirmed malicious intent:

1. Do not install or run it
2. Report to the skill repository/hosting platform
3. Notify OpenClaw community channels
4. Share scan report (without executing the skill)

Best Practices

1. Only install skills from trusted sources
2. Always scan before installing - even from trusted sources
3. Review findings carefully - understand what the skill does
4. Keep scanner updated - new detection rules added regularly
5. Use strict mode for untrusted sources - catches more suspicious patterns
6. Check skill updates - re-scan when updating existing skills

Exit Codes

The scanner returns specific exit codes:

Code	Meaning
0	PASS or REVIEW - installation may proceed
1	WARNING - high-risk patterns found
2	REJECT - critical threats detected

Use in scripts:

python scripts/security_scanner.py ./skill || {
    echo "Security check failed"
    exit 1
}