AWS integration

How the connection works

Drift detection needs read access to your live AWS state so it can diff the Terraform plan against what actually exists. DriftGuard never stores long-lived credentials — it assumes a role in your account via STS with an external ID. You create the role; DriftGuard assumes it read-only, on demand, per analysis.

1. Create the IAM role

Trust policy

Grant DriftGuard's AWS account permission to assume the role. Copy your account ID and external ID from the dashboard's AWS integration screen.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::DRIFTGUARD_ACCOUNT_ID:root" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "YOUR_ORG_EXTERNAL_ID" }
    }
  }]
}

Permissions policy

Attach a read-only policy. Describe/Get/List actions are enough for drift detection:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ec2:Describe*",
      "rds:Describe*",
      "s3:GetBucketPolicy",
      "s3:ListAllMyBuckets",
      "iam:GetPolicy",
      "iam:ListRoles"
    ],
    "Resource": "*"
  }]
}

2. Register the role

Save the role ARN and your Terraform state backend either in the dashboard (Settings → AWS) or in your repo config. The dashboard call is what actually stores the ARN; the config below documents intent and pins the region and state location:

# .github/driftguard.yml
integrations:
  aws:
    role_arn: arn:aws:iam::123456789012:role/DriftGuardReadOnly
    region: eu-west-1
    state_backend: s3://acme-tfstate/prod/terraform.tfstate

Verify the connection with GET /api/v1/aws/verify, which performs a test AssumeRole and returns success or the STS error.

Without AWS access

AWS access is optional. Cost, security, policy, and semantic recall all run from the Terraform plan alone. Only live-state drift detection requires the role — skip this page if you don't need it yet.