DriftHound

A Watchdog for Your Infrastructure State.

What is DriftHound?

DriftHound is a Rails WebApp that receives Terraform drift reports via API and provides visibility into infrastructure drift across your projects.

Live demo site: https://demo.drifthound.io

Features

• API for Drift Reports: Receive Terraform drift check results via authenticated API
• Historical Data: Store and track drift check history per project
• Project Status: Display project status (OK / Drift / Error / Unknown)
• Web Dashboard: View all projects and their drift status at a glance
• Charts Dashboard: Visual analytics with interactive charts for drift monitoring
• Slack Notifications: Real-time alerts when drift is detected or resolved

Requirements

• Ruby 3.x
• PostgreSQL
• Rails 8.0+

Local Development

Tip

Demo mode populates the app with realistic fake projects, environments, and drift history so you can browse all features without any real infrastructure. Admin credentials are created automatically (admin@drifthound.io / demo1234).

Non-Docker Setup

1. Empty instance — requires ADMIN_EMAIL and ADMIN_PASSWORD in your .env file

make setup
make start

2. Demo mode

make setup-demo
make start

Running Tests

Important

Running System tests requires google-chrome to be installed.

1. Create Test DB

make prepare-test-db

2. Run Tests

make run-tests

Docker Setup

Empty instance — requires ADMIN_EMAIL and ADMIN_PASSWORD in your .env file

make docker-setup

With demo data — admin created automatically (admin@drifthound.io / demo1234)

make docker-setup-demo

CLI Usage

DriftHound provides a CLI to automate drift checks in CI/CD pipelines.

Quick Install

sudo curl -L https://raw.githubusercontent.com/drifthoundhq/drifthound/main/bin/drifthound-cli -o /usr/local/bin/drifthound && sudo chmod +x /usr/local/bin/drifthound

Usage Example

drifthound --tool=terraform \
  --project=my-project \
  --environment=production \
  --token=YOUR_API_TOKEN \
  --api-url=http://localhost:3000 \
  --dir=./terraform

📖 See docs/cli-usage.md for detailed CLI documentation, Docker usage, and CI/CD integration examples.

---

API Usage

You can submit drift check results directly to the API:

curl -X POST \
  http://localhost:3000/api/v1/projects/my-project/environments/my-env/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "drift",
    "add_count": 2,
    "change_count": 1,
    "destroy_count": 0,
    "duration": 8.2,
    "raw_output": "Plan: 2 to add, 1 to change, 0 to destroy."
  }'

Generate an API Token:

1. Log in as admin at /login
2. Click API Tokens in the navigation bar
3. Create a new token and copy it (it's only shown once!)

📖 See docs/api-usage.md for complete API documentation, including advanced features and examples.

---

GitHub Actions Integration

Automate drift detection in your GitHub workflows with the official DriftHound GitHub Action.

🔄 GitHub Action: https://github.com/drifthoundhq/drifthound-action

---

Deployment

DriftHound can be deployed to production environments using Docker and Kubernetes.

Docker Images

Pre-built Docker images are available in the GitHub Container Registry:

docker pull ghcr.io/drifthoundhq/drifthound:latest

Kubernetes Deployment

A Helm chart is available for deploying DriftHound to Kubernetes clusters:

📦 Helm Chart Repository: https://github.com/drifthoundhq/helm-chart/

For deployment instructions and configuration options, refer to the Helm chart documentation.

---

Documentation

• Configuration Guide - Environment variables, database setup, Slack configuration, and deployment examples
• CLI Guide - Detailed CLI documentation, Docker usage, and CI/CD integration examples
• API Reference - Complete API documentation, advanced features, and integration examples
• Slack Notifications - Configure Slack alerts for drift detection

Architecture

flowchart LR
    A["CI/CD (Terraform)"] --> B["DriftHound API"]
    B --> C["PostgreSQL (Storage)"]

Loading

License

AGPL-3.0