Safe Skill

Safe-Skill

Programmatic security scanner for AI agent skills. Unlike prompt-only vetting checklists, this skill includes an automated scanner (scripts/scan.py) that performs real static analysis. Zero external dependencies. Runs anywhere Python 3.8+ is available.

Quick Start

# Scan a local skill directory
python3 {baseDir}/scripts/scan.py /path/to/skill-directory

# Scan a single file
python3 {baseDir}/scripts/scan.py /path/to/SKILL.md

# JSON output for machine consumption
python3 {baseDir}/scripts/scan.py /path/to/skill --json

# Save report to file
python3 {baseDir}/scripts/scan.py /path/to/skill -o report.txt

# Verbose mode (show clean files too)
python3 {baseDir}/scripts/scan.py /path/to/skill -v

# With explicit whitelist config
python3 {baseDir}/scripts/scan.py /path/to/skill -w /path/to/.vetterrc

Remote Fetch + Scan

# GitHub URL
python3 {baseDir}/scripts/fetch_and_scan.py https://github.com/openclaw/skills/tree/main/skills/someone/cool-skill

# ClawHub slug
python3 {baseDir}/scripts/fetch_and_scan.py clawhub:author/skill-name

# GitHub shorthand
python3 {baseDir}/scripts/fetch_and_scan.py github:openclaw/skills/skills/author/skill-name

What It Scans

The scanner runs five analysis passes on every file in a skill:

Pass 1: Pattern Matching (65+ rules)

Regex-based detection across 10 categories: RCE, data exfiltration, credential access, obfuscation, privilege escalation, agent identity theft, persistence/backdoor, suspicious network, filesystem abuse, and runtime package installation.

Pass 2: Python AST Analysis

For .py files, parses the Abstract Syntax Tree to detect patterns regex cannot — e.g. eval(dynamic_var) vs eval("literal"), only flagging the dangerous one.

Pass 3: Shannon Entropy Detection

Catches encoded payloads (base64, hex, encrypted blobs) that evade keyword-based detection.

Pass 4: URL / IP Extraction

Extracts all URLs and hardcoded IPs, classifying each by risk level.

Pass 5: Permission Scope Inference

Automatically extracts what the skill accesses: files, network, commands, env vars, packages.

Markdown Context Awareness

Security documentation describes the very patterns it warns against. Safe-Skill parses Markdown structure and automatically downgrades findings under documentation headings (containing words like "red flag", "warning", "reject", "danger", etc.) — dramatically reducing false positives for security-related skills.

Whitelist Configuration (.vetterrc)

Place a .vetterrc in the skill directory to suppress known-good patterns. See .vetterrc.example.

Risk Scoring

Quantitative scoring (0-100+):

Exit codes: 0 = CLEAN/LOW, 1 = MEDIUM, 2 = HIGH/EXTREME.

Workflow for the Agent

When asked to vet a skill:

1. Run the scanner: python3 {baseDir}/scripts/scan.py <target_path>
   • For remote skills, use: python3 {baseDir}/scripts/fetch_and_scan.py <url_or_slug>
2. Review the report: Focus on critical/high severity items NOT marked [DOC].
3. Cross-reference: For MEDIUM+ findings, read the flagged lines and assess context.
4. Recommend: Provide a final recommendation based on scan results + contextual review.

Limitations

• Static analysis only — no sandboxing or dynamic execution tracing
• No network reputation lookup — URL risk is heuristic
• Regex limits — creative obfuscation can evade; AST helps for Python only
• False positives — legitimate skills using subprocess, network calls will trigger findings

Zero external dependencies. Runs anywhere Python 3.8+ is available.