Security Best Practices

# ── WRONG — never do this ────────────────────────────────────────────────────

resource "aws_db_instance" "main" {
  username = "admin"
  password = "my-super-secret-password"  # Hardcoded — ends up in Git history forever
}

# Also wrong — terraform.tfvars with secrets committed to Git
# db_password = "my-super-secret-password"

# ── CORRECT PATTERN 1: TF_VAR_ environment variable ─────────────────────────

variable "db_password" {
  description = "RDS master password — set via TF_VAR_db_password environment variable"
  type        = string
  sensitive   = true  # Redacts from all plan/apply terminal output and CI logs
  # No default — forces explicit supply at runtime
}

# In CI/CD pipeline or local shell — never in a file:
# export TF_VAR_db_password="$(aws secretsmanager get-secret-value \
#   --secret-id prod/db/password --query SecretString --output text)"

resource "aws_db_instance" "main" {
  username = "admin"
  password = var.db_password  # Read from the sensitive variable
}

# ── CORRECT PATTERN 2: AWS Secrets Manager data source ───────────────────────

data "aws_secretsmanager_secret_version" "db" {
  secret_id = "prod/db/credentials"  # Only the secret name in code — never the value
}

locals {
  # jsondecode parses the JSON string stored in Secrets Manager
  db_creds = jsondecode(data.aws_secretsmanager_secret_version.db.secret_string)
}

resource "aws_db_instance" "main" {
  username = local.db_creds.username  # Fetched at plan time from Secrets Manager
  password = local.db_creds.password  # Never in any .tf file or state diff output
}

# Secure remote state configuration — every production project needs all of these

terraform {
  backend "s3" {
    bucket = "acme-terraform-state-123456789012"
    key    = "prod/app/terraform.tfstate"
    region = "us-east-1"

    encrypt        = true              # AES-256 encryption at rest — no extra cost
    dynamodb_table = "terraform-state-lock"  # Prevents concurrent applies corrupting state
  }
}

# The state bucket needs these protections on the S3 resource itself:
resource "aws_s3_bucket_versioning" "state" {
  bucket = aws_s3_bucket.state.id
  versioning_configuration { status = "Enabled" }
  # Versioning allows recovery of any previous state version — critical for rollbacks
}

resource "aws_s3_bucket_server_side_encryption_configuration" "state" {
  bucket = aws_s3_bucket.state.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"  # Encrypts all state file contents at rest
    }
  }
}

resource "aws_s3_bucket_public_access_block" "state" {
  bucket                  = aws_s3_bucket.state.id
  block_public_acls       = true   # State files must never be publicly accessible
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

# IAM policy for the Terraform execution role — minimum required permissions
resource "aws_iam_policy" "terraform_state_access" {
  name = "terraform-state-access"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"]
        Resource = [
          "arn:aws:s3:::acme-terraform-state-123456789012",
          "arn:aws:s3:::acme-terraform-state-123456789012/*"
        ]
      },
      {
        Effect = "Allow"
        Action = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:DeleteItem"]
        Resource = "arn:aws:dynamodb:us-east-1:123456789012:table/terraform-state-lock"
      }
    ]
  })
}

# IAM role for Terraform CI/CD — scoped to exactly what it needs

resource "aws_iam_role" "terraform_execution" {
  name = "terraform-execution-prod"

  # Trust policy — only the CI/CD runner role can assume this
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { AWS = "arn:aws:iam::CI_ACCOUNT_ID:role/github-actions-runner" }
      Action    = "sts:AssumeRole"
      # external_id prevents confused deputy attacks — only callers knowing this value can assume
      Condition = { StringEquals = { "sts:ExternalId" = "prod-terraform-deployment" } }
    }]
  })
}

# Attach only the managed policies the configuration actually uses
# A configuration managing EC2 and VPC — not IAM, not RDS, not Lambda
resource "aws_iam_role_policy_attachment" "ec2" {
  role       = aws_iam_role.terraform_execution.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
}

# Custom policy for VPC management — more precise than any managed policy
resource "aws_iam_policy" "vpc_management" {
  name = "terraform-vpc-management"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "ec2:CreateVpc",    "ec2:DeleteVpc",    "ec2:DescribeVpcs",
        "ec2:CreateSubnet", "ec2:DeleteSubnet", "ec2:DescribeSubnets",
        # Only the actions this configuration actually calls
      ]
      Resource = "*"
    }]
  })
}

resource "aws_iam_role_policy_attachment" "vpc" {
  role       = aws_iam_role.terraform_execution.name
  policy_arn = aws_iam_policy.vpc_management.arn
}

# Security baked into a module — callers cannot accidentally create insecure resources

# Pattern 1: Deny by default — require explicit opt-out for anything public-facing
variable "allow_public_access" {
  description = "Allow public access to the S3 bucket — set true only for static websites"
  type        = bool
  default     = false  # Secure by default — public access requires deliberate intent
}

# Pattern 2: Encryption always on — the variable controls key type, not whether to encrypt
variable "kms_key_arn" {
  description = "KMS key ARN for encryption — null uses S3-managed AES-256 (still encrypted)"
  type        = string
  default     = null  # null = free AES-256, non-null = customer-managed KMS key
}

resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
  bucket = aws_s3_bucket.this.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = var.kms_key_arn != null ? "aws:kms" : "AES256"
      kms_master_key_id = var.kms_key_arn  # null for AES-256, ARN for customer KMS
      # Either path results in encryption — there is no unencrypted option exposed
    }
  }
}

# Pattern 3: Preconditions enforce security contracts at plan time
resource "aws_db_instance" "this" {
  # ... resource arguments ...

  lifecycle {
    precondition {
      # Production databases must use Multi-AZ — no exceptions
      condition     = var.environment != "prod" || var.multi_az == true
      error_message = "Production RDS instances must have multi_az = true."
    }

    precondition {
      condition     = var.storage_encrypted == true
      error_message = "storage_encrypted must be true — unencrypted databases are not permitted."
    }
  }
}

# Install and run tfsec
brew install tfsec  # macOS

# Scan the current directory — catches misconfigurations before apply
tfsec .

# Scan with minimum severity filter — only HIGH and CRITICAL
tfsec . --minimum-severity HIGH

# Output JSON for CI/CD parsing
tfsec . --format json --out tfsec-results.json

# ── Suppressing a finding when you have a legitimate reason ──────────────────

resource "aws_s3_bucket" "public_website" {
  bucket = "acme-public-website-assets"

  # tfsec:ignore:aws-s3-block-public-acls
  # tfsec:ignore:aws-s3-no-public-buckets
  # Intentional — this bucket serves a public static website
  # Reviewed and approved by security team 2024-01
  # The suppression comment is the audit trail — never suppress without explanation
}

# .github/workflows/terraform-security.yml
# Security scanning runs BEFORE terraform plan — blocks on HIGH and CRITICAL

name: Terraform Security Gate

on:
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run tfsec — fail on HIGH and CRITICAL
        uses: aquasecurity/tfsec-action@v1.0.0
        with:
          working_directory: .
          minimum_severity: HIGH  # MEDIUM and LOW are warnings only
          soft_fail: false        # Hard fail — pipeline stops on any finding

      - name: Run checkov — compliance frameworks
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: .
          framework: terraform
          soft_fail: false
          # checkov checks CIS AWS benchmarks, HIPAA, PCI-DSS out of the box

      # Only if both security checks pass does the pipeline proceed to plan
      - name: Terraform Init
        run: terraform init

      - name: Terraform Plan
        run: terraform plan -out=tfplan