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 runshashicorp/awsX.Y.Z. - All settings sit in a
compliance {}block insideprovider "aws" {}; the tables below name theCOMPLIANCETF_*variable of each setting that has one. - Modes:
soft_fail(default) andhard_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 to | Set |
|---|---|
Make a violated deny control fail the plan | enforcement_mode = "hard_fail", or COMPLIANCETF_ENFORCEMENT_MODE=hard_fail in CI |
| Change the lines each finding prints | COMPLIANCETF_DIAGNOSTICS |
| Write the evidence records somewhere else | evidence_dir, or COMPLIANCETF_EVIDENCE_DIR |
| Make data source controls follow the mode | data_sources = "deny", or COMPLIANCETF_DATA_SOURCES=deny |
| Run without internet access | COMPLIANCETF_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
| Attribute | Default | Variable | Description |
|---|---|---|---|
enforcement_mode | "soft_fail" | COMPLIANCETF_ENFORCEMENT_MODE; the stricter one wins | soft_fail or hard_fail. See Enforcement modes |
control_profile | "cis" | Only cis, the built-in bundle | |
control_bundle_path | "" | COMPLIANCETF_BUNDLE_PATH wins | A signed bundle archive for air-gapped runs |
evidence_dir | ".terraform/compliancetf/evidence" | COMPLIANCETF_EVIDENCE_DIR wins | Directory of the evidence records |
data_sources | "advisory" | COMPLIANCETF_DATA_SOURCES; the stricter one wins | advisory: 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_ENVIRONMENT | Deployment environment name |
Enforcement modes
| Value | Effect |
|---|---|
soft_fail (default) | A violated deny control warns |
hard_fail | A 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:
advisoryis ignored. The provider warnsenforcement_mode advisory is below the default soft_fail and has no effect, and the mode is at leastsoft_fail.grandfatherneeds signed organization baselines, which are not available. Without them it blocks at apply likehard_fail.
Environment variables
| Name | Meaning |
|---|---|
COMPLIANCETF_ENFORCEMENT_MODE | Raises the mode for every configuration the run plans or applies |
COMPLIANCETF_DIAGNOSTICS | Lines printed after each finding; see Diagnostics |
COMPLIANCETF_EVIDENCE_DIR | Directory of the evidence records; wins over evidence_dir |
COMPLIANCETF_BUNDLE_PATH | Signed bundle archive; wins over control_bundle_path |
COMPLIANCETF_DATA_SOURCES | advisory or deny; the stricter of it and data_sources wins |
COMPLIANCETF_ENVIRONMENT | Deployment environment name |
COMPLIANCETF_UPSTREAM_PATH | Path to the hashicorp/aws binary, for air-gapped installs. It must be the pinned version and match the pinned checksum |
COMPLIANCETF_RUN_ID | Run 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:
| Field | Line | Printed by default |
|---|---|---|
fix | Fix: <how to fix it>, when the control has one | yes |
docs | Docs: https://compliance.tf/docs/controls/aws/<control id>/ | yes |
severity | Severity: <severity> | no |
mode | Mode: <enforcement mode> | no |
stage | Stage: <stage>, and Type: <data source type> for data sources | no |
frameworks | Frameworks: <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.
| Setting | What happens |
|---|---|
org_id without COMPLIANCETF_TOKEN | No 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_TOKEN | The provider requests the profile from compliance.tf, the request is refused, and the provider configuration fails, so every plan stops |
exceptions_file | Ignored 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 tfplanPrint framework references in the log
export COMPLIANCETF_DIAGNOSTICS=fix,docs,frameworks
terraform planExample 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.
| Control | Resource types | Action | Severity |
|---|---|---|---|
rds_db_instance_encryption_at_rest_enabled | aws_db_instance | deny | critical |
rds_db_instance_prohibit_public_access | aws_db_instance | deny | critical |
rds_db_instance_backup_retention_period_less_than_7 | aws_db_instance, aws_rds_cluster | deny | high |
rds_db_instance_deletion_protection_enabled | aws_db_instance | warn | medium |
rds_db_cluster_encryption_at_rest_enabled | aws_rds_cluster | deny | critical |
rds_db_cluster_deletion_protection_enabled | aws_rds_cluster | warn | medium |
ebs_attached_volume_encryption_enabled | aws_ebs_volume | deny | critical |
efs_file_system_encrypt_data_at_rest | aws_efs_file_system | deny | critical |
efs_file_system_encrypted_with_cmk | aws_efs_file_system | warn | medium |
elasticache_replication_group_encryption_at_rest_enabled | aws_elasticache_replication_group | deny | critical |
elasticache_replication_group_encryption_in_transit_enabled | aws_elasticache_replication_group | deny | critical |
redshift_cluster_kms_enabled | aws_redshift_cluster | deny | critical |
redshift_cluster_prohibit_public_access | aws_redshift_cluster | deny | critical |
elb_application_network_listener_uses_secure_protocol | aws_lb_listener | deny | critical |
s3_bucket_restrict_public_read_access | aws_s3_bucket | deny | critical |
s3_bucket_restrict_public_write_access | aws_s3_bucket | deny | critical |
vpc_security_group_remote_administration_ipv4 | aws_security_group, aws_security_group_rule, aws_vpc_security_group_ingress_rule | deny | critical |
vpc_security_group_remote_administration_ipv6 | aws_security_group, aws_security_group_rule, aws_vpc_security_group_ingress_rule | deny | critical |
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/awsbinary required. The provider finds the realhashicorp/awslocally or downloads it on first use. Only the exact pinned version is used, and its sha256 must match the pin. For air-gapped installs, setCOMPLIANCETF_UPSTREAM_PATH.- Protocol 5 only. The provider serves plugin protocol 5, the protocol
hashicorp/awsspeaks. - 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 (
-replaceor 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>ortofu 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 mismatchon a module call. Aprovidersargument maps the module'sawsto a configuration of a different provider type. See Which modules are checked.control_predicateat configure. A bundle built for 0.1.x writes a control as apredicate. Rewrite each check as a CELexpr, 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.