Heimdall

# Heimdall - Security Scanner for AI Agent Skills

Scan OpenClaw skills for malicious patterns before installation. Context-aware scanning with AI-powered narrative analysis.

## When to Use

Use Heimdall when:
- Installing a new skill from ClawHub or GitHub
- Reviewing skills before adding to your workspace
- Auditing existing installed skills
- Someone shares a skill URL and you want to verify it's safe

## Commands

### Basic Scan
```bash
~/clawd/skills/heimdall/scripts/skill-scan.py /path/to/skill
```

### AI-Powered Analysis (Recommended)
```bash
~/clawd/skills/heimdall/scripts/skill-scan.py --analyze /path/to/skill
```
Requires `OPENROUTER_API_KEY` env var or `~/clawd/secrets/openrouter.key`

### Scan from URL
```bash
# Clone to temp, scan, delete
git clone https://github.com/user/skill /tmp/test-skill
~/clawd/skills/heimdall/scripts/skill-scan.py --analyze /tmp/test-skill
rm -rf /tmp/test-skill
```

### Scan All Installed Skills
```bash
for skill in ~/clawd/skills/*/; do
  echo "=== $skill ==="
  ~/clawd/skills/heimdall/scripts/skill-scan.py "$skill"
done
```

## Options

| Flag | Description |
|------|-------------|
| `--analyze` | AI-powered narrative analysis (uses Claude) |
| `--strict` | Ignore context, flag everything |
| `--json` | Output as JSON |
| `-v, --verbose` | Show all findings |
| `--show-suppressed` | Show context-suppressed findings |

## What It Detects (100+ patterns)

### 🚨 Critical
- **credential_access**: .env files, API keys, tokens, private keys
- **network_exfil**: webhook.site, ngrok, requestbin
- **shell_exec**: subprocess, eval, exec, pipe to bash
- **remote_fetch**: curl/wget skill.md from internet
- **heartbeat_injection**: HEARTBEAT.md modifications
- **mcp_abuse**: no_human_approval, auto_approve
- **unicode_injection**: Hidden U+E0001-U+E007F characters

### 🔴 High
- **supply_chain**: External git repos, npm/pip installs
- **telemetry**: OpenTelemetry, Signoz, Uptrace
- **crypto_wallet**: BTC/ETH addresses, seed phrases
- *...

# Heimdall 🛡️

The Watchman of Asgard - Security Scanner for AI Agent Skills

Heimdall scans OpenClaw/Clawdbot skills for malicious patterns before installation. Context-aware scanning reduces false positives by ~85%.

## v4.0 Features (NEW)

### AI-Powered Analysis 🤖

```bash
skill-scan --analyze /path/to/skill
```

Generates a **narrative security report** that explains:
- WHY each finding is dangerous
- Attack scenarios and impact
- What you're agreeing to by installing
- Actionable recommendations

**Example output:**
```
============================================================
🔍 HEIMDALL SECURITY ANALYSIS 
============================================================

📁 Skill: suspicious-skill
⚡ Verdict: 🚨 HIGH RISK - Requires Significant Trust

## Summary
This skill installs code from an external company that can 
self-modify and sends telemetry to third-party servers.

## Key Risks

### 1. Data Exfiltration
OpenTelemetry sends execution traces to Signoz/Uptrace. 
YOUR agent's behavior → THEIR servers. 🚨

### 2. Supply Chain Attack Surface
- Git clones from: external repos
- Frequency: Install + during "self-evolution" cycles

## What You're Agreeing To
1. Installing their code
2. Letting it modify itself
3. Sending telemetry to them
4. Trusting their GitHub repo won't go malicious

## Recommendation
🔴 Don't install on any machine with real data/keys.
✅ Safe only on: air-gapped VM, no secrets, no API keys
============================================================
```

### v3.0 Pattern Detection

| Category | Source | Detects |
|----------|--------|---------|
| 🌐 Remote Fetch | Willison | curl skill.md from internet |
| 💓 Heartbeat Injection | Willison | HEARTBEAT.md modifications |
| 🔧 MCP Tool Abuse | PromptArmor | no_human_approval, auto_approve |
| 🏷️ Unicode Tags | Willison | Hidden U+E0001-U+E007F characters |
| ⚡ Auto-Approve | LLMSecurity | always allow, curl \| bash patterns |
| 💰 Crypto Wallets | opensourcemalware | BTC/ETH address e...