tf-why

Terraform tells you what drifted. tf-why tells you who changed it, when, and how.

---

⚡️ The "Aha!" Moment

Terraform plan shows you a resource is being "updated in-place". But the logs are silent. You need to know if that security group rule was added by a senior dev during an incident or by a script gone rogue.

Don't dig through CloudTrail. Just pipe it to tf-why.

$ terraform show -json plan.tfplan | tf-why

  aws_security_group.web  (ingress rules changed)
  ├── Changed by:   john.doe@company.com
  ├── When:         2 days ago
  ├── Via:          AWS Console
  └── Event:        AuthorizeSecurityGroupIngress

  aws_s3_bucket.assets  (versioning changed)
  └── Changed by:   ci-deploy-role
      ├── When:         1 day ago
      └── Event:        PutBucketVersioning

2 drifted resources found.

---

🛠 Features

• Instant Attribution: Maps Terraform resource changes to specific CloudTrail events.
• Root Cause Analysis: Identifies if a change was made via Console, CLI, or SDK.
• High-Fidelity UI: Clean, tree-like terminal output for better readability.
• Zero Config: Works with your existing AWS credentials and Terraform plans.
• Privacy First: Read-only access to CloudTrail; plan parsing happens entirely locally.

---

🏗 Why This Convinces Senior Devs (Architecture)

Generic tools just search CloudTrail for any change. tf-why is smarter:

1. Strict Resource Mapping: Uses a precise Mapper system that understands the relationship between Terraform resource types (e.g., aws_db_instance) and their corresponding CloudTrail event sources and names (rds.amazonaws.com, ModifyDBInstance).
2. Contextual Intelligence: It doesn't just show the last event; it uses the plan's before and after states to narrow down the exact API call that caused the drift.
3. Parallel Querying: Queries CloudTrail in parallel to ensure attribution completes in seconds, even for large plans.
4. Security: Requires only cloudtrail:LookupEvents permissions. No write access, no secrets, no database needed.

---

🚀 Installation

pip install tf-why

Requirements:

• Python 3.9+
• IAM Permission: cloudtrail:LookupEvents

---

📖 Supported Resources

Over 27 critical AWS resources are supported out-of-the-box, including:

• Networking: VPC, Security Groups, Subnets
• Storage: S3 Buckets, Policies, Versioning
• Compute: EC2, Lambda, ECS, EKS
• IAM: Roles, Users, Policies
• Database: RDS Clusters, DynamoDB

---

🤝 Social Proof & Proof of Work

Check out our Real-World Proof showing attribution on a production-grade infrastructure drift.

---

License

Apache 2.0