Sign in
Menu
Sign up
Docs

Reference

Every setting, environment variable, built-in control and known limitation of the compliance.tf provider for AWS. It is for engineers who configure the provider and for security engineers who check what it enforces. For the steps, start at the Quickstart. The exact names and values of one release are in docs/reference.md at that release's tag in the provider repository; where the two differ, that file is right for its release.

  • Source address: registry.compliance.tf/compliancetf/aws. Version X.Y.Z runs hashicorp/aws X.Y.Z.
  • All settings sit in a compliance {} block inside provider "aws" {}; the tables below name the COMPLIANCETF_* variable of each setting that has one.
  • Modes: soft_fail (default) and hard_fail. The stricter of the block and the variable wins.
  • Without an organization, the provider applies its built-in CIS bundle and nothing else.

Which one to use

You want toSet
Make a violated deny control fail the planenforcement_mode = "hard_fail", or COMPLIANCETF_ENFORCEMENT_MODE=hard_fail in CI
Change the lines each finding printsCOMPLIANCETF_DIAGNOSTICS
Write the evidence records somewhere elseevidence_dir, or COMPLIANCETF_EVIDENCE_DIR
Make data source controls follow the modedata_sources = "deny", or COMPLIANCETF_DATA_SOURCES=deny
Run without internet accessCOMPLIANCETF_UPSTREAM_PATH for hashicorp/aws, and control_bundle_path for a signed bundle archive

Syntax

terraform {
  required_providers {
    aws = {
      source  = "registry.compliance.tf/compliancetf/aws"
      version = "6.70.0"
    }
  }
}

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

  compliance {
    enforcement_mode = "hard_fail"
    control_profile  = "cis"
  }
}

Every other argument of provider "aws" is passed to hashicorp/aws unchanged.

Parameters

The compliance block

AttributeDefaultVariableDescription
enforcement_mode"soft_fail"COMPLIANCETF_ENFORCEMENT_MODE; the stricter one winssoft_fail or hard_fail. See Enforcement modes
control_profile"cis"Only cis, the built-in bundle
control_bundle_path""COMPLIANCETF_BUNDLE_PATH winsA signed bundle archive for air-gapped runs
evidence_dir".terraform/compliancetf/evidence"COMPLIANCETF_EVIDENCE_DIR winsDirectory of the evidence records
data_sources"advisory"COMPLIANCETF_DATA_SOURCES; the stricter one winsadvisory: every data source control only warns. deny: a deny data source control follows the enforcement mode. This is not the advisory enforcement mode
environment""COMPLIANCETF_ENVIRONMENTDeployment environment name

Enforcement modes

ValueEffect
soft_fail (default)A violated deny control warns
hard_failA violated deny control fails the plan, and the apply is not forwarded

A violated warn control warns in every mode. The rules on top of these, for unchanged resources, unknown values and the stages after apply, are under How the modes decide. A control that cannot be evaluated counts as a failure.

The provider also accepts advisory and grandfather. Use soft_fail or hard_fail instead:

  • advisory is ignored. The provider warns enforcement_mode advisory is below the default soft_fail and has no effect, and the mode is at least soft_fail.
  • grandfather needs signed organization baselines, which are not available. Without them it blocks at apply like hard_fail.

Environment variables

NameMeaning
COMPLIANCETF_ENFORCEMENT_MODERaises the mode for every configuration the run plans or applies
COMPLIANCETF_DIAGNOSTICSLines printed after each finding; see Diagnostics
COMPLIANCETF_EVIDENCE_DIRDirectory of the evidence records; wins over evidence_dir
COMPLIANCETF_BUNDLE_PATHSigned bundle archive; wins over control_bundle_path
COMPLIANCETF_DATA_SOURCESadvisory or deny; the stricter of it and data_sources wins
COMPLIANCETF_ENVIRONMENTDeployment environment name
COMPLIANCETF_UPSTREAM_PATHPath to the hashicorp/aws binary, for air-gapped installs. It must be the pinned version and match the pinned checksum
COMPLIANCETF_RUN_IDRun id written into the evidence records and used as their directory name. Without it the provider takes the CI run id (GitHub Actions, HCP Terraform, Spacelift, GitLab), else a random id

COMPLIANCETF_* variables are not passed to hashicorp/aws. The variables for anti-rollback state, organization mode and test builds are listed in the provider reference on GitHub.

The verified hashicorp/aws copy and its schema are cached under compliancetf in the user cache directory; Keep the caches has the paths and the ownership rules. COMPLIANCETF_CACHE_DIR does not move it.

Diagnostics

A finding prints [<control id>] <message>, the source snippet, then these lines in this order:

FieldLinePrinted by default
fixFix: <how to fix it>, when the control has oneyes
docsDocs: https://compliance.tf/docs/controls/aws/<control id>/yes
severitySeverity: <severity>no
modeMode: <enforcement mode>no
stageStage: <stage>, and Type: <data source type> for data sourcesno
frameworksFrameworks: <framework references>no

COMPLIANCETF_DIAGNOSTICS takes default (unset or empty), minimal (fix only), full (all), or a comma list of field names such as fix,docs,frameworks. Unknown names are ignored with one warning. Lines that explain the situation, such as a value unknown until apply, always print. The setting changes only what is shown: results, evidence and exit codes stay the same.

Settings that are not available

These settings serve organization mode, which needs a signed organization profile, and compliance.tf does not issue them: org_id (COMPLIANCETF_ORG_ID), COMPLIANCETF_TOKEN, profile_path, exceptions_file, exception_grants_dir, baseline_file, COMPLIANCETF_OFFLINE, COMPLIANCETF_CACHE_DIR and COMPLIANCETF_BASELINE_KEY_FILE. Leave them unset.

SettingWhat happens
org_id without COMPLIANCETF_TOKENNo request is sent. The provider warns Org profile for <org> unavailable: hard_fail floor applied (no profile found)., and every deny control runs at least in hard_fail
org_id with COMPLIANCETF_TOKENThe provider requests the profile from compliance.tf, the request is refused, and the provider configuration fails, so every plan stops
exceptions_fileIgnored with a warning

Examples

Fail the plan in CI only

export COMPLIANCETF_ENFORCEMENT_MODE=hard_fail
terraform plan -input=false -out=tfplan
terraform apply -input=false tfplan
export COMPLIANCETF_DIAGNOSTICS=fix,docs,frameworks
terraform plan

Example configurations

The provider repository has complete configurations with their expected output: basic (passes), cis-complete (every checked resource type, configured to pass), soft-fail (warnings only) and hard-fail (errors and a warning). Each README lists the expected findings.

CIS controls

The built-in CIS bundle (cis-aws) holds these controls. Control ids follow the compliance.tf controls catalog. No CIS violation can be waived today; see Settings that are not available.

ControlResource typesActionSeverity
rds_db_instance_encryption_at_rest_enabledaws_db_instancedenycritical
rds_db_instance_prohibit_public_accessaws_db_instancedenycritical
rds_db_instance_backup_retention_period_less_than_7aws_db_instance, aws_rds_clusterdenyhigh
rds_db_instance_deletion_protection_enabledaws_db_instancewarnmedium
rds_db_cluster_encryption_at_rest_enabledaws_rds_clusterdenycritical
rds_db_cluster_deletion_protection_enabledaws_rds_clusterwarnmedium
ebs_attached_volume_encryption_enabledaws_ebs_volumedenycritical
efs_file_system_encrypt_data_at_restaws_efs_file_systemdenycritical
efs_file_system_encrypted_with_cmkaws_efs_file_systemwarnmedium
elasticache_replication_group_encryption_at_rest_enabledaws_elasticache_replication_groupdenycritical
elasticache_replication_group_encryption_in_transit_enabledaws_elasticache_replication_groupdenycritical
redshift_cluster_kms_enabledaws_redshift_clusterdenycritical
redshift_cluster_prohibit_public_accessaws_redshift_clusterdenycritical
elb_application_network_listener_uses_secure_protocolaws_lb_listenerdenycritical
s3_bucket_restrict_public_read_accessaws_s3_bucketdenycritical
s3_bucket_restrict_public_write_accessaws_s3_bucketdenycritical
vpc_security_group_remote_administration_ipv4aws_security_group, aws_security_group_rule, aws_vpc_security_group_ingress_ruledenycritical
vpc_security_group_remote_administration_ipv6aws_security_group, aws_security_group_rule, aws_vpc_security_group_ingress_ruledenycritical

The vpc_security_group_remote_administration controls deny ingress from 0.0.0.0/0 (IPv4) and ::/0 (IPv6) on any rule whose port range covers 22 or 3389, or whose protocol is -1. A prefix list source on such a rule cannot be evaluated at plan and counts as a failure. They have no page in the controls catalog yet.

Other resource types are not checked. Resources in child modules that require hashicorp/aws are not checked either; see Which modules are checked.

Versions

compliancetf/aws X.Y.Z runs hashicorp/aws X.Y.Z, so a configuration keeps its version constraint and lock file workflow. Fixes to the compliance.tf layer alone ship as prereleases X.Y.Z-compliancetf.N, and betas as X.Y.Z-beta.N. Terraform never selects a prerelease from a range constraint, so to use one, pin it exactly:

aws = {
  source  = "registry.compliance.tf/compliancetf/aws"
  version = "6.70.0-compliancetf.1"
}

Release notes are in the CHANGELOG.

Errors and limits

  • hashicorp/aws binary required. The provider finds the real hashicorp/aws locally or downloads it on first use. Only the exact pinned version is used, and its sha256 must match the pin. For air-gapped installs, set COMPLIANCETF_UPSTREAM_PATH.
  • Protocol 5 only. The provider serves plugin protocol 5, the protocol hashicorp/aws speaks.
  • No remediation. The provider warns or denies; it never changes a value.
  • Replacing a resource with an identity needs Terraform 1.16.6 or later. Terraform 1.12 to 1.16.5 and OpenTofu (checked with 1.13) do not send the prior resource identity when they destroy the old object of a replace (-replace or a forced replacement). The provider cannot confirm which object is destroyed and blocks that apply. Use Terraform 1.16.6 or later, or taint the object first and apply again (terraform taint <address> or tofu taint <address>): a tainted replace destroys the object by resource id and is not blocked. Plain destroys, and replaces of resource types without an identity, are not affected.
  • Provider type mismatch on a module call. A providers argument maps the module's aws to a configuration of a different provider type. See Which modules are checked.
  • control_predicate at configure. A bundle built for 0.1.x writes a control as a predicate. Rewrite each check as a CEL expr, then rebuild and re-sign the bundle.

The full list, including saved-plan limits on older Terraform versions, is in the provider reference on GitHub.

On this page

Ask AI about this

Help improve this page