Skip to content

catherinevee/driftmgr

BranchesTags

Repository files navigation

     .___      .__  _____  __                         
   __| _/______|__|/ ____\/  |_  _____    ___________ 
  / __ |\_  __ \  \   __\\   __\/     \  / ___\_  __ \
 / /_/ | |  | \/  ||  |   |  | |  Y Y  \/ /_/  >  | \/
 \____ | |__|  |__||__|   |__| |__|_|  /\___  /|__|   
      \/                             \//_____/

DriftMgr

Advanced Terraform drift detection and remediation for multi-cloud environments with comprehensive security, compliance, and monitoring capabilities.

CI/CD Pipeline Drift Detection Checkov Security Go Report Card Code Coverage Release

License Go Version Security

Table of Contents

Why DriftMgr

The Problem

Infrastructure drift occurs when actual cloud resources diverge from Terraform state:

  • Manual changes bypass version control
  • Emergency fixes create undocumented modifications
  • Multiple teams cause configuration conflicts
  • Untracked resources increase costs and security risks

The Solution

DriftMgr provides comprehensive infrastructure management with:

  • 30-second quick scans for CI/CD pipelines
  • Smart detection that prioritizes critical resources
  • Automated remediation with multiple strategies
  • Multi-cloud support across AWS, Azure, GCP, and DigitalOcean
  • Security & compliance with OPA policy engine and SOC2/HIPAA support
  • Real-time monitoring with web dashboard and API
  • Terragrunt integration for complex infrastructure management
  • Comprehensive testing with 80%+ code coverage

Quick Start

Get drift detection running in under 2 minutes:

# Install
go install github.com/catherinevee/driftmgr/cmd/driftmgr@latest

# Detect drift in current directory
driftmgr drift detect --state terraform.tfstate

# Start web dashboard
driftmgr serve web --port 8080

# Access the modern web interface at http://localhost:8080

Example Output

Drift Detection Summary
----------------------
Resources Scanned: 47
Drift Detected: 3

MODIFIED: aws_security_group.web (critical)
  - ingress rule added outside Terraform
  
MISSING: aws_s3_bucket.logs
  - Resource deleted but exists in state

UNMANAGED: aws_ec2_instance.temp-debug
  - Resource created outside Terraform

Installation

Binary Installation

# macOS/Linux
curl -L https://github.com/catherinevee/driftmgr/releases/latest/download/driftmgr-$(uname -s)-$(uname -m) -o driftmgr
chmod +x driftmgr
sudo mv driftmgr /usr/local/bin/

# Windows
# Download from releases page

From Source

git clone https://github.com/catherinevee/driftmgr.git
cd driftmgr
go build -o driftmgr ./cmd/driftmgr

Docker

docker pull catherinevee/driftmgr:latest
docker run -v ~/.aws:/root/.aws:ro catherinevee/driftmgr discover --provider aws

Core Concepts

Detection Modes

Mode Duration Use Case What It Checks
Quick <30s CI/CD pipelines Resource existence
Deep 2-5min Scheduled audits All attributes
Smart Adaptive Production Critical resources deep, others quick

Resource Criticality

DriftMgr automatically prioritizes resources:

  • Critical: Databases, security groups, IAM roles
  • High: Load balancers, encryption keys
  • Medium: Compute instances, storage
  • Low: Tags, metadata

Remediation Strategies

Strategy Action Use Case
Code-as-Truth Apply Terraform Enforce desired state
Cloud-as-Truth Update code Accept cloud changes
Manual Generate plan Review before applying

Usage Guide

Drift Detection

Basic drift detection:

# Quick scan (30 seconds)
driftmgr drift detect --state terraform.tfstate --mode quick

# Deep analysis
driftmgr drift detect --state terraform.tfstate --mode deep

# Smart mode (recommended for production)
driftmgr drift detect --state terraform.tfstate --mode smart

Filter by provider or resource:

# AWS only
driftmgr drift detect --state terraform.tfstate --provider aws

# Specific resource types
driftmgr drift detect --state terraform.tfstate --resource-type aws_security_group

Resource Discovery

Discover all resources in your cloud accounts:

# Auto-discover across all configured providers
driftmgr discover

# Specific provider and region
driftmgr discover --provider aws --region us-east-1

# With filters
driftmgr discover --provider azure --filter "tag:Environment=production"

State Management

Work with Terraform state files:

# Analyze state file
driftmgr analyze --state terraform.tfstate

# Pull from remote backend
driftmgr state pull s3 terraform.tfstate --bucket my-states --key prod.tfstate

# Push to remote backend  
driftmgr state push terraform.tfstate s3 --bucket my-states --key prod.tfstate

# List remote states
driftmgr state list --backend s3 --bucket my-states

Remediation

Fix detected drift:

# Preview changes (dry run)
driftmgr remediate --state terraform.tfstate --dry-run

# Apply Terraform (code-as-truth)
driftmgr remediate --state terraform.tfstate --strategy code-as-truth

# Update code to match cloud (cloud-as-truth)
driftmgr remediate --state terraform.tfstate --strategy cloud-as-truth

# Interactive mode with approval
driftmgr remediate --state terraform.tfstate --interactive

Import Resources

Import unmanaged resources:

# Auto-discover and generate imports
driftmgr import --provider aws --auto-discover

# Import specific resource type
driftmgr import --provider aws --resource-type aws_s3_bucket

# Bulk import from file
driftmgr import --from-file unmanaged-resources.json

Configuration

Configuration File

Create driftmgr.yaml:

# Provider settings
providers:
  aws:
    regions: [us-east-1, us-west-2]
    profile: production
  azure:
    subscription_id: ${AZURE_SUBSCRIPTION_ID}
  gcp:
    project_id: ${GCP_PROJECT_ID}

# Detection settings  
detection:
  mode: smart
  workers: 10
  timeout: 5m

# State discovery
state_discovery:
  backends:
    s3:
      buckets: [terraform-states]
    azurerm:
      storage_accounts: [tfstates]

# Remediation
remediation:
  dry_run: true
  require_approval: true
  backup_state: true

Environment Variables

# AWS
export AWS_PROFILE=production
export AWS_REGION=us-east-1

# Azure
export AZURE_SUBSCRIPTION_ID=xxx
export AZURE_TENANT_ID=xxx
export AZURE_CLIENT_ID=xxx
export AZURE_CLIENT_SECRET=xxx

# GCP
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# DigitalOcean
export DIGITALOCEAN_TOKEN=xxx

# DriftMgr
export DRIFTMGR_LOG_LEVEL=info
export DRIFTMGR_WORKERS=10

Cloud Providers

AWS

Authentication methods:

  • IAM roles (recommended for EC2)
  • AWS credentials file
  • Environment variables
  • AssumeRole with MFA

Supported resources: EC2, VPC, S3, RDS, IAM, Lambda, ECS, EKS

Azure

Authentication methods:

  • Service principal
  • Managed identity
  • Azure CLI

Supported resources: VMs, VNets, Storage, SQL, AKS, Key Vault

GCP

Authentication methods:

  • Service account JSON
  • Application default credentials
  • Workload identity

Supported resources: Compute, Networks, Storage, CloudSQL, GKE

DigitalOcean

Authentication methods:

  • API token

Supported resources: Droplets, Volumes, Load Balancers, Databases

Advanced Features

Web Interface

Start the web server:

# Basic
driftmgr serve web

# With authentication
driftmgr serve web --auth --jwt-secret $SECRET

# Custom port
driftmgr serve web --port 9090

Access at http://localhost:8080

Features:

  • Real-time drift detection
  • Interactive resource explorer
  • Visual dependency graphs
  • Remediation workflows
  • Export reports (JSON, CSV, HTML)

API Server

Start API server:

driftmgr serve api --port 8081

Endpoints:

  • POST /api/discover - Trigger discovery
  • GET /api/drift - Get drift results
  • POST /api/remediate - Execute remediation
  • GET /api/resources - List resources
  • GET /api/health - Health check

Terragrunt Support

# Analyze Terragrunt project
driftmgr terragrunt analyze --path ./infrastructure

# Detect drift in Terragrunt modules
driftmgr terragrunt drift --path ./infrastructure

# Run-all operations
driftmgr terragrunt run-all plan --path ./infrastructure

Continuous Monitoring

# Start monitoring daemon
driftmgr monitor start --interval 5m

# With webhook notifications
driftmgr monitor start --webhook https://slack.webhook.url

# Status
driftmgr monitor status

Compliance & Reporting

# Generate compliance report
driftmgr compliance report --standard cis-aws

# Policy validation
driftmgr policy validate --policy-file policies.rego

# Audit trail
driftmgr audit export --format json --from 2024-01-01

Security & Compliance

Policy Engine

DriftMgr includes a comprehensive policy engine with OPA integration:

# Create security policy
driftmgr security policy create --name "encryption-required" --file policy.rego

# Run compliance checks
driftmgr security scan --policy encryption-required

# Generate compliance reports
driftmgr security report --standard soc2
driftmgr security report --standard hipaa
driftmgr security report --standard pci-dss

Security Features

  • Policy as Code: Define security policies using Rego
  • Compliance Standards: Built-in support for SOC2, HIPAA, PCI-DSS
  • Real-time Scanning: Continuous security monitoring
  • Vulnerability Detection: Integration with security scanners
  • Audit Logging: Comprehensive audit trails

Policy Examples

# encryption-required.rego
package driftmgr.security

deny[msg] {
    input.type == "aws_s3_bucket"
    not input.server_side_encryption_configuration
    msg := "S3 bucket must have encryption enabled"
}

deny[msg] {
    input.type == "aws_security_group"
    input.ingress[_].from_port == 22
    input.ingress[_].cidr_blocks[_] == "0.0.0.0/0"
    msg := "SSH access should not be open to the world"
}

Web Dashboard

Modern Web Interface

DriftMgr features a comprehensive web dashboard with:

  • Real-time Monitoring: Live drift detection and alerts
  • Interactive Resource Explorer: Visual resource management
  • Compliance Dashboard: Security and compliance status
  • Terragrunt Support: Module hierarchy visualization
  • Backend Discovery: Automatic remote backend detection
  • State Management: Visual state file operations

Dashboard Features

# Start with authentication
driftmgr serve web --auth --jwt-secret $SECRET

# Enable HTTPS
driftmgr serve web --tls-cert cert.pem --tls-key key.pem

# Custom configuration
driftmgr serve web --config dashboard.yaml

Dashboard Views

  • Backend Discovery: Remote backend scanning and management
  • State Management: Terraform state file operations
  • Drift Detection: Real-time drift monitoring
  • Resources: Infrastructure resource management
  • Terragrunt: Module dependency visualization
  • Remediation: Automated fix workflows
  • Compliance: Security policy management
  • Monitoring: System metrics and alerts

Testing & Quality

Comprehensive Test Coverage

DriftMgr maintains high-quality standards with:

  • 80%+ Code Coverage: Comprehensive unit and integration tests
  • Automated Testing: CI/CD pipeline with GitHub Actions
  • Security Testing: Automated security scans with multiple tools
  • Performance Testing: Load testing and benchmarking
  • Quality Gates: Automated quality checks and linting

Test Suite

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test suites
go test ./internal/api/...
go test ./internal/security/...
go test ./internal/providers/...

# Run integration tests
go test ./tests/integration/...

# Run benchmarks
go test -bench=. ./tests/benchmarks/...

Quality Tools

  • Go Report Card: Code quality analysis
  • GolangCI-Lint: Comprehensive linting
  • Gosec: Security vulnerability scanning
  • Codecov: Coverage reporting
  • Checkov: Infrastructure security scanning
  • Semgrep: Static analysis security testing

CI/CD Pipeline

The project includes automated workflows for:

  • Build & Test: Automated testing on multiple Go versions
  • Security Scanning: Multiple security tools integration
  • Code Quality: Linting, formatting, and quality checks
  • Coverage Reporting: Automated coverage tracking
  • Release Management: Automated releases and versioning

API Reference

CLI Commands

driftmgr
├── discover        # Resource discovery
├── drift          
│   ├── detect      # Detect drift
│   └── report      # Generate reports
├── analyze         # Analyze state files
├── remediate       # Fix drift
├── import          # Import resources
├── state          
│   ├── pull        # Pull from backend
│   ├── push        # Push to backend
│   └── list        # List states
├── serve          
│   ├── web         # Web dashboard
│   └── api         # API server
├── monitor         # Continuous monitoring
├── security        # Security & compliance
│   ├── scan        # Security scanning
│   ├── policy      # Policy management
│   └── report      # Compliance reports
├── compliance      # Legacy compliance (deprecated)
└── terragrunt      # Terragrunt operations

Go SDK

import "github.com/catherinevee/driftmgr/pkg/drift"

// Create detector
detector := drift.NewDetector(drift.Config{
    Mode: drift.ModeSmart,
    Workers: 10,
})

// Detect drift
results, err := detector.Detect(ctx, stateFile)

Troubleshooting

Common Issues

No credentials found

# Check AWS credentials
aws sts get-caller-identity

# Set profile
export AWS_PROFILE=your-profile

State file locked

# Force unlock (use carefully)
driftmgr state unlock --force

Timeout errors

# Increase timeout
driftmgr drift detect --timeout 10m

# Reduce workers for rate limits
driftmgr discover --workers 5

Memory issues with large states

# Use streaming mode
driftmgr analyze --state terraform.tfstate --stream

# Increase memory limit
export GOGC=50

Debug Mode

# Verbose logging
DRIFTMGR_LOG_LEVEL=debug driftmgr drift detect

# Trace HTTP requests  
DRIFTMGR_LOG_LEVEL=trace driftmgr discover

# Save debug output
driftmgr drift detect --debug 2> debug.log

Performance Tuning

Large Infrastructures

For environments with 1000+ resources:

# driftmgr.yaml
performance:
  workers: 20
  batch_size: 200
  cache_ttl: 10m
  stream_mode: true
  
detection:
  incremental: true
  bloom_filter: true

CI/CD Integration

# .github/workflows/drift.yml
- name: Drift Detection
  run: |
    driftmgr drift detect \
      --state terraform.tfstate \
      --mode quick \
      --output json > drift.json

Contributing

See CONTRIBUTING.md

License

MIT License - see LICENSE

Support

Project Status

DriftMgr is actively maintained with:

  • ✅ Comprehensive Test Coverage: 80%+ code coverage across all modules
  • ✅ Security Hardened: Multiple security scanning tools integrated
  • ✅ CI/CD Pipeline: Automated testing, building, and deployment
  • ✅ Modern Web Dashboard: Real-time monitoring and management interface
  • ✅ Multi-Cloud Support: AWS, Azure, GCP, and DigitalOcean
  • ✅ Terragrunt Integration: Full support for complex infrastructure
  • ✅ Policy Engine: OPA-based security and compliance management
  • ✅ API-First Design: RESTful API with comprehensive endpoints

Recent Updates

  • Latest: Major release with security, compliance, and web dashboard
  • Code Coverage: Comprehensive test suite implementation
  • Security: OPA policy engine and compliance reporting
  • Web Interface: Modern dashboard with real-time monitoring
  • Quality: Automated testing and security scanning

About

Catherine Vee | DevOps/Network Engineer - Terraform Drift Detection

linkedin.com/in/catherinevee

Topics

aws azure terraform gcp

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 4

DriftMgr v1.1.0 - Enhanced Security & Monitoring Latest
Sep 14, 2025
+ 3 releases

Packages

 
 
 

Contributors 2

  •  
  •  

Languages