tf-best-practices

Files (39)

• .gitignore
• SKILL.md
• vpc.tf · fixtures/terraform-policy/bad-db-sg-public-quoted-port/
• vpc.tf · fixtures/terraform-policy/bad-db-sg-public/
• cache.tf · fixtures/terraform-policy/bad-elasticache-cluster-redis-unencrypted/
• cache.tf · fixtures/terraform-policy/bad-elasticache-unencrypted/
• cache.tf · fixtures/terraform-policy/bad-heroku-eb-elasticache/
• compute.tf · fixtures/terraform-policy/bad-http-forward/
• main.tf · fixtures/terraform-policy/bad-rds-public-brace-in-comment/
• main.tf · fixtures/terraform-policy/bad-rds-public-closing-brace/
• rds.tf · fixtures/terraform-policy/bad-rds-public-interpolated-brace/
• database.tf · fixtures/terraform-policy/bad-rds-public-unencrypted/
• vpc.tf · fixtures/terraform-policy/bad-sg-public-ipv6/
• vpc.tf · fixtures/terraform-policy/bad-sg-public-ssh/
• security.tf · fixtures/terraform-policy/bad-wildcard-iam-listform/
• security.tf · fixtures/terraform-policy/bad-wildcard-iam/
• vpc.tf · fixtures/terraform-policy/good-db-sg-scoped/
• cache.tf · fixtures/terraform-policy/good-elasticache-cluster-memcached/
• cache.tf · fixtures/terraform-policy/good-elasticache-cluster-redis-encrypted/
• cache.tf · fixtures/terraform-policy/good-elasticache-encrypted/
• pipeline.tf · fixtures/terraform-policy/good-heroku-eb-codepipeline/
• compute.tf · fixtures/terraform-policy/good-heroku-eb-loadbalanced/
• database.tf · fixtures/terraform-policy/good-heroku-eb-loadbalanced/
• security.tf · fixtures/terraform-policy/good-heroku-eb-loadbalanced/
• compute.tf · fixtures/terraform-policy/good-heroku-eb-only/
• compute.tf · fixtures/terraform-policy/good-heroku-eb-singleinstance/
• compute.tf · fixtures/terraform-policy/good-https-redirect/
• security.tf · fixtures/terraform-policy/good-iam-scoped-list/
• compute.tf · fixtures/terraform-policy/good-internet-nlb/
• compute.tf · fixtures/terraform-policy/good-quoted-port-https/
• database.tf · fixtures/terraform-policy/good-rds-private-encrypted/
• security.tf · fixtures/terraform-policy/good-scoped-iam/
• vpc.tf · fixtures/terraform-policy/good-sg-ipv6-scoped/
• vpc.tf · fixtures/terraform-policy/good-sg-public-webapp/
• compute.tf · fixtures/terraform-policy/internal-alb-only/
• security-posture-rules.md · references/
• terraform-validation.md · references/
• test_validate_terraform_policy.py · scripts/
• validate-terraform-policy.py · scripts/

SKILL.md (first lines)

# tf-best-practices — Generated-IaC posture rules + read-only policy gate

A **shared authoring guide and verdict producer**, not a workflow. It answers two
questions for a phase that generates AWS Terraform:

1. **Before writing** — "what security posture must the generated `terraform/` follow?"
   (the posture rules + the `baseline.tf` account-hardening spec)
2. **After writing** — "does the generated `terraform/` pass policy?" (a deterministic,
   **read-only** verdict + a machine-readable report)

## Routing — load the part that matches your context

This skill is entered at two touchpoints in the caller's Generate flow, with the caller's
own terraform-authoring work in between. **The caller states which touchpoint it is at when it
loads this skill**, and reads the corresponding part:

| Caller context                                              | Load                                                                                                      | Why                                                                                               |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **About to author `terraform/`** (before writing)           | Part 1 → [`references/security-posture-rules.md`](references/security-posture-rules.md)                   | The "what to emit" AWS authoring rules (gate-enforced + authoring-only + compliance-conditional). |
| **`terraform/` written, ready to validate** (after writing) | Part 2 → [`references/terraform-validation.md`](references/terraform-validation.md) + run the gate script | The `fmt → init → validate → policy` protocol and the read-only verdict.                          |

Everything this skill states is **source-cloud-agnostic** (pure AWS Terraform). Any GCP/Heroku
detection or artifact reading is the caller's job; where a rule needs a caller-known fact (e.g.
declared compliance frameworks), the caller passes it as a **caller-context signal** — see
`references/security-posture-rules.md` § _Caller-context signals_.

## Boundary (read this first)

This unit is a **verdict producer, never a mutator**. Its entire write surface is the
JSON verdict it is asked to emit. Specifically it **MUST NOT**:

- edit, format, or rewrite any `.tf` file (the caller owns remediation),
- read or write `.phase-status.json` or any run-state file (interpreter-owned),
- decide whether a phase may complete, or prompt the user (caller policy).

The caller (a migration skill's Generate phase) owns: the fix-and-retry loop that edits
the `.tf` it generated, `terraform fmt` auto-apply, the retry/skip/abort prompt, the
Phase Completion gate, and every `.phase-status.json` write. See the consuming skill's
generate phase for how the verdict feeds those decisions.

> **Consumers:** `gcp-to-aws` (prose Generate) and `heroku-to-aws` (DSL Generate). The
> contract is source-agnostic; each caller wires the two touchpoints in its own Generate
> idiom — gcp-to-aws as prose steps, heroku-to-aws as a fragment step plus a fail-closed
> `_postconditions` assert enforced by the interpreter.

## Part 1 — Authoring posture (load before writing `terraform/`)

Emit generated Terraform that satisfies the posture in
[`references/security-posture-rules.md`](references/security-posture-rules.md).

These are the "what good AWS Terraform looks like" rules. Following them makes the Part 2 gate
pass by construction. This unit does not read the caller's artifacts — it consumes only
caller-context signals the caller passes in.

> **Scope.** `security-posture-rules.md` covers, in three tiers:
>
> - **Gate-enforced** (Part 2 verifies statically): ALB TLS, no-public-database, RDS +
>   ElastiCache encryption-at-rest, no-public-DB-port ingress, no-public admin/datastore-port
>   ingress, no-wildcard-IAM.
> - **Authoring-only** (not gate-checkable, still required): `deletion_protection`,
>   master-password-via-Secrets-Manager, S3 hardening, Fargate/EKS/ECR settings, private-subnet
>   placement, backups, baseline monitoring.
> - **Compliance-conditional** (emitted when the caller declares `soc2`/`pci`/`hipaa`/`fedramp`):
>   VPC flow logs, S3 access logging, secret rotation, customer-managed KMS.
>
> Still the **caller's** own generation concern (candidates to migrate here later): the
> account-hardening `baseline.tf` layer (CloudTrail, GuardDuty, Config, Security Hub).

## Part 2 — Policy gate (run after writing `terraform/`)

Run the read-only checker against the generated directory. Resolve the script path relative to
the plugin root (`$PLUGIN_ROOT/skills/tf-best-practices/scripts/...`), the same convention the
plugin uses for its other scripts:

```bash
python3 "$PLUGIN_ROOT/skills/tf-best-practices/scripts/validate-terraform-policy.py" "$TERRAFORM_DIR" --json "$VERDICT_PATH"
```

- `$TERRAFORM_DIR` — **required, caller-supplied**: the generated `terraform/` directory
  (e.g. `$MIGRATION_DIR/terraform`). This skill never defaults or discovers it — the caller
  always passes the path it wrote Terraform to.
- `--json $VERDICT_PATH` — optional; writes a machine-readable verdict the caller can merge
  into its own `validation-report.json`.

The policy check is one stage of a larger validation flow (`fmt → init → validate → policy`).
The full protocol — including offline-fallback behavior and how the policy verdict maps into a
`validation-report.json` — is documented in
[`references/terraform-validation.md`](references/terraform-validation.md). That protocol is
descriptive: the **caller** owns the fmt/init/validate execution, the fix-and-retry loop, and
the report write; this unit contributes only the read-only policy stage + verdict shape.

### Exit codes → caller action

| Exit | stdout        | Meaning            | Caller does                                                                     |
| ---- | ------------- | ------------------ | ------------------------------------------------------------------------------- |
| `0`  | `POLICY_OK`   | posture satisfied  | proceed                                                                         |
| `1`  | `POLICY_FAIL` | violations present | read `violations[]`, edit the named `.tf` sites, re-run (caller's retry budget) |
| `2`  | (usage error) | bad path / IO      | surface to user; do not treat as pass                                           |

### Verdict shape (`--json`)

```json
{
  "check": "policy",
  "policy_status": "POLICY_OK | POLICY_FAIL",
  "violations": [
    {
      "check": "policy",
      "rule": "alb_https_listener | alb_http_redirect | no_tf_files",
      "file": "compute.tf",
      "line": 7,
      "severity": "error",
      "summary": "human-readable violation",
      "fix_hint": "concrete remediation the caller can apply"
    }
  ]
}
```

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws