Extend your pre-commit hooks with AWS CloudFormation Guard

Git hooks are scripts that extend Git functionality when certain events and actions occur during code development. Developer teams often use Git hooks to perform quality checks before they commit their code changes. For example, see the blog post Use Git pre-commit hooks to avoid AWS CloudFormation errors for a description of how the AWS Integration and Automation team uses various pre-commit hooks to help reduce effort and errors when they build AWS Quick Starts.

This blog post shows you how to extend your Git hooks to validate your AWS CloudFormation templates against policy-as-code rules by using AWS CloudFormation Guard. This can help you verify that your code follows organizational best practices for security, compliance, and more by preventing you from commit changes that fail validation rules.

We will also provide patterns you can use to centrally maintain a list of rules that security teams can use to roll out new security best practices across an organization. You will learn how to configure a pre-commit framework by using an example repository while you store Guard rules in both a central Amazon Simple Storage Service (Amazon S3) bucket or in versioned code repositories (such as AWS CodeCommit, GitHub, Bitbucket, or GitLab).

Prerequisites

To complete the steps in this blog post, first perform the following installations.

1. Install AWS Command Line Interface (AWS CLI).
2. Install the Git CLI.
3. Install the pre-commit framework by running the following command.
   pip install pre-commit
4. Install the Rust programming language by following these instructions.
5. (Windows only) Install the version of Microsoft Visual C++ Build Tools 2019 that provides just the Visual C++ build tools. 

Solution walkthrough

In this section, we walk you through an exercise to extend a Java service on an Amazon EKS example repository with Git hooks by using AWS CloudFormation Guard. You can choose to upload your Guard rules in either a separate GitHub repository or your own S3 bucket.

First, download the sample repository that you will add the pre-commit framework to.

To clone the test repository

• Clone the repo to a local directory by running the following command in your local terminal.

  git clone https://github.com/aws-samples/amazon-eks-example-for-stateful-java-service.git

Next, create Guard rules that reflect the organization’s policy-as-code best practices and store them in an S3 bucket.

To set up an S3 bucket with your Guard rules

1. Create an S3 bucket by running the following command in the AWS CLI.

   aws s3 mb s3://<account-id>-cfn-guard-rules --region <aws-region>

   where <account-id> is the ID of the AWS account you’re using and <aws-region> is the AWS Region you want to use.

2. (Optional) Alternatively, you can follow the Getting started with Amazon S3 tutorial to create the bucket and upload the object (as described in step 4 that follows) by using the AWS Management Console.

   When you store your Guard rules in an S3 bucket, you can make the rules accessible to other member accounts in your organization by using the aws:PrincipalOrgID condition and setting the value to your organization ID in the bucket policy.

3. Create a file that contains a Guard rule named rules.guard, with the following content.

   let eks_cluster = Resources.* [ Type == 'AWS::EKS::Cluster' ]
   rule eks_public_disallowed when %eks_cluster !empty {
         %eks_cluster.Properties.ResourcesVpcConfig.EndpointPublicAccess == false
   }

   This rule will verify that public endpoints are disabled by checking that resources that are created by using the AWS::EKS::Cluster resource type have the EndpointPublicAccess property set to false. For more information about authoring your own rules using Guard domain-specific language (DSL), see Introducing AWS CloudFormation Guard 2.0.

4. Upload the rule set to your S3 bucket by running the following command in the AWS CLI.

   aws s3 cp rules.guard s3://<account-id>-cfn-guard-rules/rules/rules.guard

In the next step, you will set up the pre-commit framework in the repository to run CloudFormation Guard against code changes.

To configure your pre-commit hook to use Guard

1. Run the following command to create a new branch where you will test your changes.
   git checkout -b feature/guard-hook
2. Navigate to the root directory of the project that you cloned earlier and create a .pre-commit-config.yaml file with the following configuration.

   repos:
   -   repo: local
       hooks:
       -   id: cfn-guard-rules
           name: Rules for AWS
           description: Download Organization rules
           entry: aws s3 cp --recursive s3://<account-id>-cfn-guard-rules/rules  guard-rules/org-rules/
           language: system
           pass_filenames: false
       -   id: cfn-guard
           name: AWS CloudFormation Guard
           description: Validate code against your Guard rules
           entry: cfn-guard validate -r guard-rules -d "cloudformation"
           language: rust
           additional_dependencies:
             - cli:cfn-guard
           files: \.(json|yaml|yml|template\.json|template)$
           pass_filenames: false

   You will need to replace the <account-id> placeholder value with the AWS account ID you entered in the To set up an S3 bucket with your Guard rules procedure.

   This hook configuration uses local pre-commit hooks to download the latest version of Guard rules from the bucket you created previously. This allows you to set up a centralized set of Guard rules across your organization.

   Alternatively, you can create and use a code repository such as GitHub, AWS CodeCommit, or Bitbucket to keep your rules in version control. To do so, replace the command in the Download Organization rules step of the .pre-commit-config.yaml file with:

   bash -c ‘if [ -d guard-rules/org-rules ]; then cd guard-rules/org-rules && git pull; else git clone <guard-rules-repository-target> guard-rules/org-rules; fi’

   Where <guard-rules-repository-target> is the HTTPS or SSH URL of your repository. This command will clone or pull the latest rules from your Git repo by using your Git credentials.

   The hook will also install Guard as an additional dependency by using a Rust hook. Using Guard, it will run the code changes in the repository directory against the downloaded rule set. When misconfigurations are detected, the hook stops the commit.

   You can further extend your organization rules with your own Guard rules by adding them to the cfn-guard-rules folder. You should commit these rules in your repository and add cfn-guard-rules/org-rules/* to your .gitignore file.

3. Run a pre-commit install command to install the hooks you just created.

Finally, test that the pre-commit’s Guard hook fails commits of code changes that do not follow organizational best practices.

To test pre-commit hooks

1. Add EndpointPublicAccess: true in cloudformation/eks.template.yaml, as shown following. This describes the test-only intent (meaning that you want to detect and flag errors in your rule) of adding public access to the Amazon Elastic Kubernetes Service (Amazon EKS) cluster.

     EKSCluster:
       Type: AWS::EKS::Cluster
       Properties:
         Name: java-app-demo-cluster
         ResourcesVpcConfig:
           EndpointPublicAccess: true
           SecurityGroupIds:
             - !Ref EKSControlPlaneSecurityGroup

2. Add your changes with the git add command.

   git add .pre-commit-config.yaml

   git add cloudformation/eks.template.yaml

3. Commit changes with the following command.

   git commit -m “bad config”

   You should see the following error that disallows the commit to the local repository and shows which one of your Guard rules failed.

   amazon-eks-controlplane.template.yaml Status = FAIL
   		
   FAILED rules
   		
   rules.guard/eks_public_disallowed    FAIL
   		
   ---
   		
   Evaluation of rules rules.guard against data amazon-eks-controlplane.template.yaml
   		
   ---
   		
   Property
   [/Resources/EKS/Properties/ResourcesVpcConfig/EndpointPublicAccess] in data
   [eks.template.yaml] is not compliant with [rules.guard/eks_public_disallowed] 
   because provided value [true] did not match expected value [false]. 
   Error Message []

4. (Optional) You can also test hooks before committing by using the pre-commit run command to see similar output.

Cleanup

To avoid incurring ongoing charges, follow these cleanup steps to delete the resources and files you created as you followed along with this blog post.

To clean up resources and files

1. Remove your local repository.
   rm -rf /path/to/repository
2. Delete the S3 bucket you created by running the following command.
   aws s3 rb s3://<account-id>-cfn-guard-rules --force
3. (Optional) Remove the pre-commit hooks framework by running this command.
   pip uninstall pre-commit

Conclusion

In this post, you learned how to use AWS CloudFormation Guard with the pre-commit framework locally to validate your infrastructure-as-code solutions before you push remote changes to your repositories.

You also learned how to extend the solution to use a centralized list of security rules that is stored in versioned code repositories (GitHub, Bitbucket, or GitLab) or an S3 bucket. And you learned how to further extend the solution with your own rules. You can find examples of rules to use in Guard’s Github repository or refer to write preventative compliance rules for AWS CloudFormation templates the cfn-guard way. You can then further configure other repositories to prevent misconfigurations by using the same Guard rules.

 
If you have feedback about this post, submit comments in the Comments section below. If you have questions about this post, start a new thread on the KMS re:Post or contact AWS Support.

Want more AWS Security news? Follow us on Twitter.