Security scanner for AI agent skills. Heimdall inspects OpenClaw skills and agent toolkits for malicious patterns before installation. Context-aware scanning combined with AI-powered narrative analysis to catch advanced threats.

Your agent runs with high privileges, API keys, and file system access. One malicious skill is all it takes:

# Don't blind install!
git clone https://github.com/unknown/super-agent-skill
# Run Heimdall first
skill-scan --analyze ./super-agent-skill

Built for: OpenClaw Skills · MCP Tools · Agent Workflows · ClawHub Packages

Quick Start · Features · Detection Patterns · How It Works

# 1. Install Heimdall (if not using ClawHub)
git clone https://github.com/henrino3/heimdall.git ~/clawd/skills/heimdall

# 2. Add the alias to your shell
echo 'alias skill-scan="~/clawd/skills/heimdall/scripts/skill-scan.py"' >> ~/.bashrc
source ~/.bashrc

# 3. Run a basic scan
skill-scan /path/to/suspicious-skill

# 4. Run an AI-powered narrative analysis (Recommended)
skill-scan --analyze /path/to/suspicious-skill

# Clone to temp, scan, and clean up
git clone https://github.com/user/suspicious-skill /tmp/test-skill
skill-scan --analyze /tmp/test-skill
rm -rf /tmp/test-skill

# Scan all currently installed skills
for skill in ~/clawd/skills/*/; do
  echo "=== $skill ==="
  skill-scan "$skill"
done

Heimdall isn't just a simple grep. It uses context-aware scanning (~85% fewer false positives than traditional regex scanners) and AI narrative analysis via OpenClaw to explain exactly what the skill intends to do with its permissions.

flowchart LR
    subgraph INPUT["Skill Package"]
        Code["Code (.py, .js, .sh)"]
        Config["Config (.json, .yaml)"]
        Docs["Docs (README.md)"]
    end
    subgraph SCANNER["Heimdall Core"]
        Context["Context Extractor"]
        Engine["Pattern Engine (100+ Rules)"]
        AI["AI Narrative Analyzer"]
    end
    subgraph OUTPUT["Verdict"]
        Report["Severity Score"]
        Narrative["Human-Readable Risk Summary"]
    end

    Code & Config & Docs --> Context
    Context --> Engine
    Engine -- "Flags found" --> AI
    AI -- "Routes via openclaw agent" --> Report & Narrative
    
    style INPUT fill:#f4f4f4,stroke:#333
    style SCANNER fill:#e1f5fe,stroke:#0288d1
    style OUTPUT fill:#ffebee,stroke:#c62828

Heimdall utilizes 100+ detection patterns derived from real-world agent vulnerabilities (Moltbook Security Analysis, PromptArmor, LLMSecurity.net).

• Credential Access: Hardcoded extraction of .env files, API keys, tokens.
• Network Exfiltration: Covert data drops to webhook.site, ngrok, requestbin.
• Shell Execution: Unsafe subprocess, eval, exec, or curl-to-bash pipes.
• Remote Fetching: Dynamic downloading of code from untrusted sources at runtime.
• Agent Subversion: Modifications to HEARTBEAT.md, MCP auto_approve hijacking.
• Unicode Injection: Hidden directional formatting characters (U+E0001-U+E007F).

• Supply Chain: Unpinned external git repos or sketchy npm/pip installs.
• Aggressive Telemetry: Unconsented metrics via OpenTelemetry, Signoz, etc.
• Impersonation: Prompts attempting to "ignore previous instructions".
• Privilege Escalation: Usage of sudo -S or chmod 777.

• Prefill Exfiltration: Bypassing bounds via Google Forms URLs.
• Persistence: Unauthorized crontab or .bashrc modifications.

============================================================
🔍 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.
============================================================

Heimdall dynamically adjusts severity based on where the pattern is found:

• CODE: Full severity.
• CONFIG: -1 severity level.
• DOCS: -3 severity levels (patterns in READMEs are usually examples).
• STRING: -3 severity levels (often just blocklist definitions).

Built by the Enterprise Crew 🚀

• Ada 🔮 (Brain + BD/Sales)
• Spock 🖖 (Research & Ops)
• Scotty 🔧 (Builder)

Keep your agents safe.