Validate templates with Guard

AWS CloudFormation Guard (cfn-guard) is a policy-as-code tool. You write rules in the Guard language that describe required or prohibited configurations, and then Guard checks JSON or YAML data against those rules. For example, you can require every Amazon S3 bucket in a template to use encryption, or block security group rules that open port 22 to the internet.

Guard works with any JSON or YAML data. In addition to CloudFormation templates, you can check CloudFormation change sets and AWS Config configuration items. This topic focuses on checking templates.

For release notes and the complete command reference, see Guard on GitHub. For the complete language reference, see the Guard User Guide.

For the limitations of local validation and steps to take before deployment, see Understand validation scope.

Install Guard

On macOS, install Guard with Homebrew:

brew install cloudformation-guard

On Linux or macOS, you can instead run the installation script. The script installs the latest release to ~/.guard/bin. Add that directory to your PATH after the script finishes.

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/aws-cloudformation/cloudformation-guard/main/install-guard.sh | sh

If you have a Rust toolchain, you can also install Guard with Cargo:

cargo install cfn-guard

To confirm the installation, print the installed version:

cfn-guard --version

For Windows installation, a Docker image, and release verification, see Setting up Guard.

Understand the Guard language

Now that Guard is installed, you can start writing rules. Guard rules are built from the following parts:

For the complete syntax, see Writing Guard rules.

Write a rule

Save rules in a file with the .guard extension. The following example in rules.guard requires every Amazon S3 bucket in a template to specify bucket encryption and to block public access:

let s3_buckets = Resources.*[ Type == 'AWS::S3::Bucket' ]

rule S3_BUCKET_ENCRYPTED when %s3_buckets !empty {
  %s3_buckets.Properties.BucketEncryption exists
  <<
    Violation: S3 buckets must specify BucketEncryption.
    Fix: Add a BucketEncryption property with ServerSideEncryptionConfiguration.
  >>
}

rule S3_BUCKET_PUBLIC_ACCESS_BLOCKED when %s3_buckets !empty {
  %s3_buckets.Properties.PublicAccessBlockConfiguration {
    BlockPublicAcls == true
    BlockPublicPolicy == true
    IgnorePublicAcls == true
    RestrictPublicBuckets == true
  }
}

The first line stores every Amazon S3 bucket in the s3_buckets variable. Each rule runs only when the template contains at least one bucket. The first rule checks that the BucketEncryption property exists and includes a message that Guard prints when the check fails. The second rule checks four properties inside PublicAccessBlockConfiguration. Because the clauses are on separate lines, all four must pass.

You can keep many rules in one file, or split rules across files by topic, such as one file for storage rules and another for network rules. Guard evaluates every .guard file in a directory when you pass the directory to a command.

Validate a template

Pass the rule file to --rules and the template to --data. Add --type CFNTemplate so that Guard reports findings by resource logical ID.

cfn-guard validate --rules rules.guard --data template.yaml --type CFNTemplate

When the template passes, Guard prints a PASS status and returns exit code 0. When a rule fails, Guard lists the failed rules and, for each noncompliant resource, the check that failed, the property path, and the reason. The output for a template whose bucket is missing BucketEncryption starts like the following:

template.yaml Status = FAIL
FAILED rules
rules.guard/S3_BUCKET_ENCRYPTED    FAIL
---
Evaluating data template.yaml against rules rules.guard
Number of non-compliant resources 1
Resource = MyBucket {
  Type      = AWS::S3::Bucket
  Rule = S3_BUCKET_ENCRYPTED {
    ...

Guard returns exit code 19 when one or more rules fail and 5 when it can't parse a rule or data file. You can use these exit codes to stop an automated build.

The following options are useful when you validate templates:

For all options, see validate in the Guard User Guide.

Test your rules

Before you use a rule in an automated workflow, test it with the built-in unit testing support. A test file lists sample inputs and the result that you expect for each rule: PASS, FAIL, or SKIP. The following example in rules_tests.yaml tests the S3_BUCKET_ENCRYPTED rule from the previous example:

---
- input:
    Resources: {}
  expectations:
    rules:
      S3_BUCKET_ENCRYPTED: SKIP
- input:
    Resources:
      MyBucket:
        Type: AWS::S3::Bucket
        Properties: {}
  expectations:
    rules:
      S3_BUCKET_ENCRYPTED: FAIL
- input:
    Resources:
      MyBucket:
        Type: AWS::S3::Bucket
        Properties:
          BucketEncryption:
            ServerSideEncryptionConfiguration:
              - ServerSideEncryptionByDefault:
                  SSEAlgorithm: aws:kms
  expectations:
    rules:
      S3_BUCKET_ENCRYPTED: PASS

Run the tests with the test command:

cfn-guard test --rules-file rules.guard --test-data rules_tests.yaml

Guard prints PASS or FAIL for each expectation and returns exit code 7 when any expectation fails. For more information, see Testing Guard rules.

Generate rules from a template

To get started quickly, you can generate rules from a template that already meets your requirements. The rulegen command reads the template and writes a rule for each resource type that requires the property values found in the template:

cfn-guard rulegen --template template.yaml --output generated.guard

Review the generated file and keep only the checks that represent your policy. Generated rules are a starting point and often require the exact values in the source template, which might be too strict for other templates.

Add Guard to your workflow

You can run Guard in the following places:

For ready-to-use rules that cover common security and compliance controls, see the AWS Guard Rules Registry on GitHub.