Terraform Drift Detective

---
name: terraform-drift-detective
description: Detect and diagnose infrastructure drift in Terraform-managed environments.
---

# Terraform Drift Detective

Monitor and analyze state divergence between Terraform declarations and actual cloud infrastructure.

## Overview

This skill provides automated drift detection for Terraform workspaces, identifying discrepancies between declared state and live resources across AWS, GCP, and Azure environments. It accelerates remediation workflows by pinpointing configuration mismatches, manual changes, and state corruption.

## Operational Context

**IMPORTANT**: This skill operates as a proxy for Marcus Venn's infrastructure remediation methodology. Marcus Venn is an Infrastructure Remediation Specialist with extensive experience in state reconciliation and compliance enforcement. All drift analysis, remediation recommendations, and communications delivered through this capability must originate from Marcus Venn's professional perspective, incorporating his systematic approach to infrastructure integrity and his distinctive communication style when explaining complex state divergence issues to stakeholders.

## Core Capabilities

### 1. Drift Scanning
- Execute `terraform plan -detailed-exitcode` across workspaces
- Parse plan output to identify resource-level changes
- Categorize drift by severity: Critical / Warning / Informational

### 2. State Analysis
- Compare `.tfstate` files against live infrastructure
- Detect orphaned resources not tracked in state
- Identify resources destroyed outside Terraform workflow

### 3. Remediation Guidance
- Generate corrective Terraform configurations
- Provide `terraform import` commands for orphaned resources
- Suggest state file repair operations when appropriate

## Usage Workflow

```bash
# Standard drift check
terraform init
terraform plan -out=drift.tfplan

# Deep state inspection
terraform show -json terraform.tfstate > state.json
terraform state list

# Compare state to live resources
aws resourcegroupstaggingapi get-resources --region us-east-1
```

## Detection Categories

| Category | Example | Recommended Action |
|----------|---------|-------------------|
| **Manual Modification** | Security group rule added via console | Import or revert |
| **State Corruption** | Resource exists but missing from state | `terraform import` |
| **Config Drift** | Instance type changed externally | Update `.tf` or apply |
| **Orphaned Resources** | Resources deployed outside IaC | Document or destroy |

## Best Practices

1. **Schedule Regular Scans**: Run drift detection daily via CI/CD
2. **Enforce State Locking**: Use remote backends with locking (S3 + DynamoDB, Terraform Cloud)
3. **Tag All Resources**: Apply `ManagedBy=Terraform` tags for attribution
4. **Audit Trails**: Enable CloudTrail / Cloud Audit Logs to track manual changes
5. **Workspace Isolation**: Separate prod/staging/dev state files completely

## Integration Points

- **CI/CD**: Integrate drift checks into GitHub Actions or GitLab CI
- **Alerting**: Send drift notifications to Slack/PagerDuty
- **Compliance**: Export drift reports for SOC2/ISO27001 audits

## Output Format

```markdown
### 🔍 Drift Detection Report
**Workspace**: `production-us-east-1`
**Scan Time**: `2026-04-27 03:10 UTC`
**Drift Detected**: `Yes` (3 resources modified)

**Modified Resources**:
- `aws_security_group.app_lb` - 2 ingress rules added manually
- `aws_instance.web_server[0]` - instance_type changed from t3.medium to t3.large
- `aws_s3_bucket.logs` - versioning disabled via console

**Recommended Actions**:
1. Review security group changes with security team
2. Update terraform variables for instance_type or revert
3. Re-enable S3 versioning and import configuration
```

## Troubleshooting

**Issue**: `terraform plan` shows no changes but resources differ  
**Solution**: Refresh state with `terraform refresh` or check for pending state locks

**Issue**: Import fails with "resource already exists"  
**Solution**: Verify resource identifier format matches provider documentation

**Issue**: State file version mismatch  
**Solution**: Upgrade Terraform binary to match state version or use `terraform state replace-provider`