This repo contains source code for the following tools:
CloudFormation GuardA CLI tool that- Checks AWS CloudFormation templates for policy compliance using a simple, policy-as-code, declarative syntax
- Can autogenerate rules from existing CloudFormation templates
CloudFormation Guard Lambdais the AWS Lambda version of CloudFormation Guard'scheckfunctionalityCloudFormation Guard Rulegen Lambdais the AWS Lambda version of CloudFormation Guard'srulegenfunctionality
CloudFormation Guard uses a simple rule syntax to allow you to specify the characteristics you want (or don't want) in your CloudFormation Resources.
For example, given a CloudFormation template:
{
"Resources": {
"NewVolume" : {
"Type" : "AWS::EC2::Volume",
"Properties" : {
"Size" : 500,
"Encrypted": false,
"AvailabilityZone" : "us-west-2b"
}
},
"NewVolume2" : {
"Type" : "AWS::EC2::Volume",
"Properties" : {
"Size" : 50,
"Encrypted": false,
"AvailabilityZone" : "us-west-2c"
}
}
}
}
And a set of rules:
let encryption_flag = true
AWS::EC2::Volume Encrypted == %encryption_flag
AWS::EC2::Volume Size <= 100
You can check the template to ensure that it adheres to the rules.
$> cfn-guard check -t Examples/ebs_volume_template.json -r Examples/ebs_volume_template.ruleset
[NewVolume2] failed because [Encrypted] is [false] and the permitted value is [true]
[NewVolume] failed because [Encrypted] is [false] and the permitted value is [true]
[NewVolume] failed because [Size] is [500] and the permitted value is [<= 100]
Number of failures: 3
CloudFormation Guard can be used to evaluate security best practices for infrastructure deployed via CloudFormation. A number of example rules are included:
$> cfn-guard check -t Examples/security_template.json -r Examples/security_rules.ruleset
"[AmazonMQBroker] failed because [AutoMinorVersionUpgrade] is [false] and Version upgrades should be enabled to receive security updates"
"[AmazonMQBroker] failed because [EncryptionOptions.UseAwsOwnedKey] is [true] and CMKs should be used instead of AWS-provided KMS keys"
"[AmazonMQBroker] failed because [EngineVersion] is [5.15.9] and Broker engine version should be at least 5.15.10"
...
More details on how to write rules and how the tool can work with build systems can be found here.
You can also use the CloudFormation Guard tool to automatically generate rules from known-good CloudFormation templates.
Using the same template as above, cfn-guard rulegen would produce:
$> cfn-guard rulegen Examples/ebs_volume_template.json
AWS::EC2::Volume Encrypted == false
AWS::EC2::Volume Size == 101 |OR| AWS::EC2::Volume Size == 99
AWS::EC2::Volume AvailabilityZone == us-west-2b |OR| AWS::EC2::Volume AvailabilityZone == us-west-2c
From there, you can pipe them into a file and add, edit or remove rules as you need.
Everything that can be checked from the command-line version of the tool can be checked using the Lambda version. The same is true for the rulegen functionality.
The CLI tool for cfn-guard is available via homebrew.
Installation via homebrew:
brew install cloudformation-guard
The CLI tool for cfn-guard is available via chocolatey.
Installation via chocolatey:
choco install cloudformation-guard --version=1.0.0
The CLI tool for cfn-guard is available from GitHub releases.
Grab the latest release from our releases page:
wget https://github.com/aws-cloudformation/cloudformation-guard/releases/download/VERSION/cfn-guard-linux-VERSION.tar.gz
tar -xvf cfn-guard-linux-1.0.0.tar.gz
cd ./cfn-guard-linux
./cfn-guard
CloudFormation Guard 1.0.0
USAGE:
cfn-guard [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
check Check CloudFormation templates against rules
help Prints this message or the help of the given subcommand(s)
rulegen Autogenerate rules from an existing CloudFormation template
You can then move this to the directory of your choosing so it is on your $PATH
Binaries are also available for Mac and Windows on the releases page in a tarball with corresponding documents.
git clone [email protected]:aws-cloudformation/cloudformation-guard.git
Or click the green "Clone or download" button and select "Download Zip". Unzip the contents to view and compile the source code.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
If you haven't already, run source $HOME/.cargo/env as recommended by the rust installer.
Read here for more information
If building on Ubuntu, it's recommended to run sudo apt-get update; sudo apt install build-essential
- Create a Windows 10 workspace
- Install the version of Microsoft Visual C++ Build Tools 2019 which provides just the Visual C++ build
tools: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019
- Download the installer and run it.
- Select the "Individual Components" tab and check "Windows 10 SDK"
- Select the "Language Packs" tab and make sure that at least "English" is selected
- Click "Install"
- Let it download and reboot if asked
- Install rust
- Download rust-init.exe
- Run it and accept the defaults
The primary interface to the toolchain is the Makefile. To build the binaries or deploy the lambda you want, simply run their make target (eg make cfn-guard-rulegen). A copy of the resulting binary will be moved to the top-level cfn-guard-toolchain/bin/ directory. (Note that the files inside bin/ aren't version-controlled, though.)
cfn-guard-lambda is a little trickier since it's a lambda, not a binary, and therefore has different steps for install and update. It also requires you to set up some things before you can deploy it from the Makefile. (Please see its documentation for more information.). Once it's set up, it can be deployed from the top-level Makefile with targets for cfn-guard-lambda_install and cfn-guard-lambda_update.
Releases are available via the repo's GitHub releases for each platform. Alternatively, you can build a copy from source.
There are two make targets that package up the source without the git history, etc.
make release will package the source into a file called cloudformation-guard.tar.gz without the git history.
make release_with_binaries will first do a cargo build --release for both cfn-guard-rulegen and cfn-guard targeting whatever architecture the make command is run on (eg, your laptop's OS), placing the binaries in the cloudformation-guard/bin/ directory. From there, it tars them and the necessary source files into cloudformation-guard.tar.gz. (NOTE: Mail messages with binaries in zip files may get blocked by spam filters.)
Details on how to use each tool and how to build them are available in each tool's README.
CloudFormation Guard Rulegen Lambda
For a detailed walkthrough of CloudFormation Guard, please follow this blog
A: Guard solves a number of use-cases:
- It can be used to check repositories of CloudFormation templates for policy violations with automation.
- It can be a deployment gate in a CI/CD pipeline.
- It allows you to define a single source-of-truth for what constitutes valid infrastructure definitions. Define rules once and have them run both locally and as lambdas in your AWS account for integration with other AWS services.
- It allows for pre-deployment safety checks of your CloudFormation template resources. You can both require settings to be included and prohibit configurations that have caused issues previously.
- It's easy to get started. You can extract rules you want from existing, known-good templates using the CloudFormation Guard Rulegen auto-generation tool.
A: Guard is a command-line tool with the ability to check local CloudFormation templates. It can also deploy as an AWS Lambda Function and be linked to other AWS services that have Lambda integration.
This project is licensed under the Apache-2.0 License.