mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 05:28:02 +03:00
davida-ps
db0339084f
* chore(license): migrate repository licensing to AGPL-3.0-or-later * fix(ci): skip skill dry-run when version is unchanged
134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|