ClawScan

🛡️ SkillGuard — ClawHub Security Scanner

"Trust, but verify." ClawHub has no moderation process. Any agent can publish any skill. SkillGuard provides the security layer that's missing — scanning skills for dangerous patterns, vulnerable dependencies, and suspicious behaviors before they touch your system.

🚨 Why This Matters

Third-party skills can: RiskImpactExecute arbitrary codeFull system compromiseAccess your filesystemData theft, ransomwareRead environment variablesAPI key theft ($$$)Exfiltrate data via HTTPPrivacy breachInstall malicious dependenciesSupply chain attackPersist backdoorsLong-term compromiseEscalate privilegesRoot access One malicious skill = game over. SkillGuard helps you catch threats before installation.

📦 Installation

clawhub install clawscan Or manually: git clone https://github.com/G0HEAD/skillguard cd skillguard chmod +x scripts/skillguard.py

Requirements

Python 3.8+ clawhub CLI (for remote scanning)

🚀 Quick Start

# Scan a skill BEFORE installing python3 scripts/skillguard.py scan some-random-skill # Scan a local folder (your own skills or downloaded) python3 scripts/skillguard.py scan-local ./path/to/skill # Audit ALL your installed skills python3 scripts/skillguard.py audit-installed # Generate detailed security report python3 scripts/skillguard.py report some-skill --format markdown # Check dependencies for known vulnerabilities python3 scripts/skillguard.py deps ./path/to/skill

🔴 CRITICAL — Block Installation

These patterns indicate serious security risks: CategoryPatternsRiskCode Executioneval(), exec(), compile()Arbitrary code executionShell Injectionsubprocess(shell=True), os.system(), os.popen()Command injectionChild Processchild_process.exec(), child_process.spawn()Shell access (Node.js)Credential TheftAccess to ~/.ssh/, ~/.aws/, ~/.config/Private key/credential theftSystem Files/etc/passwd, /etc/shadowSystem compromiseRecursive Deleterm -rf, shutil.rmtree('/')Data destructionPrivilege Escalationsudo, setuid, chmod 777Root accessReverse ShellSocket + subprocess patternsRemote accessCrypto MiningMining pool URLs, stratum://Resource theft

🟡 WARNING — Review Before Installing

These patterns may be legitimate but warrant inspection: CategoryPatternsConcernNetwork Requestsrequests.post(), fetch() POSTWhere is data going?Environment Accessos.environ, process.envWhich variables?File Writesopen(..., 'w'), writeFile()What's being saved?Base64 Encodingbase64.encode(), btoa()Obfuscated payloads?External IPsHardcoded IP addressesExfiltration endpoints?Bulk File Opsshutil.copytree(), globMass data access?Persistencecrontab, systemctl, .bashrcAuto-start on boot?Package Installpip install, npm installSupply chain risk

🟢 INFO — Noted But Normal

CategoryPatternsNoteFile Readsopen(..., 'r'), readFile()Expected for skillsJSON Parsingjson.load(), JSON.parse()Data handlingLoggingprint(), console.log()DebuggingStandard Importsimport os, import sysCommon libraries

📊 Scan Output Example

╔══════════════════════════════════════════════════════════════╗ ║ 🛡️ SKILLGUARD SECURITY REPORT ║ ╠══════════════════════════════════════════════════════════════╣ ║ Skill: suspicious-helper v1.2.0 ║ ║ Author: unknown-user ║ ║ Files: 8 analyzed ║ ║ Scan Time: 2024-02-03 05:30:00 UTC ║ ╚══════════════════════════════════════════════════════════════╝ 📁 FILES SCANNED ──────────────────────────────────────────────────────────────── ✓ SKILL.md (541 bytes) ✓ scripts/main.py (2.3 KB) ✓ scripts/utils.py (1.1 KB) ✓ scripts/network.py (890 bytes) ✓ config.json (234 bytes) ✓ requirements.txt (89 bytes) ✓ package.json (312 bytes) ✓ install.sh (156 bytes) 🔴 CRITICAL ISSUES (3) ──────────────────────────────────────────────────────────────── [CRIT-001] scripts/main.py:45 │ Pattern: eval() with external input │ Risk: Arbitrary code execution │ Code: result = eval(user_input) │ [CRIT-002] scripts/utils.py:23 │ Pattern: subprocess with shell=True │ Risk: Command injection vulnerability │ Code: subprocess.run(cmd, shell=True) │ [CRIT-003] install.sh:12 │ Pattern: Recursive delete with variable │ Risk: Potential data destruction │ Code: rm -rf $TARGET_DIR/* 🟡 WARNINGS (5) ──────────────────────────────────────────────────────────────── [WARN-001] scripts/network.py:15 — HTTP POST to external URL [WARN-002] scripts/main.py:78 — Reads OPENAI_API_KEY [WARN-003] requirements.txt:3 — Unpinned dependency: requests [WARN-004] scripts/utils.py:45 — Base64 encoding detected [WARN-005] config.json — Hardcoded IP: 192.168.1.100 🟢 INFO (2) ──────────────────────────────────────────────────────────────── [INFO-001] scripts/main.py:10 — Standard file read operations [INFO-002] requirements.txt — 3 dependencies declared 📦 DEPENDENCY ANALYSIS ──────────────────────────────────────────────────────────────── requirements.txt: ⚠️ requests (unpinned - specify version!) ✓ json (stdlib) ✓ pathlib (stdlib) package.json: ⚠️ axios@0.21.0 (CVE-2021-3749 - upgrade to 0.21.2+) ════════════════════════════════════════════════════════════════ VERDICT: 🚫 DANGEROUS ════════════════════════════════════════════════════════════════ ⛔ DO NOT INSTALL THIS SKILL 3 critical security issues found: • Arbitrary code execution via eval() • Command injection via shell=True • Dangerous file deletion pattern Manual code review required before any use. ════════════════════════════════════════════════════════════════

scan <skill-name>

Fetch and scan a skill from ClawHub before installing. skillguard scan cool-automation-skill skillguard scan cool-automation-skill --verbose skillguard scan cool-automation-skill --json > report.json

scan-local <path>

Scan a local skill directory. skillguard scan-local ./my-skill skillguard scan-local ~/downloads/untrusted-skill --strict

audit-installed

Scan all skills in your workspace. skillguard audit-installed skillguard audit-installed --fix # Attempt to fix issues

deps <path>

Analyze dependencies for known vulnerabilities. skillguard deps ./skill-folder skillguard deps ./skill-folder --update-db # Refresh vuln database

report <skill> [--format]

Generate detailed security report. skillguard report suspicious-skill --format markdown > report.md skillguard report suspicious-skill --format json > report.json skillguard report suspicious-skill --format html > report.html

allowlist <skill>

Mark a skill as manually reviewed and trusted. skillguard allowlist my-trusted-skill skillguard allowlist --list # Show all trusted skills skillguard allowlist --remove old-skill

watch

Monitor for new skill versions and auto-scan updates. skillguard watch --interval 3600 # Check every hour

⚙️ Configuration

Create ~/.skillguard/config.json: { "severity_threshold": "warning", "auto_scan_on_install": true, "block_critical": true, "trusted_authors": [ "official", "PaxSwarm", "verified-publisher" ], "allowed_domains": [ "api.openai.com", "api.anthropic.com", "api.github.com", "clawhub.ai" ], "ignored_patterns": [ "test_*.py", "*_test.js", "*.spec.ts" ], "custom_patterns": [ { "regex": "my-internal-api\\.com", "severity": "info", "description": "Internal API endpoint" } ], "vuln_db_path": "~/.skillguard/vulns.json", "report_format": "markdown", "color_output": true }

🔐 Security Levels

After scanning, skills are assigned a security level: LevelBadgeMeaningRecommendationVerified✅Trusted author, no issuesSafe to installClean🟢No issues foundLikely safeReview🟡Warnings onlyRead before installingSuspicious🟠Multiple warningsCareful review neededDangerous🔴Critical issuesDo not installMalicious⛔Known malware patternsBlock & report

Pre-Install Hook

# Add to your workflow skillguard scan $SKILL && clawhub install $SKILL

CI/CD Pipeline

• # GitHub Actions example
• name: Security Scan
• run: |
• pip install skillguard
• skillguard scan-local ./my-skill --strict --exit-code

Automated Monitoring

# Cron job for daily audits 0 9 * * * /path/to/skillguard audit-installed --notify

📈 Vulnerability Database

SkillGuard maintains a local database of known vulnerabilities: # Update vulnerability database skillguard update-db # Check database status skillguard db-status # Report a new vulnerability skillguard report-vuln --skill bad-skill --details "Description..." Sources: CVE Database (Python packages) npm Advisory Database GitHub Security Advisories Community reports

🚫 Limitations

SkillGuard is a first line of defense, not a guarantee: LimitationExplanationObfuscationDetermined attackers can hide malicious codeDynamic codeRuntime-generated code is harder to analyzeFalse positivesLegitimate code may trigger warningsZero-daysNew attack patterns won't be detectedDependenciesDeep transitive dependency scanning is limited Defense in depth: Use SkillGuard alongside: Sandboxed execution environments Network monitoring Regular audits Principle of least privilege

🤝 Contributing

Found a dangerous pattern we missed? Help improve SkillGuard:

Add a Pattern

{ "id": "CRIT-XXX", "regex": "dangerous_function\\(", "severity": "critical", "category": "code_execution", "description": "Dangerous function call", "cwe": "CWE-94", "remediation": "Use safe_alternative() instead", "file_types": [".py", ".js"] }

Report False Positives

skillguard report-fp --pattern "WARN-005" --reason "Legitimate use case"

v2.0.0 (Current)

Comprehensive pattern database (50+ patterns) Dependency vulnerability scanning Multiple output formats (JSON, Markdown, HTML) Configuration file support Trusted author system Watch mode for monitoring updates Improved reporting with CWE references

v1.0.0

Initial release Basic pattern detection Local and remote scanning Audit installed skills

📄 License

MIT License — Use freely, contribute back.

🛡️ Stay Safe

"In the agent ecosystem, trust is earned through transparency. Every skill you install is code you're choosing to run. Choose wisely. Verify always." Built by PaxSwarm — protecting the swarm, one skill at a time 🐦‍⬛ Links: ClawHub GitHub Report Issues Pattern Database