Infrastructure Drift Control Platform

Detect Terraform-to-AWS drift before it becomes operational debt.

DriftCTL is a read-only Terraform drift-detection and remediation-planning tool for AWS. It helps teams identify and safely resolve Terraform state drift: the common situation where a Terraform-managed environment no longer matches the configuration that exists in AWS.

The tool compares Terraform's recorded expected state with live AWS inventory, identifies the difference, classifies its risk, recommends a safe next action, and records an append-only audit trail. It never runs terraform apply, changes Terraform state, or calls AWS mutation APIs.

Platform Capabilities

Capability	What it provides
Expected versus live comparison	Loads Terraform state through terraform show -json, collects supported AWS configuration through read-only APIs, and compares normalized resource snapshots.
Drift taxonomy	Classifies every finding as missing, unmanaged, or modified, so teams can distinguish deleted resources, AWS-only resources, and changed configuration.
Risk classification	Uses modular severity rules to classify findings as minor, moderate, severe, or critical. Public SSH, RDP, and all-port security-group exposure are treated as critical risks; public RDS exposure and weakened RDS encryption or deletion protection are treated as severe.
Reports and audit history	Produces a Markdown report grouped by resource category and severity, plus append-only JSONL audit events for each scan, finding, and recommendation.
Read-only AWS access	Uses a dedicated least-privilege AWS policy and only Describe, List, and Get collection APIs. The scanner observes and reports; it does not apply remediation.
Environment scoping	Supports repeatable --tag KEY=VALUE filters so a scan can focus on one environment without unrelated regional resources creating findings.
Current AWS coverage	EC2 instances, security groups and their inline or standalone Terraform rules, S3 bucket public-access and encryption controls, VPCs, subnets, internet gateways, NAT gateways, route tables, network ACLs, IAM roles and instance profiles, Application Load Balancers, target groups, listeners, listener rules, RDS DB instances, ECS clusters, task definitions and services, CloudWatch log groups, plus Route 53 hosted zones and records. Unsupported Terraform types are reported as collection diagnostics rather than misclassified as drift.
Extension model	Future AWS services will be added through the same adapter, collector, comparison, severity, reporting, and validation pattern. Each supported service is documented here when it becomes part of the tool.
Automation (planned)	Automated Jenkins and GitHub Actions workflows are planned, but are not included yet. When added, they will run scheduled and on-demand scans, retain reports and audit logs, and notify teams about critical drift.

How DriftCTL Is Used

DriftCTL has two ways of being used:

• Manual Scanning: Scenario: (After a Terraform apply, during an investigation, or before an approved change, an engineer runs a read-only scan against the applied Terraform state and the corresponding AWS environment.) DriftCTL reports supported differences inside the chosen tag scope. It can be used for production or non-production infrastructure when the team applies its normal access controls and change process. (See Configure Read-Only AWS Access and Run a Live Scan With the Full Command for the production manual-scanning workflow.)

• Scheduled Automation: A Jenkins pipeline or GitHub Actions workflow runs the same read-only comparison on a team-defined schedule or on demand, retains reports and audit records, and notifies the team about critical findings via Slack. (P.S. This automation feature is not implemented yet. It is planned as an additional way for teams to use the tool.)

The optional controlled-validation sections in the setup guide document how this project verified real detection behavior in a non-production environment. They are not a third operating mode and are not required before using DriftCTL in production. In routine use, DriftCTL reports whatever supported drift already exists; it does not expect a team to create drift first.

Note

DriftCTL reads applied Terraform state with terraform show -json. It does not run terraform init, terraform plan, terraform apply, or terraform refresh, and it does not call AWS APIs that create, update, or delete resources.

Note

Current coverage boundaries: DriftCTL supports Application Load Balancers, but not Network or Gateway Load Balancers. It does not evaluate target registration or runtime target health. RDS coverage is limited to DB instances, not Aurora clusters. When the tool cannot determine a reliable impact for a difference, it reports NOT ASSESSED instead of overstating risk.

How DriftCTL Works

Terraform establishes the intended environment. DriftCTL later compares Terraform's applied state with the configuration AWS reports, without changing either one.

Terraform configuration
        |
        v
terraform plan -> human review and approval -> terraform apply
                                                   |
                          +------------------------+------------------------+
                          |                                                 |
                          v                                                 v
             Terraform state (expected)                       Live AWS environment
                          |                                                 |
                          +------------------------+------------------------+
                                                   |
                                                   v
                                  DriftCTL scan coordinator (read-only)
                                                   |
                  +--------------------------------+--------------------------------+
                  |                                                                 |
                  v                                                                 v
     Terraform CLI loader: terraform show -json                    AWS collector: Describe/List/Get APIs
                  |                                                                 |
                  v                                                                 v
     Terraform-state adapter -> expected ResourceSnapshots     boto3 adapter -> live ResourceSnapshots
                  |                                                                 |
                  +--------------------------------+--------------------------------+
                                                   |
                                                   v
                             Tag-scope filtering and collection diagnostics
                                                   |
                                                   v
                        Drift detector: missing | unmanaged | modified differences
                                                   |
                                                   v
                        Severity, impact, explanation, and remediation policies
                                                   |
                          +------------------------+------------------------+
                          |                                                 |
                          v                                                 v
          Markdown report grouped by category and severity     Append-only JSONL audit history
                          |                                                 |
                          +------------------------+------------------------+
                                                   |
                                                   v
                              Human review and approved remediation
                        Terraform change or AWS correction; never automatic

Today, an engineer starts the scan manually from the command line. Planned Jenkins and GitHub Actions automation will call the same read-only scan coordinator; they do not change the comparison, risk, reporting, or remediation boundaries.

The Terraform and boto3 adapters convert provider-specific data into common ResourceSnapshot objects. The detector compares those normalized snapshots rather than raw Terraform state or AWS API responses. This separation keeps collection logic, comparison logic, and reporting policies independent.

Quick Start

The offline demonstration is the fastest way to see the tool work. It uses included fixture files that resemble Terraform state and boto3 responses, so it does not access an AWS account or require credentials.

Python 3.11 or later is required. After cloning, change into the repository directory before running these commands. They create a .venv folder in the current directory, so do not run them from your home directory unless the repository is there.

Note

DriftCTL works from Windows, Linux, and macOS terminals. The commands below are Windows PowerShell examples. Bash and Zsh use a different virtual-environment activation command and Unix-style paths; equivalents appear where the syntax differs.

Create the isolated Python environment:

python -m venv .venv

Windows PowerShell can block local activation scripts. Allow this activation script to run in the current PowerShell window only; this does not change your computer's permanent execution-policy setting:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Activate the environment in Windows PowerShell:

.\.venv\Scripts\Activate.ps1

In Bash or Zsh on Linux or macOS, activate the same environment with:

source .venv/bin/activate

Install the project and development dependencies:

python -m pip install -e ".[dev]"

Run the offline scan using the command for your terminal. In Windows PowerShell:

driftctl scan --expected examples\expected.json --live examples\live.json --report reports\offline-drift-report.md --audit audit\offline-events.jsonl

In Bash or Zsh on Linux or macOS:

driftctl scan --expected examples/expected.json --live examples/live.json --report reports/offline-drift-report.md --audit audit/offline-events.jsonl

The command writes a Markdown report and appends JSONL audit events. This credential-free workflow is useful for local evaluation, development, and CI.

For a complete step-by-step guide to using DriftCTL manually, including safe live AWS testing and evidence screenshots, read the setup and usage guide.

Learn More

• Setup and usage guide: the complete manual workflow, from installation and offline evaluation to safe live AWS scans, controlled validation, cleanup, and troubleshooting.
• Terraform infrastructure: the version-controlled non-production infrastructure reference used for this project's controlled live validation.
• Read-only IAM policy: the least-privilege AWS inspection policy used by the live-scan workflow. The setup guide explains how to apply it safely.
• License: GNU Affero General Public License v3.0 permissions, conditions, and limitations. Modified versions offered to users over a network must provide their corresponding source code under the same license.
• Evidence index: screenshots from the offline and controlled live-validation demonstrations.