The Module Promotion Gate: Scan Before You Wire

In this module, you'll learn to:

• Take a module through the five gate steps, from development in isolation to its first apply in dev
• Build the justification package (ADR, scoped skip, README entry) that lets a finding be accepted
• Explain why the scan runs twice, and how CI makes skipping a step impossible rather than just discouraged

Before you start: read CI/CD Guardrails for how Checkov runs, and ADRs & Changelogs for the records an accepted finding needs.

Scan the module before anything depends on it

Module 06 runs Checkov on every pull request. That catches problems, but late: by the time a finding shows up in an environment's plan, the module is already wired in, other work is stacked on it, and the pressure is to add a skip and move on.

The promotion gate moves the scan earlier. No module, base or composition, may be called from environments/dev or any other environment until it has passed the gate. The module is scanned on its own, while it's still cheap to change, and the decision about each finding is made and reviewed before anything depends on it.

Develop the module in isolation

Build or change the module under modules/base/<name> or modules/composition/<name>, with its tests (Module 09). Don't add a module block to any environment yet. Until the gate is passed, nothing calls this code.

Scan only that module

checkov -d terraform/modules/base/<name> \
  --config-file terraform/.checkov.yaml

• No findings: go straight to Step 4. No justification is needed.
• Findings: go to Step 3. The module can't move on with any finding unexplained.

Fix it, or justify it

Every finding ends one of two ways:

The three parts of an accepted risk:

1. An ADR explaining why the risk is accepted, with real alternatives in its Options Considered section (Module 10).
2. A scoped inline skip on the exact resource, giving the reason and the ADR number:

resource "aws_s3_bucket" "this" {
  # checkov:skip=CKV_AWS_18:Nonprod synthetic data only (ADR-0003)
  bucket = var.bucket_name
}

1. A README entry under a ## Security Exceptions heading, so anyone reading the module sees its accepted risks without reading every resource:

Security Exceptions

**No blanket skips to get a module through.** A global `skip-check` in `.checkov.yaml` hides the finding from every module, including ones where it really matters. It's only for a platform-wide decision that already has its own ADR, like the cross-region replication example in [Module 06](06-ci-cd-security-linting-testing.html). Everything else is scoped to one resource and justified one at a time.

A second person approves

Someone other than the module's author reviews, as part of the module's pull request:

• the Checkov output: clean, or every finding justified;
• the ADR for each accepted risk, and whether its rejected options are real;
• that the README's Security Exceptions table matches the skips actually in the code.

The module code doesn't merge without this sign-off. Branch protection makes it a rule, not a habit: the module scan is a required status check, and the reviewer is a required approval.

Wire it in, and scan again

Only now may the module be referenced:

1. Add the module block to the composition, or call the composition from environments/dev/main.tf.
2. Scan again, at the composition and environment level:

checkov -d terraform/modules/composition/<composition> \
  --config-file terraform/.checkov.yaml
checkov -d terraform/environments/dev \
  --config-file terraform/.checkov.yaml

1. Put any new findings through Steps 2 to 4 again.
2. Only after this second clean or justified scan does terraform plan and apply run against dev.
3. Log the promotion in environments/dev/docs/CHANGELOG.md.

The second scan isn't a formality. Base modules can be clean on their own and still produce findings once joined: the IAM policy that grants the Glue job access to the bucket, or the security group that lets it reach a database, is written in the composition. That joining code is exactly where over-broad permissions tend to appear.

Make skipping a step impossible

A process people are trusted to follow erodes under deadline pressure. The pipeline enforces the gate instead:

In a single repository, "the module passed the gate" has a simple meaning: its code is on main, and main only accepts module code that passed the required checks. Re-scanning the whole environment tree on every environment change is the backstop. A module that somehow slipped in without its own scan is still caught before apply.

# .github/workflows/terraform-modules.yml (excerpt)
on:
  pull_request:
    paths: ["terraform/modules/**"]

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - name: Module tests
        run: |
          for dir in terraform/modules/*/*/; do
            if [ -d "$dir/tests" ]; then
              (cd "$dir" && terraform init -backend=false && terraform test)
            fi
          done
      - name: Checkov
        run: |
          pip install checkov
          checkov -d terraform/modules \
            --config-file terraform/.checkov.yaml \
            -o cli -o junitxml --output-file-path console,checkov

The whole delivery, end to end

Part 2 of this track describes one process. Here it is in a single picture, with where each step is covered:

There are two ways into this process:

• Changing or adding one module. Start at Design, and follow it down. The environments and their layers are already in place.
• Building a platform from scratch. First split it into the numbered state layers from Module 01, such as 01-networking, 03-data, and 04-compute, and bootstrap the state backend (Module 02). Then build each layer's code through this same process.

Key terms

• Promotion gate: the rule that a module is scanned, justified, and approved before any environment may call it.
• Justification package: the ADR, scoped inline skip, and README Security Exceptions entry an accepted finding needs.
• Scoped skip: a checkov:skip comment on one resource, never a global skip.
• Second scan: the composition- and environment-level scan after wiring, which catches findings in the joining code.
• Required status check: a CI check that branch protection won't let a pull request merge without.

Pop quiz

Five questions: three on the ideas in this module, and two scenarios where you apply them. The order changes every time you take it, and 4 out of 5 passes.