clawsec/skills/clawsec-clawhub-checker/README.md

ClawSec ClawHub Checker

A ClawSec suite skill that enhances the guarded skill installer with ClawHub reputation checks and VirusTotal Code Insight integration.

Purpose

Adds a second layer of security to skill installation by:

1. Checking ClawHub's VirusTotal Code Insight reputation scores
2. Analyzing skill age, author reputation, and download statistics
3. Requiring double confirmation for suspicious skills
4. Integrating with existing ClawSec advisory checks

Architecture

clawsec-suite (base)
└── clawsec-clawhub-checker (enhancement)
    ├── enhanced_guarded_install.mjs - Main enhanced installer
    ├── check_clawhub_reputation.mjs - Reputation checking logic
    ├── setup_reputation_hook.mjs - Integration script
    └── hooks/ - Enhanced advisory guardian hook

Installation

# First install the base suite
npx clawhub install clawsec-suite

# Then install the checker
npx clawhub install clawsec-clawhub-checker

# Run setup to integrate with existing suite
node scripts/setup_reputation_hook.mjs

# Restart OpenClaw gateway
openclaw gateway restart

Setup installs these scripts into clawsec-suite/scripts:

• enhanced_guarded_install.mjs
• guarded_skill_install_wrapper.mjs (drop-in wrapper)
• check_clawhub_reputation.mjs

The original guarded_skill_install.mjs remains unchanged.

Usage

Enhanced Guarded Installer

# Basic usage via wrapper (includes reputation checks)
node scripts/guarded_skill_install_wrapper.mjs --skill some-skill --version 1.0.0

# Direct usage (enhanced script)
node scripts/enhanced_guarded_install.mjs --skill some-skill --version 1.0.0

# With reputation confirmation override
node scripts/guarded_skill_install_wrapper.mjs --skill suspicious-skill --version 1.0.0 --confirm-reputation

# Adjust reputation threshold (default: 70)
node scripts/guarded_skill_install_wrapper.mjs --skill some-skill --reputation-threshold 80

Reputation Check Only

# Check reputation without installation
node scripts/check_clawhub_reputation.mjs some-skill 1.0.0 70

Exit Codes

• 0 - Safe to install
• 42 - Advisory match found (requires --confirm-advisory)
• 43 - Reputation warning (requires --confirm-reputation) - NEW
• 1 - Error

Reputation Signals Checked

1. VirusTotal Code Insight - Malicious code patterns
2. Skill Age - New skills (<7 days) are riskier
3. Author Reputation - Number of published skills
4. Update Frequency - Stale skills (>90 days)
5. Download Statistics - Low download counts
6. Version Existence - Specified version availability

Configuration

Environment variables:

• CLAWHUB_REPUTATION_THRESHOLD - Minimum score (0-100, default: 70)

Integration Points

1. Enhanced guarded_skill_install.mjs - Wraps original with reputation checks via guarded_skill_install_wrapper.mjs and enhanced_guarded_install.mjs
2. Updated advisory guardian hook - Adds reputation warnings to alerts
3. Catalog entry in clawsec-suite - Listed as available enhancement

Development

Files

• SKILL.md - Main documentation
• skill.json - Skill metadata and SBOM
• scripts/enhanced_guarded_install.mjs - Enhanced installer
• scripts/check_clawhub_reputation.mjs - Reputation logic
• scripts/setup_reputation_hook.mjs - Integration script
• hooks/clawsec-advisory-guardian/lib/reputation.mjs - Hook module

Testing

# Test reputation check
node scripts/check_clawhub_reputation.mjs clawsec-suite

# Test enhanced installer (dry run)
node scripts/enhanced_guarded_install.mjs --skill test-skill --dry-run

# Test setup
node scripts/setup_reputation_hook.mjs

Security Considerations

• Reputation checks are heuristic, not definitive
• False positives possible with legitimate novel skills
• Always review skill code before overriding warnings
• This is defense-in-depth, not replacement for advisory feeds

License

GNU AGPL v3.0 or later - Part of the ClawSec security suite