Skill Security Auditor

Automated security analysis tool for AgentSkills that detects vulnerabilities and provides actionable remediation guidance.

Quick Start

Run security audit on all skills:

scripts/audit.py /path/to/skills

Audit specific skill:

scripts/audit.py /path/to/skills --skill instagram-marketing

Generate detailed report:

scripts/audit.py /path/to/skills --format markdown --output security-report.md

Core Capabilities

1. Network Safety Detection

Scans for unsafe network operations:

• Unencrypted HTTP (NET-001): Detects http:// usage that should be https://
• Missing Rate Limiting (NET-002): Identifies API calls without rate limiting
• Missing Timeout (NET-003): Finds network requests without timeout protection
• URL Injection (NET-004): Detects user-controlled URLs without validation

2. Permission Validation

Cross-checks declared permissions against actual usage:

• Undeclared Environment Variables (PERM-001): os.environ usage not in metadata.requires.env
• Undeclared Binaries (PERM-002): subprocess calls not in metadata.requires.bins
• Unused Declarations (PERM-003): Declared permissions never used in code

3. File Operation Security

Detects file system vulnerabilities:

• Path Traversal (FILE-001): User input in file paths without validation
• Unsafe Permissions (FILE-002): Excessive permissions like 0o777 or 0o666

4. Command Execution Safety

Scans for dangerous command patterns:

• Shell Injection (CMD-001): shell=True, os.system(), eval(), exec()
• Missing Timeout (CMD-002): subprocess calls without timeout

Usage

Basic Commands

# Console output (default)
scripts/audit.py /path/to/skills

# Filter by risk level
scripts/audit.py /path/to/skills --min-risk HIGH

# Specific skill
scripts/audit.py /path/to/skills --skill skill-name

Output Formats

# Console (real-time colored output)
scripts/audit.py /path/to/skills --format console

# Markdown report
scripts/audit.py /path/to/skills --format markdown --output report.md

# JSON for CI/CD
scripts/audit.py /path/to/skills --format json --output report.json

CLI Options

Risk Levels

Security Rules Reference

Network Safety

NET-001: Unencrypted HTTP

• Severity: HIGH
• Pattern: http:// URLs
• Fix: Replace with https://
• CWE: CWE-319

NET-002: Missing Rate Limiting

• Severity: MEDIUM
• Pattern: API calls without rate limiting mechanism
• Fix: Implement exponential backoff
• References: Cloud Rate Limiting Strategies

NET-003: Missing Timeout

• Severity: MEDIUM
• Pattern: Network requests without timeout parameter
• Fix: Add timeout=30 to requests

NET-004: URL Injection

• Severity: CRITICAL
• Pattern: User-controlled URL in network request
• Fix: Validate against whitelist, use urlparse
• CWE: CWE-918 (SSRF)

Permission Validation

PERM-001: Undeclared Environment Variables

• Severity: HIGH
• Pattern: os.environ usage not declared in frontmatter
• Fix: Add to metadata.openclaw.requires.env

PERM-002: Undeclared Binary Dependencies

• Severity: MEDIUM
• Pattern: External binary usage not declared
• Fix: Add to metadata.openclaw.requires.bins

PERM-003: Unused Declarations

• Severity: LOW
• Pattern: Declared permissions never used
• Fix: Remove from frontmatter or verify implementation

File Operations

FILE-001: Path Traversal

• Severity: CRITICAL
• Pattern: User input in file paths without validation
• Fix: Use Path.resolve() and validate against base directory
• CWE: CWE-22

FILE-002: Unsafe Permissions

• Severity: MEDIUM
• Pattern: chmod(0o777), chmod(0o666)
• Fix: Use minimum required permissions (0o600 for files, 0o700 for directories)
• CWE: CWE-732

Command Execution

CMD-001: Shell Injection

• Severity: CRITICAL/HIGH
• Pattern: shell=True, os.system(), eval(), exec()
• Fix: Use list arguments in subprocess, never use shell=True
• CWE: CWE-78

CMD-002: Missing Command Timeout

• Severity: MEDIUM
• Pattern: subprocess calls without timeout
• Fix: Add timeout=30 parameter

Exit Codes

Examples

Audit Before Publishing

# Check your skill before packaging
scripts/audit.py ~/.claude/skills --skill my-new-skill

# If any issues found, fix them and re-run
scripts/audit.py ~/.claude/skills --skill my-new-skill --min-risk HIGH

CI/CD Integration

# In GitHub Actions or similar
- name: Security Audit
  run: |
    python scripts/audit.py ./skills --format json --output audit-report.json

- name: Check Results
  run: |
    if [ $? -eq 2 ]; then
      echo "Critical issues found!"
      exit 1
    fi

Review Third-Party Skills

# Before installing a community skill
git clone https://github.com/user/skill-repo /tmp/skill-review
scripts/audit.py /tmp/skill-review --format markdown --output review.md
cat review.md

Best Practices

1. Run Regularly: Audit skills monthly or after updates
2. Prioritize: Fix CRITICAL issues immediately, HIGH within 30 days
3. Verify: Re-scan after fixes to validate improvements
4. Track: Monitor security scores over time
5. Educate: Use findings to learn secure coding patterns

Security Score Calculation

Each skill receives a security score from 0-100:

• Starts at 100
• Deduct points based on findings:
  • CRITICAL: -10 points
  • HIGH: -5 points
  • MEDIUM: -2 points
  • LOW: -1 point

Overall score is the average across all audited skills.

Troubleshooting

No skills found

• Verify the skills directory path
• Ensure each skill has a SKILL.md file

Import errors

• Make sure you're running from the skill root directory
• Check that all scanner files exist in scripts/scanners/

Permission errors

• Ensure the script has execute permissions: chmod +x scripts/audit.py