Skip to content

TFDrift-Falco Documentation

Welcome to the official documentation for TFDrift-Falco, a real-time multi-cloud Terraform drift detection system powered by Falco.

Version: v0.5.0+ | Status: Production Ready | Providers: AWS + GCP

What is TFDrift-Falco?

TFDrift-Falco detects when your cloud infrastructure changes outside of Terraform by:

  1. Monitoring cloud audit logs in real-time (AWS CloudTrail, GCP Audit Logs)
  2. Comparing changes against Terraform state (S3, GCS, or local)
  3. Alerting via Falco when drift is detected
  4. Visualizing drift in Grafana dashboards

Key Features

🌐 Multi-Cloud Support (v0.5.0+)

AWS Coverage

Supports 203+ CloudTrail events across 19 AWS services: - Compute: EC2, Lambda, Auto Scaling - Networking: VPC, Security Groups, ELB/ALB - Storage: S3 - Databases: RDS, Aurora, DynamoDB - Security: IAM, KMS - Containers: ECS, EKS, ECR - Serverless: API Gateway - DNS & CDN: Route53, CloudFront - Messaging: SNS, SQS

View AWS Service Coverage →

GCP Coverage (v0.5.0+)

Supports 100+ Audit Log events across 12+ GCP services: - Compute: Compute Engine, Disks - Networking: VPC, Firewall, Routes, Routers - Storage: Cloud Storage - Databases: Cloud SQL - Security: IAM, KMS, Secret Manager - Containers: GKE, Cloud Run - Serverless: Cloud Functions - Data & Analytics: BigQuery, Pub/Sub

View GCP Service Coverage →

⚡ Real-time Detection

  • Sub-minute latency from cloud change to alert
  • Asynchronous audit log processing (CloudTrail, GCP Audit Logs)
  • Parallel multi-cloud service detection
  • Event-driven architecture with Falco

🔐 Security-Focused

  • IAM policy drift detection (AWS IAM, GCP IAM)
  • Encryption configuration monitoring (S3, KMS, Cloud Storage)
  • Firewall rule changes (Security Groups, GCP Firewall)
  • Key management (AWS KMS, GCP KMS)
  • Service account modifications (GCP Service Accounts)

📊 Production-Ready Monitoring

  • Grafana dashboards for multi-cloud visibility
  • Falco rules with severity levels
  • User attribution for every change (IAM principals, service accounts)
  • Alert integration ready (Slack, Discord, webhooks)
  • Multi-cloud unified view in single dashboard

Quick Start

Prerequisites

For AWS: - AWS account with CloudTrail enabled - Falco with cloudtrail plugin

For GCP (v0.5.0+): - GCP project with Audit Logs enabled - Falco with gcpaudit plugin - Pub/Sub subscription for Audit Logs

Common: - Terraform state file (S3, GCS, or local backend) - Kubernetes cluster (for Falco deployment) - Grafana + Prometheus (optional, for visualization)

Installation

AWS Setup

# Clone the repository
git clone https://github.com/higakikeita/tfdrift-falco.git
cd tfdrift-falco

# Deploy Falco with cloudtrail plugin
kubectl apply -f deployments/falco/

# Configure TFDrift for AWS
vim config.yaml  # Configure AWS provider and S3 state

# Run the detector
./tfdrift --config config.yaml

Full AWS Setup Guide →

GCP Setup (v0.5.0+)

# Quick start (recommended)
./scripts/gcp-quick-start.sh

# Or manual setup
# See full GCP setup guide

Full GCP Setup Guide →

Multi-Cloud Setup

# config.yaml - Monitor both AWS and GCP
providers:
  aws:
    enabled: true
    regions: ["us-east-1", "us-west-2"]
    state:
      backend: "s3"
      s3_bucket: "my-terraform-state"
      s3_key: "aws/terraform.tfstate"

  gcp:
    enabled: true
    projects: ["my-gcp-project-123"]
    state:
      backend: "gcs"
      gcs_bucket: "my-terraform-state"
      gcs_prefix: "gcp/terraform.tfstate"

Full Quickstart Guide →

Architecture

┌─────────────┐
│ AWS Console │ User makes manual change
│   / CLI     │ (e.g., modify EC2 instance type)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ CloudTrail  │ Event: ModifyInstanceAttribute
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  TFDrift    │ 1. Fetch event
│  Detector   │ 2. Load Terraform state
│             │ 3. Compare attributes
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Falco    │ Drift detected!
│    Rules    │ Severity: WARNING
└──────┬──────┘
       │
       ├───────────────┐
       ▼               ▼
┌─────────────┐ ┌─────────────┐
│   Grafana   │ │   Alerting  │
│  Dashboard  │ │ (Slack/PD)  │
└─────────────┘ └─────────────┘

Learn More About Architecture →

Use Cases

1. Detect Unplanned Changes

Problem: Someone modifies infrastructure via cloud console or CLI, bypassing Terraform.

Solution: TFDrift-Falco alerts you immediately with: - What changed - Resource type and modified attributes - Who made the change - IAM user/role (AWS) or principal email (GCP) - When it happened - Precise timestamp with timezone - Where - Account/project, region/zone

Examples: - AWS: EC2 instance type changed via AWS Console - GCP: Compute Engine metadata modified via gcloud CLI

2. Security Compliance

Problem: Security configurations modified without approval across multiple clouds.

Solution: Critical severity alerts for security-related drift:

AWS: - IAM role trust policy changes - S3 bucket made public - Security group rules opened to 0.0.0.0/0 - KMS key deletion scheduled

GCP: - Firewall rules allowing public access - GCS bucket IAM policy changes - Service account key creation - KMS crypto key rotation disabled

3. Multi-Cloud Governance

Problem: Managing drift across multiple cloud providers, accounts, and projects.

Solution: Unified monitoring with multi-cloud support: - AWS: Monitor 10+ accounts across multiple regions - GCP: Monitor multiple projects and organizations - Hybrid: Single dashboard for AWS + GCP resources - Filtering: Account/project, region/zone, service-level filtering

Documentation Sections

Getting Started

AWS Service Coverage (203+ events, 19 services)

GCP Service Coverage (100+ events, 12+ services) - New in v0.5.0

Release Notes

Community

License

TFDrift-Falco is open source under the MIT License.

Next Steps

  1. Understand how TFDrift-Falco works →
  2. Check service coverage for your infrastructure →
  3. Deploy TFDrift-Falco →