## What It Checks

### Dangerous Imports
Detects imports that could be used maliciously:
- `os` - System-level operations
- `subprocess` - Command execution
- `shutil` - File operations
- `socket` - Network operations
- `urllib` / `requests` - HTTP requests

**Why dangerous?** These imports enable system command execution, file manipulation, and network access that could be exploited.

### Dangerous Functions
Detects potentially unsafe function calls:
- `os.system()` - Executes shell commands
- `subprocess.call()`, `subprocess.run()`, `subprocess.Popen()` - Command execution
- `eval()` - Executes arbitrary code
- `exec()` - Executes arbitrary code

**Why dangerous?** These can execute arbitrary commands or code, leading to remote code execution vulnerabilities.

### Hardcoded Secrets
Detects tokens, keys, and passwords:
- API keys
- Auth tokens (including ClawHub tokens)
- Passwords
- Private keys
- JWT-like tokens

**Why dangerous?** Secrets leaked in published code can be stolen and abused.

### Unsafe File Operations
Detects risky file access patterns:
- Absolute file paths outside expected directories
- Parent directory traversal (`..`)
- Writing to system directories

**Why dangerous?** Could lead to unintended file access, data loss, or system modification.

## Usage Pattern: Pre-Publish Checklist

Before publishing any skill:

## Interpretation of Results

### ✅ "No security issues found"
Code appears safe. Proceed with publishing.

### ⚠️  "Warning" (Yellow)
Potentially risky pattern detected. Review the specific line and decide:
- **Is it legitimate?** Document why in code comments or SKILL.md
- **Can it be avoided?** Refactor to safer alternatives
- **Is it necessary?** Clearly document the risk and purpose

### 🔴 "Possible hardcoded secret"
Secret detected. Before publishing:
- Remove the secret
- Use environment variables instead: `os.getenv('API_KEY')`
- Document required env variables in SKILL.md
- Never commit real secrets

## Examples

### Legitimate os module usage (documented)

**Scan result:** ⚠️ Warning about os import
**Action:** Document safe usage pattern in code comments

### Hardcoded secret (must fix)

**Scan result:** 🔴 Possible hardcoded secret
**Action:** Remove and use environment variable:

**Scan result:** ✅ No issues

## Best Practices

1. **Always scan before publishing** - Make it part of your workflow
2. **Review warnings manually** - The scanner can't judge context
3. **Use environment variables for secrets** - Never hardcode
4. **Prefer json over eval** - Safe parsing vs code execution
5. **Document necessary risks** - If dangerous code is required, explain why
6. **Minimize dangerous imports** - Only use what's truly necessary
7. **Keep code simple** - Complex code is harder to audit

## Integration with Development Workflow

### Before committing to repo

## Limitations

This scanner:
- **Can't judge context** - Some dangerous code may be legitimate
- **Static analysis only** - Doesn't execute code
- **Python-focused** - Other languages need different tools
- **Basic patterns** - Sophisticated obfuscation may evade detection

**Complement with:**
- Manual code review
- Testing in isolated environment
- Reading through all code before publishing
- Using additional tools: `bandit`, `safety`

## Trust Building

Publishing skills that pass security scans builds trust in the community:
- Users know you care about safety
- Your reputation improves
- Skills get adopted more readily
- ClawHub may highlight safe skills

## Examples of Published Skills (All Scanned)

# Scan a single Python file
security_scan.py scripts/my_script.py

# Scan an entire skill directory
security_scan.py /path/to/skill-folder

# Scan multiple skills
security_scan.py skills/

# 1. Run security scan
security_scan.py /path/to/skill

# 2. Review any warnings
# If warnings appear, fix the code or document why it's safe

# 3. Re-scan after fixes
security_scan.py /path/to/skill

# 4. Only publish if scan passes
clawhub publish /path/to/skill --slug my-skill ...

# JSON storage for local data only
data = {"notes": [], "metadata": {}}
with open("data.json", "w") as f:
    json.dump(data, f)

# Pre-commit hook concept
python3 /path/to/security_scan.py scripts/
if [ $? -ne 0 ]; then
    echo "❌ Security scan failed. Fix issues before committing."
    exit 1
fi