terraform-permcheck

README

PermCheck

Pre-apply IAM policy validation for Terraform — cloud-agnostic.

PermCheck ensures your Terraform deploy role has the permissions required by every resource in the plan, before terraform apply touches a single cloud API. It cross-references the plan's resource types against your declared IAM policies using each cloud's native schema registry.

terraform plan -out=plan.tfplan
terraform show -json plan.tfplan | terraform-permcheck validate

If your deploy role is missing kms:CreateGrant for a aws_backup_vault, you find out at plan time — not 3 failed deploys later.

Motivation

Writing least-privilege IAM policies for a Terraform deploy role is tedious and error-prone. Every new resource type needs its own set of API permissions, and those permissions are scattered across AWS/GCP/Azure docs. PermCheck automates the cross-reference:

1. Parses the terraform plan -json to extract every resource type being created, updated, or deleted.
2. Maps each terraform resource type to its cloud-native equivalent (e.g., aws_backup_vault → AWS::Backup::BackupVault).
3. Fetches the required IAM permissions from the cloud's schema registry (CloudFormation Resource Schema for AWS, Resource Manager for GCP, Resource Provider schemas for Azure).
4. Diffs against your declared IAM policy documents.
5. Fails the pipeline if any required permission is missing.

Conditional & side-effect permissions

Some permissions are only needed when a particular attribute is set. The AWS provider, for example, makes an extra kms:TagResource call when an aws_kms_key declares a tags block — a side effect that isn't part of the primary kms:CreateKey action. PermCheck reads the planned attribute values and only requires such permissions when their gating attribute is actually present, so you neither miss them (when tags are set) nor get false positives (when they aren't).

Supported clouds

Cloud	Schema source	Status
AWS	CloudFormation Resource Schema Registry	✅ MVP
GCP	Cloud Asset Inventory / IAM API	🔜 planned
Azure	Resource Provider operations API	🔜 planned

Usage

CLI

# Pipe the plan JSON directly
terraform show -json plan.tfplan | terraform-permcheck validate \
  --policy-file deploy_policy.json \
  --cloud aws

# Or point at files
terraform-permcheck validate \
  --plan-file plan.json \
  --policy-file deploy_policy.json \
  --cloud aws

Flags

Flag	Default	Description
--format	text	Output format: text or github-annotations
--exit-zero	false	Exit 0 even when gaps are found (warn, don't fail)

Exit codes

Code	Meaning
0	All permissions covered (or --exit-zero was set)
1	Permission gaps found (details printed to stderr)
2	Invalid input or configuration error

Terraform provider (planned)

data "tf-permcheck_iam_check" "deploy_role" {
  cloud             = "aws"
  plan_file         = "plan.tfplan.json"
  policy_documents  = [
    data.aws_iam_policy_document.deploy_core.json,
    data.aws_iam_policy_document.deploy_backup.json,
  ]
}

Install

go install github.com/elecnix/terraform-permcheck@latest

CI integration

Hard fail (block the PR on missing permissions)

# .github/workflows/pr-tests.yml
- name: Check IAM permissions
  run: |
    terraform plan -out=plan.tfplan
    terraform show -json plan.tfplan | terraform-permcheck validate \
      --policy-file <(terraform output -raw deploy_policy) \
      --cloud aws

Soft warn (annotate the PR diff without failing the check)

- name: Check IAM permissions
  run: |
    terraform plan -out=plan.tfplan
    terraform show -json plan.tfplan | terraform-permcheck validate \
      --policy-file <(terraform output -raw deploy_policy) \
      --cloud aws \
      --format github-annotations \
      --exit-zero

With --format github-annotations, each missing permission group produces a ::warning:: workflow command that GitHub Actions surfaces as a ⚠️ annotation in the PR diff. --exit-zero ensures the step itself succeeds so the check passes green while surfacing warnings.

License

MIT — see LICENSE.

Documentation

Overview

terraform-permcheck validates that a terraform deploy role has sufficient IAM permissions for every resource in a terraform plan.

Usage:

terraform show -json plan.tfplan | terraform-permcheck validate --policy-file deploy_policy.json --cloud aws

terraform-permcheck validate --plan-file plan.json --policy-file deploy_policy.json --cloud aws

terraform show -json plan.tfplan | terraform-permcheck validate --policy-from-plan-output deploy_policy_json --cloud aws

terraform-permcheck validate --plan-file plan.json --policy-from-state-output deploy_policy_json --state-file state.json --cloud aws
terraform-permcheck validate --terraform-root ./terraform --policy-file deploy_policy.json --cloud aws

GitHub Actions annotations (warn, don't fail):

terraform show -json plan.tfplan | terraform-permcheck validate \
  --policy-file deploy_policy.json --cloud aws \
  --format github-annotations --exit-zero

# With file/line annotations (inline in the PR "Files changed" tab):
terraform show -json plan.tfplan | terraform-permcheck validate \
  --policy-file deploy_policy.json --cloud aws \
  --format github-annotations --terraform-root . --exit-zero