OpenTofu modules gated by tofu test and Checkov

# AGENTS.md: OpenTofu modules gated by tofu test and Checkov

Infrastructure as code in OpenTofu (HCL works the same in Terraform, with `terraform` for `tofu`). Check
`required_providers` and the lock file before using a provider argument: AWS provider v6 split many bucket
settings into separate resources.

## Commands
- Format: `tofu fmt -recursive`.
- Gate (run before calling a change done): `bash .agents/skills/tofu-module-gate/scripts/gate.sh <module-dir>`.
  It runs fmt check, `tofu init -backend=false -lockfile=readonly`, `tofu validate`, `tofu test` and Checkov, and
  needs no cloud credentials.
- Done means: `gate: ok`, with a `run` block in `tests/` covering the behaviour you changed.

## Rules
- Use the `tofu-module-gate` skill for any change to `.tf` or `.tftest.hcl` files.
- Never run `tofu apply`, `destroy`, `import`, `state` subcommands, `force-unlock` or `-auto-approve`, and never
  read state files. A person plans against real accounts and applies.
- Tests use `mock_provider`. Do not add real credentials, profiles or a backend to make a test pass.
- Every variable has a description and a type; constrained inputs have a `validation` block and a test with
  `expect_failures`.
- Pin providers (`~>` on a minor version) and keep the committed lock file. Upgrading a provider is its own change,
  stated in the summary.
- Fix Checkov findings. An exception is an inline `#checkov:skip=<ID>:<reason>` on the resource, never
  `soft-fail`, `--skip-check` or a repo-wide skip list.
- Root modules enforce OpenTofu state and plan encryption, with the key from the environment or a KMS key
  provider, never from a file.
- Stateful resources (buckets, databases, keys) carry `prevent_destroy = true`. Renames use `moved` blocks.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `tofu-module-gate`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "OpenTofu modules gated by tofu test and Checkov" v1.0.0 — https://loadout.jnw-it.com/loadouts/opentofu-module-checkov/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `tofu-module-gate`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "OpenTofu modules gated by tofu test and Checkov" v1.0.0 — https://loadout.jnw-it.com/loadouts/opentofu-module-checkov/ -->

---
name: tofu-module-gate
description: Write or change an OpenTofu (or Terraform) module so it passes a local gate - fmt, validate, tofu test with a mocked provider, and Checkov with reasoned exceptions only. Use when adding or editing .tf files, module variables, tests, or Checkov skips.
---

# OpenTofu module gate

A module change is done when `scripts/gate.sh` prints `gate: ok`. The gate needs no cloud
credentials and creates nothing: tests run against `mock_provider`, Checkov reads the HCL.

## Workflow

1. Read the module's variables, outputs and tests before editing. Keep one resource type per
   concern (the bucket, its versioning, its encryption ...), as the AWS provider v6 expects.
2. Make the change. Every new input gets a `description`, a `type`, and a `validation` block
   when it has a valid range or format.
3. Add or update a `run` block in `tests/*.tftest.hcl` for the behaviour you changed:
   - `command = plan` with `assert` blocks for secure defaults and computed values;
   - `expect_failures = [var.x]` for every validation rule you add.
4. Run the gate on the module folder:

   ```bash
   TOFU=tofu bash .agents/skills/tofu-module-gate/scripts/gate.sh modules/s3-bucket
   ```

   It runs, in order, and stops at the first failure:
   `tofu fmt -check -recursive`, `tofu init -backend=false -lockfile=readonly`, `tofu validate`,
   `tofu test`, an audit of Checkov exceptions, then Checkov 3.3.29 (through `uvx`).
5. Fix what failed. Report the gate output, not a summary of it.

## Checkov findings

- Fix the finding first. Most S3, IAM and logging findings have a one-resource fix.
- If the finding is genuinely the caller's decision (replication, event notifications), skip it
  inline on the resource, with a reason a reviewer can disagree with:

  ```hcl
  resource "aws_s3_bucket" "this" {
    #checkov:skip=CKV_AWS_144:Cross-region replication is configured by callers that need it
  ```

- Never add `soft-fail: true` or a `skip-check:` list to the repository's Checkov config, and
  never pass `--soft-fail` or `--skip-check` on the command line. The gate refuses both config
  settings, and refuses a skip with no reason or a reason under 10 characters.
- Start the repository config from `references/checkov.yaml`.

## Lock file and providers

- Pin providers with `~>` on a minor version in `required_providers`, and commit the lock file.
  The gate runs init with `-lockfile=readonly`, so a provider change must be a deliberate
  `tofu init -upgrade` that a human reviews in the diff.
- For lock hashes on every platform the team uses:
  `tofu providers lock -platform=linux_amd64 -platform=darwin_arm64`.
- Never commit the `.terraform` folder, state files or plan files.

## Root modules: encrypt state

OpenTofu encrypts state and plan files natively. A root module that uses this module should
carry an `encryption` block with `enforced = true` for both state and plan, and take the key
from the environment (a sensitive variable set by `TF_VAR_...`, or a KMS key provider). See
`references/example-root.tf`. Never write the passphrase into a file.

## What the agent does not do

- No `tofu apply`, `destroy`, `import`, `state` subcommands or `-auto-approve`. A person applies.
  Pair this loadout with terraform-plan-only for a hook that enforces it.
- No `tofu plan` against a real account to "check it works": that is what the mocked tests are for.
- No new provider or module source without saying so in the summary.

## Files

- `scripts/gate.sh`: the gate. Env: `TOFU` (default `tofu`), `CHECKOV` (default
  `uvx --from checkov==3.3.29 checkov`).
- `references/main.tf`, `references/variables.tf`, `references/outputs.tf`,
  `references/versions.tf`: a private, versioned, SSE-KMS S3 bucket module with access logging,
  TLS-only policy and noncurrent-version expiry. Checkov: 0 failed, 2 reasoned skips.
- `references/bucket.tftest.hcl`: four `run` blocks with a mocked AWS provider.
- `references/example-root.tf`: root module with enforced state and plan encryption.
- `references/checkov.yaml`: repository Checkov config.

#!/usr/bin/env bash
# Module gate: fmt, init (lock file read-only), validate, tofu test, Checkov, and an audit of
# Checkov exceptions. Runs no plan against real cloud accounts and never applies.
# Usage: gate.sh [module-dir]   (default: current directory)
# Env: TOFU (default tofu), CHECKOV (default: uvx --from checkov==3.3.29 checkov)
set -uo pipefail

dir="${1:-.}"
TOFU="${TOFU:-tofu}"
CHECKOV="${CHECKOV:-uvx --from checkov==3.3.29 checkov}"
cd "$dir" || { echo "gate: no such directory: $dir"; exit 2; }

fail() { echo "gate: FAILED at $1"; exit 1; }
step() { echo "== $1"; }

step "fmt"
"$TOFU" fmt -check -recursive -diff -no-color || fail "fmt (run: tofu fmt -recursive)"

step "init"
[ -f .terraform.lock.hcl ] || fail "init (no .terraform.lock.hcl: run tofu init and commit the lock file)"
"$TOFU" init -backend=false -input=false -lockfile=readonly -no-color >/dev/null || fail "init"

step "validate"
"$TOFU" validate -no-color || fail "validate"

step "test"
if ls tests/*.tftest.hcl >/dev/null 2>&1; then
  "$TOFU" test -no-color || fail "test"
else
  fail "test (no tests/*.tftest.hcl)"
fi

step "exception audit"
bad=0
if [ -f .checkov.yaml ] && grep -Eq '^[[:space:]]*(soft-fail|soft_fail)[[:space:]]*:[[:space:]]*true' .checkov.yaml; then
  echo "soft-fail is set in .checkov.yaml: findings would not fail the run"; bad=1
fi
if [ -f .checkov.yaml ] && grep -Eq '^[[:space:]]*skip-check[[:space:]]*:' .checkov.yaml; then
  echo "skip-check in .checkov.yaml hides checks repo-wide: use an inline skip with a reason"; bad=1
fi
while IFS= read -r hit; do
  reason="${hit#*checkov:skip=}"; reason="${reason#*:}"
  if [ "$reason" = "${hit#*checkov:skip=}" ] || [ "${#reason}" -lt 10 ]; then
    echo "skip without a reason: $hit"; bad=1
  fi
done < <(grep -rn --include='*.tf' 'checkov:skip=' . | grep -v '/\.terraform/')
[ "$bad" -eq 0 ] || fail "exception audit"

step "checkov"
cfg=()
[ -f .checkov.yaml ] && cfg=(--config-file .checkov.yaml)
# shellcheck disable=SC2086
$CHECKOV -d . "${cfg[@]}" --framework terraform --compact --quiet || fail "checkov"

echo "gate: ok"

# Private, versioned, KMS-encrypted bucket with access logging and an expiry rule for old versions.
# Checkov CKV_AWS_144 (cross-region replication) and CKV2_AWS_62 (event notifications) are skipped
# with a reason: both are per-workload decisions made by the caller, not by this module.
resource "aws_s3_bucket" "this" {
  #checkov:skip=CKV_AWS_144:Cross-region replication is configured by callers that need it
  #checkov:skip=CKV2_AWS_62:Event notifications are wired up by the consuming service
  bucket = var.name
  tags   = var.tags

  lifecycle {
    prevent_destroy = true
  }
}

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

  rule {
    object_ownership = "BucketOwnerEnforced"
  }
}

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

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

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
  bucket = aws_s3_bucket.this.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_logging" "this" {
  bucket        = aws_s3_bucket.this.id
  target_bucket = var.log_bucket
  target_prefix = "s3/${var.name}/"
}

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

  rule {
    id     = "expire-noncurrent"
    status = "Enabled"

    filter {}

    noncurrent_version_expiration {
      noncurrent_days = var.noncurrent_days
    }

    abort_incomplete_multipart_upload {
      days_after_initiation = 7
    }
  }

  depends_on = [aws_s3_bucket_versioning.this]
}

data "aws_iam_policy_document" "tls_only" {
  statement {
    sid     = "DenyInsecureTransport"
    effect  = "Deny"
    actions = ["s3:*"]
    resources = [
      aws_s3_bucket.this.arn,
      "${aws_s3_bucket.this.arn}/*",
    ]

    principals {
      type        = "*"
      identifiers = ["*"]
    }

    condition {
      test     = "Bool"
      variable = "aws:SecureTransport"
      values   = ["false"]
    }
  }
}

resource "aws_s3_bucket_policy" "tls_only" {
  bucket = aws_s3_bucket.this.id
  policy = data.aws_iam_policy_document.tls_only.json

  depends_on = [aws_s3_bucket_public_access_block.this]
}

variable "name" {
  description = "Bucket name. Globally unique, lower case, 3 to 63 characters."
  type        = string

  validation {
    condition     = can(regex("^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$", var.name))
    error_message = "name must be 3-63 lower-case letters, digits, dots or hyphens, starting and ending with a letter or digit."
  }
}

variable "kms_key_arn" {
  description = "ARN of the customer-managed KMS key used for default encryption."
  type        = string

  validation {
    condition     = startswith(var.kms_key_arn, "arn:aws:kms:")
    error_message = "kms_key_arn must be a KMS key ARN."
  }
}

variable "log_bucket" {
  description = "Name of the bucket that receives server access logs."
  type        = string
}

variable "noncurrent_days" {
  description = "Days to keep noncurrent object versions before they expire."
  type        = number
  default     = 90

  validation {
    condition     = var.noncurrent_days >= 7 && var.noncurrent_days <= 3650
    error_message = "noncurrent_days must be between 7 and 3650."
  }
}

variable "tags" {
  description = "Tags added to every resource."
  type        = map(string)
  default     = {}
}

output "id" {
  description = "Bucket name."
  value       = aws_s3_bucket.this.id
}

output "arn" {
  description = "Bucket ARN."
  value       = aws_s3_bucket.this.arn
}

terraform {
  required_version = ">= 1.10.0"

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

# Runs with `tofu test`: a mocked AWS provider, so no credentials, no API calls, nothing created.
mock_provider "aws" {
  mock_data "aws_iam_policy_document" {
    defaults = {
      json = "{\"Version\":\"2012-10-17\",\"Statement\":[]}"
    }
  }
}

variables {
  name        = "acme-reports-eu"
  kms_key_arn = "arn:aws:kms:eu-west-2:111122223333:key/0d7c2f4e-1111-2222-3333-444455556666"
  log_bucket  = "acme-access-logs"
}

run "secure_defaults" {
  command = plan

  assert {
    condition     = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Enabled"
    error_message = "Versioning must be enabled."
  }

  assert {
    condition = alltrue([
      aws_s3_bucket_public_access_block.this.block_public_acls,
      aws_s3_bucket_public_access_block.this.block_public_policy,
      aws_s3_bucket_public_access_block.this.ignore_public_acls,
      aws_s3_bucket_public_access_block.this.restrict_public_buckets,
    ])
    error_message = "All four public access block settings must be true."
  }

  assert {
    condition     = one([for r in aws_s3_bucket_server_side_encryption_configuration.this.rule : one(r.apply_server_side_encryption_by_default).sse_algorithm]) == "aws:kms"
    error_message = "Default encryption must be SSE-KMS."
  }

  assert {
    condition     = aws_s3_bucket_ownership_controls.this.rule[0].object_ownership == "BucketOwnerEnforced"
    error_message = "ACLs must be disabled (BucketOwnerEnforced)."
  }

  assert {
    condition     = aws_s3_bucket_logging.this.target_prefix == "s3/acme-reports-eu/"
    error_message = "Access logs must go under s3/<name>/."
  }
}

run "rejects_bad_name" {
  command = plan

  variables {
    name = "Acme_Reports"
  }

  expect_failures = [var.name]
}

run "rejects_non_kms_key" {
  command = plan

  variables {
    kms_key_arn = "alias/aws/s3"
  }

  expect_failures = [var.kms_key_arn]
}

run "rejects_short_retention" {
  command = plan

  variables {
    noncurrent_days = 1
  }

  expect_failures = [var.noncurrent_days]
}

# Root module example: calls the bucket module and encrypts state and plan files with
# OpenTofu's built-in state encryption. The passphrase comes from a variable that is
# set in the environment (TF_VAR_state_passphrase), never written to a file.
terraform {
  required_version = ">= 1.10.0"

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

  encryption {
    key_provider "pbkdf2" "state" {
      passphrase = var.state_passphrase
    }

    method "aes_gcm" "state" {
      keys = key_provider.pbkdf2.state
    }

    state {
      method   = method.aes_gcm.state
      enforced = true
    }

    plan {
      method   = method.aes_gcm.state
      enforced = true
    }
  }
}

variable "state_passphrase" {
  description = "State encryption passphrase, at least 16 characters. Set TF_VAR_state_passphrase."
  type        = string
  sensitive   = true
}

provider "aws" {
  region = "eu-west-2"
}

module "reports" {
  source = "../../modules/s3-bucket"

  name        = "acme-reports-eu"
  kms_key_arn = "arn:aws:kms:eu-west-2:111122223333:key/0d7c2f4e-1111-2222-3333-444455556666"
  log_bucket  = "acme-access-logs"
  tags        = { service = "reports" }
}

output "bucket_arn" {
  value = module.reports.arn
}

# Repository .checkov.yaml. Findings fail the run: no soft-fail, no skip-check list.
# Accepted exceptions are inline `#checkov:skip=<ID>:<reason>` comments next to the resource,
# so the reason is reviewed in the same diff as the code.
framework:
  - terraform
compact: true
quiet: true
download-external-modules: false
skip-path:
  - .terraform