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
• Role-Based Plan Visibility: Optionally restrict raw plan output to editors or admins with PLAN_OUTPUT_MIN_ROLE (see the Configuration Guide)
• Environment Overview: See every project for one environment in a single table at /environments/:key
• Charts Dashboard: Visual analytics with interactive charts for drift monitoring
• Dark Mode: Switch between light and dark themes from the top nav; follows your OS setting until you choose
• 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

Testing SSO (OIDC) Login Locally

Runs the app next to a mock identity provider (mock-oauth2-server), so you can try the OIDC login without a real provider. Run make docker-setup or make docker-setup-demo once first to create the database.

make docker-oidc-start   # builds the app image, starts the app and the mock provider
make docker-oidc-stop

Open http://localhost:3000/login, click Sign in with SSO, and on the mock login page type one of these usernames (leave the claims box empty):

Username	Result
admin, editor, viewer	Signed in with that role
multi	Signed in as admin (member of the viewers and admins groups; the highest role wins)
nogroups	Refused: not in a mapped group
unverified	Refused: the provider marks the email as not verified
clash	Refused: the email belongs to the make docker-setup admin (foo@example.com)
clash-demo	Refused: the email belongs to the demo admin (admin@drifthound.io)

The users and their claims live in dev/oidc/mock-oauth2-server.json. Add a block there to test another case, then run make docker-oidc-stop and make docker-oidc-start so the mock reloads the file. The OIDC settings are in docker-compose.oidc.yml, and docs/configuration.md explains each one.

Note

The mock provider shares the app container's network, so http://localhost:8090 is the same address for your browser and for the app, and no /etc/hosts changes are needed. Plain http discovery is enabled only in development (config/initializers/oidc_local_http.rb).

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."
  }'

Read past drift checks (newest first, paginated, without plan output) to chart trends elsewhere:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "http://localhost:3000/api/v1/checks?project=my-project&since=2025-11-01"

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!)

Tokens are read and write by default. Choose Read only for dashboards or reporting tools that only need the GET endpoints, or Read only, with plan output if they also need to read plans. Both receive 403 Forbidden on writes.

📖 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

Thank you contributors! ❤️