ClawScan

Security scanner for ClawHub skills. Vet third-party skills before installation — detect dangerous patterns, suspicious code, and risky dependencies.

Security Scan

The skill's files and instructions match a legitimate security scanner, but there are several red flags (prompt‑injection content in SKILL.md, third‑party repository/author not clearly verified, and the tool persists data under ~/.skillguard and may fetch/update vulnerability data) that warrant manual review before running.

Purpose & Capability

The name/description match the provided code and SKILL.md: this is a local security scanner that analyzes skill code and dependencies. It does not request unrelated credentials or unusual binaries in the manifest.

Instruction Scope

Runtime instructions stay within the scanner's purpose (scan a skill, scan a folder, audit installed skills). However SKILL.md contains detected prompt‑injection markers (unicode control characters) which could be an attempt to manipulate automated evaluation or LLMs; it also instructs cloning and running a third‑party GitHub repo—so exercise caution before executing.

Install Mechanism

There is no formal install spec in the package; SKILL.md recommends cloning a GitHub repo and making scripts executable. Using GitHub is common, but because the source/owner is not verified here, pulling and executing code from that repo is a risk. The package already includes scripts/skillguard.py (so a separate download isn't strictly necessary).

Credentials

The skill declares no required environment variables or credentials. The scanner looks for patterns that reference secrets (e.g., ~/.ssh, OPENAI_API_KEY) but it does not itself request or require those credentials in the manifest.

Persistence & Privilege

The scanner is designed to create a user config directory (~/.skillguard) to store config, trust list, vulnerability DB, and cache. This is plausible for a scanner but it is persistent and may fetch/overwrite data (vuln DB). The skill is not force-included (always:false) and does not request elevated privileges in the manifest.

Scan Findings in Context

[unicode-control-chars] unexpected: Prompt-injection patterns (unicode control characters) were found in SKILL.md. A scanner skill does not need to include such characters; these are commonly used to manipulate LLMs or evade simple text-parsing. This should be inspected and removed/justified before trusting the package.

What to consider before installing

What to check before running/installing: - Review the code yourself (open scripts/skillguard.py). Search for any network calls, subprocess.run/os.system usage, code that writes or executes downloaded content, or auto-update routines. Pay special attention to any code that runs shell commands or executes dynamically constructed code (eval/exec/compile). - Investigate the GitHub repository and author: confirm the repo exists, check commit history, issues, stars, and whether the author/organization is trustworthy. If the package points to a repo but the package already contains the script, prefer using the included files rather than re-cloning automatically. - Because SKILL.md contains unicode control characters (prompt-injection markers), view the raw SKILL.md in a safe viewer (or cat -v) and remove/clean those characters before feeding the file to any automated LLM-based evaluator. - Run the scanner in a sandboxed environment or non-privileged user account first (container/VM) to observe network activity and file writes. Monitor outbound network connections to ensure the tool only contacts expected servers. - Inspect what ~/.skillguard will contain (trusted.json, vulns.json, cache). Decide whether you are comfortable with the tool persisting a vulnerability DB and a trust list on disk and whether it will auto-update that DB from network sources. - Do not run it as root. If you want higher assurance, ask the author for a signed release or a reproducible build, and consider static code analysis or running the script through a vetted linter/security tool. If you are not comfortable performing these checks, treat the package as untrusted and avoid executing its scripts on your machine.

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

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:
    ⚠️  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.
  
════════════════════════════════════════════════════════════════

---

🎯 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