Skill Shield — Security Auditor
Scanned@yx2601816404-sys
npx machina-cli add skill @yx2601816404-sys/skill-shield --openclawSkill Shield v0.2.0 — Security Auditor
Scan any skill directory for permissions and dangerous patterns. Get a safety rating before you install.
Usage
Run the scanner on a skill directory:
python3 scripts/scan.py /path/to/skill-directory
Output
The script prints two blocks to stdout:
- A JSON report (between
--- JSON START ---and--- JSON END ---markers) - A Markdown report (between
--- MD START ---and--- MD END ---markers)
Save reports to files
python3 scripts/scan.py /path/to/skill-directory --output-dir /path/to/output
This creates report.json and report.md in the output directory.
Safety Ratings
| Grade | Meaning | Action |
|---|---|---|
| A | Safe | Install freely |
| B | Low risk | Minor concerns, generally safe |
| C | Needs review | Review flagged patterns before installing |
| D | High risk | Significant dangerous patterns detected |
| F | Dangerous | Do not install without thorough manual review |
Detection Capabilities (65 patterns, 11 categories)
- File deletion: rm -rf, shred, unlink, rmtree, rimraf, del /f (7 patterns)
- Network exfiltration: curl POST, wget --post, requests.post, fetch POST, netcat reverse shell, DNS exfil, pipe to curl, socat (9 patterns)
- Environment variable access: process.env, os.environ, .env files, printenv (5 patterns)
- Secret/key access: .ssh/, .gnupg/, private keys, wallets, tokens, passwords, keychain, cloud credentials (8 patterns)
- Privilege escalation: sudo, su, chmod 777, chown, setuid/setgid, doas (6 patterns)
- Code execution: eval, exec(), Function(), child_process, subprocess, os.system, os.popen, compile (8 patterns)
- Data collection: /etc/passwd, /etc/shadow, whoami, hostname, ifconfig, /proc/self (6 patterns)
- Persistence: crontab, systemd, rc.local, shell profile modification, autostart (5 patterns)
- Obfuscation: long base64 strings, hex escapes, charCode, base64 decode, string reversal (5 patterns)
- Cryptocurrency/mining: xmrig/minerd, mining pool URLs, wallet addresses (3 patterns)
- Shell injection: backtick execution, pipe to shell, download-and-execute (3 patterns)
Key Features
Permission Declaration Audit (unique to skill-shield)
Compares tools declared in SKILL.md against tools actually used in code. Reports:
- Undeclared permissions with sensitivity scoring (1-5)
- Unused declared permissions
- Declaration coverage ratio
- Per-tool risk recommendations
Anti-Obfuscation Analysis
Automatically decodes base64 and hex-encoded content, then re-scans decoded output for dangerous patterns. Obfuscated findings receive elevated severity.
Context-Aware False Positive Reduction
- Comments and docstrings: severity reduced by 2
- Markdown code blocks in SKILL.md: severity reduced by 2 (examples, not real code)
- Pattern definition lines in scanner source: skipped entirely
- Original vs adjusted severity shown in reports (e.g., "Low (2←4)")
CWE References
Every detection pattern includes a CWE (Common Weakness Enumeration) reference for professional vulnerability classification.
Exit Codes
| Code | Ratings | Meaning |
|---|---|---|
| 0 | A, B | Safe to install |
| 1 | C, D | Review recommended |
| 2 | F | Do not install |
Overview
Skill Shield is a security auditor for ClawHub skills that scans a skill directory to extract declared permissions and detect dangerous code patterns. It uses a catalog of 65 patterns with CWE references and includes anti-obfuscation analysis to surface hidden risks across 11 categories. It outputs both human-readable Markdown and machine-readable JSON reports, along with a safety rating from A to F to guide installation decisions.
How This Skill Works
Run the scanner on a skill directory with python3 scripts/scan.py /path/to/skill-directory. It cross-checks SKILL.md declared permissions against code usage, decodes obfuscated content, and flags patterns across 11 categories with CWE references. The tool prints a JSON report between --- JSON START --- and --- JSON END --- markers and a Markdown report between --- MD START --- and --- MD END --- markers, and can save report.json and report.md to disk.
When to Use It
- Before installing a new skill in your ClawHub environment.
- During a security review of a skill's safety and permissions.
- Auditing declared permissions against actual code usage.
- Scanning for dangerous patterns using CWE references.
- Generating both human-readable and machine-readable safety reports for audits.
Quick Start
- Step 1: Run the scanner on your skill directory: python3 scripts/scan.py /path/to/skill-directory
- Step 2: Optionally save outputs to a directory: python3 scripts/scan.py /path/to/skill-directory --output-dir /path/to/output
- Step 3: Open report.json and report.md to review the safety rating and findings before installing
Best Practices
- Run Skill Shield as part of the skill assessment workflow before installation.
- Compare declared permissions in SKILL.md with actual code usage to surface undeclared or unused permissions.
- Prioritize remediation for high-severity patterns tied to CWE references identified by the scanner.
- Leverage anti-obfuscation results to detect obfuscated or encoded threats in the skill.
- Use the exit codes to decide install readiness and require fixes before deployment.
Example Use Cases
- A skill is flagged for undeclared permissions after scanning, prompting a permissions fix before install.
- Anti-obfuscation analysis uncovers obfuscated payloads that elevate risk scores.
- Multiple high-severity CWE-patterns are detected, resulting in a D rating and a recommended review.
- A clean skill prints an A rating with no critical findings, enabling immediate installation.
- Reports are generated as report.json and report.md and saved to the specified output directory for audits.
