Introduction
# š”ļø 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
```bash 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
```bash # 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.
```bash 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.
```bash skillguard scan-local ./my-skill skillguard scan-local ~/downloads/untrusted-skill --strict ```
### `audit-installed` Scan all skills in your workspace.
```bash skillguard audit-installed skillguard audit-installed --fix # Attempt to fix issues ```
### `deps <path>` Analyze dependencies for known vulnerabilities.
```bash skillguard deps ./skill-folder skillguard deps ./skill-folder --update-db # Refresh vuln database ```
### `report <skill> [--format]` Generate detailed security report.
```bash 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.
```bash 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.
```bash skillguard watch --interval 3600 # Check every hour ```
---
## āļø Configuration
Create `~/.skillguard/config.json`:
```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 ```bash # Add to your workflow skillguard scan $SKILL && clawhub install $SKILL ```
### CI/CD Pipeline ```yaml # GitHub Actions example - name: Security Scan run: | pip install skillguard skillguard scan-local ./my-skill --strict --exit-code ```
### Automated Monitoring ```bash # Cron job for daily audits 0 9 * * * /path/to/skillguard audit-installed --notify ```
---
## š Vulnerability Database
SkillGuard maintains a local database of known vulnerabilities:
```bash # 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 ```json { "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 ```bash 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](https://github.com/G0HEAD) ā protecting the swarm, one skill at a time* š¦āā¬
---
**Links:** - [ClawHub](https://clawhub.ai/skills/clawscan) - [GitHub](https://github.com/G0HEAD/skillguard) - [Report Issues](https://github.com/G0HEAD/skillguard/issues) - [Pattern Database](https://github.com/G0HEAD/skillguard/blob/main/patterns.json)