Skip to main content
Get Heimdall up and running in under 5 minutes. This guide covers the fastest path to running your first security scan.

​
Prerequisites

Before you begin, ensure you have:
  • Rust 1.85+ (2024 edition)
  • PostgreSQL 14+ or Docker
  • Git 2.25+
  • AI API Key — At least one of:
    • Anthropic API key (Claude) - recommended
    • OpenAI API key (GPT-4o)
    • Ollama server URL (for local models)
Docker is optional but recommended for easier PostgreSQL setup and for enabling the Garmr sandbox (PoC validation).

​
Quick Start

1

Clone the repository

git clone https://github.com/modestnerd/heimdall.git
cd heimdall
2

Start PostgreSQL

docker compose -f docker-compose.dev.yml up -d
3

Configure environment

Copy the example environment file and add your AI provider key:
cp .env.example .env
Edit .env and set at least one AI provider:
.env
# Required: Database connection
DATABASE_URL=postgres://heimdall:heimdall@localhost:5432/heimdall

# Required: At least one AI provider (BYOK)
ANTHROPIC_API_KEY=sk-ant-...          # Claude (recommended)
# OPENAI_API_KEY=sk-...               # GPT-4o
# OLLAMA_URL=http://localhost:11434    # Local models

# Recommended: Generate security keys
ENCRYPTION_KEY=$(openssl rand -hex 32)
WEBHOOK_SECRET=$(openssl rand -hex 20)
Generate unique values for ENCRYPTION_KEY and WEBHOOK_SECRET using the commands shown above. These are critical for securing stored API keys and webhook verification.
4

Run Heimdall

The schema is applied automatically on startup:
cargo run --bin heimdall
Wait for the server to start. You should see:
[INFO] Starting Heimdall on http://0.0.0.0:8080
[INFO] Database schema applied successfully
[INFO] Worker enabled, polling every 5 seconds
5

Verify installation

Open your browser to http://localhost:8080 or check the health endpoint:
curl http://localhost:8080/health
# {"status":"ok"}

​
Your First Scan

1

Register an account

  1. Navigate to http://localhost:8080
  2. Click Sign Up
  3. Enter your email and password
  4. Click Register
You’ll be automatically logged in after registration.
2

Add a repository

Heimdall supports multiple ways to connect repositories:
1. Click "Connect Repository" → "GitHub"
2. Authorize the OAuth app
3. Select a repository from your account
GitHub and GitLab OAuth require setting up OAuth apps and configuring GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET or GITLAB_CLIENT_ID/GITLAB_CLIENT_SECRET in your .env file.
3

Trigger a scan

  1. From your repositories list, click on the repository you just added
  2. Click Run Scan
  3. Confirm by clicking Start Scan
The scan will enter a queue and begin processing immediately if a worker is available.
4

Monitor progress

Heimdall provides real-time scan progress via Server-Sent Events (SSE):
  • Ingest — Cloning repository and building code index (AST, symbols, call graph)
  • Tyr — Generating threat model (boundaries, attack surfaces, data flows)
  • Static Analysis — Pattern matching, secret detection, dependency audit
  • Hunt — AI agent investigating security vulnerabilities per threat
  • Víðarr — Adversarial verification to filter false positives
  • Garmr — Sandbox validation of proof-of-concept exploits
  • Report — Ranking findings and generating patches
A typical scan takes 2-5 minutes depending on repository size and number of threats discovered.
5

Review findings

Once the scan completes, you’ll see:
  • Severity-ranked findings — Critical, High, Medium, Low
  • File locations with line numbers and code context
  • Plain English explanations of each vulnerability
  • Suggested patches as unified diffs
  • PoC exploit details (if sandbox-validated)
  • Source badges — AI (Hunt agent), Static (pattern rules), Dependencies (audit)
Click on any finding to view:
  • Full vulnerability details
  • CWE/CVE classification
  • Confidence level (High for static rules, Confirmed for sandbox-validated)
  • Code snippets showing the vulnerable code
  • Step-by-step remediation guidance

​
Understanding Results

​
Severity Levels

SeverityDescriptionExamples
CriticalExploitable remotely with severe impactSQL injection, RCE, authentication bypass
HighSignificant security impactXSS, CSRF, hardcoded credentials
MediumModerate risk or limited exploitabilityInformation disclosure, weak crypto
LowBest practice violationsMissing security headers, verbose errors

​
Finding Sources

  • AI — Discovered by the Hunt agent through code reasoning
  • Static — Pattern-matched by deterministic rules
  • Dependencies — Vulnerable dependencies from audit

​
Confidence Levels

  • High — Static analysis rules (deterministic)
  • Medium — AI-discovered (requires validation)
  • Confirmed — Sandbox-validated with PoC exploit

​
Next Steps

Configuration

Configure AI providers, OAuth, security settings, and workers

Installation

Learn about local development setup and Docker deployment

Scan Pipeline

Deep dive into the 7-stage scan pipeline

API Reference

Integrate Heimdall into your CI/CD pipeline

​
Docker Quick Start

Prefer Docker? Here’s the fastest path:
1

Configure environment

cp .env.example .env
# Edit .env with your AI provider key(s)
2

Start Heimdall + PostgreSQL

docker compose --profile postgres up -d
3

Verify it's running

curl http://localhost:8080/health
# {"status":"ok"}
Open http://localhost:8080 in your browser.
The Docker container requires access to /var/run/docker.sock for the Garmr sandbox. This is mounted automatically in the docker-compose.yml.

​
Troubleshooting

​
Database Connection Failed

If you see DATABASE_URL connection failed:
  1. Verify PostgreSQL is running: 
    docker compose -f docker-compose.dev.yml ps
# OR
brew services list | grep postgresql
  2. Check your DATABASE_URL in .env matches your database credentials
  3. Test the connection: 
    psql postgres://heimdall:heimdall@localhost:5432/heimdall -c "SELECT 1"

​
No AI Provider Configured

If you see No AI provider configured:
  1. Ensure at least one of these is set in .env:
    • ANTHROPIC_API_KEY
    • OPENAI_API_KEY
    • OLLAMA_URL
  2. Restart Heimdall after editing .env

​
Scan Stuck or Failed

If a scan gets stuck:
  1. Check the logs for errors: 
    RUST_LOG=debug cargo run --bin heimdall
  2. Verify Docker is running (required for Garmr sandbox): 
    docker info
  3. Cancel the scan and retry: 
    curl -X POST http://localhost:8080/api/scans/{scan_id}/cancel
Stale scans are automatically timed out after 10 minutes by default. Configure this with WORKER_STALE_TIMEOUT_MINS in .env.

Build docs developers (and LLMs) love

Get started for freeTalk to us