🛡️ 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:

Risk	Impact
Execute arbitrary code	Full system compromise
Access your filesystem	Data theft, ransomware
Read environment variables	API key theft ($$$)
Exfiltrate data via HTTP	Privacy breach
Install malicious dependencies	Supply chain attack
Persist backdoors	Long-term compromise
Escalate privileges	Root access

One malicious skill = game over.

SkillGuard helps you catch threats before installation.

📦 Installation

clawhub install clawscan

Or manually: bash 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

🔍 What SkillGuard Detects

🔴 CRITICAL — Block Installation

These patterns indicate serious security risks:

Category	Patterns	Risk
Code Execution	`eval()`, `exec()`, `compile()`	Arbitrary code execution
Shell Injection	`subprocess(shell=True)`, `os.system()`, `os.popen()`	Command injection
Child Process	`child_process.exec()`, `child_process.spawn()`	Shell access (Node.js)
Credential Theft	Access to `~/.ssh/`, `~/.aws/`, `~/.config/`	Private key/credential theft
System Files	`/etc/passwd`, `/etc/shadow`	System compromise
Recursive Delete	`rm -rf`, `shutil.rmtree('/')`	Data destruction
Privilege Escalation	`sudo`, `setuid`, `chmod 777`	Root access
Reverse Shell	Socket + subprocess patterns	Remote access
Crypto Mining	Mining pool URLs, `stratum://`	Resource theft

🟡 WARNING — Review Before Installing

These patterns may be legitimate but warrant inspection:

Category	Patterns	Concern
Network Requests	`requests.post()`, `fetch()` POST	Where is data going?
Environment Access	`os.environ`, `process.env`	Which variables?
File Writes	`open(..., 'w')`, `writeFile()`	What's being saved?
Base64 Encoding	`base64.encode()`, `btoa()`	Obfuscated payloads?
External IPs	Hardcoded IP addresses	Exfiltration endpoints?
Bulk File Ops	`shutil.copytree()`, `glob`	Mass data access?
Persistence	`crontab`, `systemctl`, `.bashrc`	Auto-start on boot?
Package Install	`pip install`, `npm install`	Supply chain risk

🟢 INFO — Noted But Normal

Category	Patterns	Note
File Reads	`open(..., 'r')`, `readFile()`	Expected for skills
JSON Parsing	`json.load()`, `JSON.parse()`	Data handling
Logging	`print()`, `console.log()`	Debugging
Standard Imports	`import os`, `import sys`	Common 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:
    ⚠️  [email protected]   (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.

════════════════════════════════════════════════════════════════

🎯 Commands Reference

`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:

Level	Badge	Meaning	Recommendation
Verified	✅	Trusted author, no issues	Safe to install
Clean	🟢	No issues found	Likely safe
Review	🟡	Warnings only	Read before installing
Suspicious	🟠	Multiple warnings	Careful review needed
Dangerous	🔴	Critical issues	Do not install
Malicious	⛔	Known malware patterns	Block & report

🔄 Integration Workflows

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:

Limitation	Explanation
Obfuscation	Determined attackers can hide malicious code
Dynamic code	Runtime-generated code is harder to analyze
False positives	Legitimate code may trigger warnings
Zero-days	New attack patterns won't be detected
Dependencies	Deep 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"

📜 Changelog

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

ClawScan