Using Terraform to Enable S3 Versioning for HIPAA Integrity

terraform s3 versioning hipaa integrity supports HIPAA’s integrity requirement by making prior object versions recoverable when ePHI is overwritten or deleted, while Terraform provides evidence that the control was deployed consistently. It helps address 45 CFR §164.312(c)(1), which requires protections against improper alteration or destruction of ePHI, but versioning must be paired with access controls, audit logging, monitoring, and recovery procedures to be a defensible safeguard. For the addressable mechanism at §164.312(c)(2), organizations should also use hashes, application validation, or signed records to corroborate that restored data has not been changed without authorization.

What can Terraform automate, and what still requires governance?

As a vCISO, I advise clients to treat Terraform as the enforcement mechanism for their chosen S3 baseline, not as the policy itself. Terraform can make versioning, encryption, logging, and preventive bucket settings repeatable across accounts. It cannot determine whether a particular deleted psychotherapy note should be restored, whether a clinician’s change was clinically appropriate, or whether a workforce member was authorized to access a specific record.

One client, Harbor Path Behavioral Health, operates 14 outpatient locations with approximately 175 employees. Its patient engagement platform exports appointment records and encrypted document packages to S3 each night, while its billing vendor deposits remittance files in a separate bucket. A bucket owner accidentally deleting an export should not permanently destroy the only recoverable copy. Terraform-managed S3 versioning makes recovery possible, but Harbor Path still needs a documented restoration workflow and a person authorized to decide which version is authoritative.

How do you implement terraform s3 versioning hipaa integrity controls?

Start by creating a dedicated bucket for a defined ePHI workflow, enabling versioning at creation, requiring encryption, blocking public access, and retaining noncurrent versions long enough to support investigation and recovery. The example below assumes the organization already has an AWS KMS customer-managed key and a central CloudTrail configuration. The bucket name is intentionally specific to a production workflow so it can be tied to an asset inventory and HIPAA risk analysis.

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

variable "kms_key_arn" {
  type        = string
  description = "KMS key approved for production ePHI storage."
}

resource "aws_s3_bucket" "clinical_exports" {
  bucket = "harbor-path-prod-clinical-exports"
}

resource "aws_s3_bucket_versioning" "clinical_exports" {
  bucket = aws_s3_bucket.clinical_exports.id

  versioning_configuration {
    status = "Enabled"
  }
}

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

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = var.kms_key_arn
    }

    bucket_key_enabled = true
  }
}

resource "aws_s3_bucket_public_access_block" "clinical_exports" {
  bucket                  = aws_s3_bucket.clinical_exports.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_s3_bucket_lifecycle_configuration" "clinical_exports" {
  bucket = aws_s3_bucket.clinical_exports.id

  rule {
    id     = "retain-noncurrent-clinical-exports"
    status = "Enabled"

    filter {}

    noncurrent_version_expiration {
      noncurrent_days = 2555
    }

    abort_incomplete_multipart_upload {
      days_after_initiation = 7
    }
  }
}

output "clinical_exports_bucket" {
  value = aws_s3_bucket.clinical_exports.bucket
}

The 2,555-day noncurrent-version retention in this example is a business decision, not a universal HIPAA requirement. HIPAA does not prescribe an S3 retention period. The compliance owner, legal counsel, records-management lead, and system owner should approve the period based on operational need, applicable state law, contracts, and the organization’s documented retention schedule.

Do not use a lifecycle expiration rule for current objects unless the workflow explicitly permits it. Expiring current versions can create an avoidable availability and records-retention problem. Also note that versioning does not prevent deletion; it preserves a noncurrent version after a delete marker or overwrite. For highly sensitive, immutable evidence sets, evaluate S3 Object Lock during bucket creation. Object Lock has operational consequences and cannot simply be enabled later on an existing bucket.

How should the module prevent versioning from being suspended?

A common control failure is not that versioning was never enabled; it is that an administrator later suspended it during troubleshooting. Add an explicit deny statement to the bucket policy, then narrowly exempt a controlled break-glass role if the organization has approved one. This makes a routine administrative credential unable to weaken the safeguard.

data "aws_iam_policy_document" "deny_versioning_suspension" {
  statement {
    sid    = "DenyVersioningSuspension"
    effect = "Deny"

    actions = [
      "s3:PutBucketVersioning"
    ]

    resources = [
      aws_s3_bucket.clinical_exports.arn
    ]

    condition {
      test     = "StringEquals"
      variable = "s3:VersioningConfiguration"
      values   = ["Suspended"]
    }
  }
}

resource "aws_s3_bucket_policy" "clinical_exports" {
  bucket = aws_s3_bucket.clinical_exports.id
  policy = data.aws_iam_policy_document.deny_versioning_suspension.json
}

Validate the condition behavior in a nonproduction account before relying on it. IAM policy conditions and permitted operational roles should be reviewed against the organization’s actual administrative model. Terraform S3 versioning is strongest when changes can occur only through reviewed infrastructure code, rather than through unrestricted console administration.

How should this run in CI/CD or scheduled assurance checks?

Use a protected GitHub repository, require pull-request review, run Terraform validation and plan checks before merge, and apply only from a protected branch using short-lived AWS credentials through OIDC. Do not store long-lived AWS access keys in GitHub secrets. The following workflow runs on changes to the Terraform directory and produces a plan for review.

name: terraform-plan

on:
  pull_request:
    paths:
      - "terraform/s3-ephi/**"
  workflow_dispatch:

permissions:
  contents: read
  id-token: write
  pull-requests: write

jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: terraform/s3-ephi

    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.8.5"

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-terraform-plan
          aws-region: us-east-1

      - run: terraform init -input=false
      - run: terraform fmt -check
      - run: terraform validate
      - run: terraform plan -input=false -out=tfplan
      - run: terraform show -no-color tfplan

For higher assurance, add a scheduled nightly job that runs terraform plan -detailed-exitcode against production. An exit code of 2 indicates drift: for example, an administrator may have suspended versioning outside Terraform. Send that result to the ticketing queue and investigate before allowing a normal deployment to overwrite evidence of the change.

Which monitoring and alerting hooks make versioning defensible?

Enable CloudTrail management events in every production account and route them to a protected central logging account. Alert on PutBucketVersioning, bucket-policy changes, and unusual deletion activity. For object-level evidence, CloudTrail S3 data events can record DeleteObject, DeleteObjectVersion, and write activity, though they add cost and should be scoped deliberately.

resource "aws_sns_topic" "s3_integrity_alerts" {
  name = "s3-integrity-alerts"
}

resource "aws_cloudwatch_event_rule" "bucket_versioning_changed" {
  name        = "s3-bucket-versioning-changed"
  description = "Alert when S3 bucket versioning is changed."

  event_pattern = jsonencode({
    source        = ["aws.s3"]
    "detail-type" = ["AWS API Call via CloudTrail"]
    detail = {
      eventSource = ["s3.amazonaws.com"]
      eventName   = ["PutBucketVersioning"]
    }
  })
}

resource "aws_cloudwatch_event_target" "versioning_alert_to_sns" {
  rule      = aws_cloudwatch_event_rule.bucket_versioning_changed.name
  target_id = "security-operations"
  arn       = aws_sns_topic.s3_integrity_alerts.arn
}

At Harbor Path, the alert should create a high-priority ticket for the managed security provider and notify the privacy officer when it affects a bucket mapped to clinical exports. The alert is not proof of unauthorized alteration by itself; it is the trigger for review of the CloudTrail event, actor identity, change ticket, affected bucket, and resulting versioning state.

How should teams handle failures and recovery events?

Version restoration should be tested at least annually and after material workflow changes. For §164.312(c)(2), a practical test includes restoring a selected export version, calculating a SHA-256 checksum, and comparing it with a checksum recorded by the exporting application or a trusted manifest. That corroborates that the recovered file is the expected file, rather than merely demonstrating that S3 retained a prior version.

Next step: Select one production ePHI bucket this month, map its owner and retention decision, and deploy the Terraform baseline through a reviewed pull request with a tested restoration runbook.