cfn_nag
cfn_nag copied to clipboard
Linting tool for CloudFormation templates
![](https://github.com/stelligent/cfn_nag/raw/master/logo.png?raw=true)
Background
The cfn-nag tool looks for patterns in CloudFormation templates that may indicate insecure infrastructure. Roughly speaking, it will look for:
- IAM rules that are too permissive (wildcards)
- Security group rules that are too permissive (wildcards)
- Access logs that aren't enabled
- Encryption that isn't enabled
- Password literals
For more background on the tool, please see this post at Stelligent's blog:
Installation
Gem Install
Presuming Ruby >= 2.5.x is installed, installation is just a matter of:
gem install cfn-nag
Brew Install
On MacOS or Linux you can alternatively install with brew:
brew install ruby brew-gem
brew gem install cfn-nag
CodePipeline
To run cfn_nag
as an action in CodePipeline, you can deploy via the AWS Serverless Application Repository.
Usage
To execute:
cfn_nag_scan --input-path <path to cloudformation json>
The path can be a directory or a particular template. If it is a directory, all .json,
.template
, .yml
and .yaml
files will be processed, including recursing into subdirectories.
The default output format is free-form text, but json output can be selected with the --output-format json
flag.
Optionally, a --debug
flag will dump information about the internals of rule loading.
Run with --help
for a full listing of supported switches.
To see a list of all the rules cfn-nag currently supports, there is a command-line utility that will dump them to stdout:
cfn_nag_rules
Results
- The results are dumped to stdout
- A failing violation will return a non-zero exit code.
- A warning will return a zero/success exit code.
- A fatal violation stops analysis (per file) because the template is malformed in some severe way
Running in Docker
A Dockerfile is provided for convenience. It is published on DockerHub as stelligent/cfn_nag
.
https://hub.docker.com/r/stelligent/cfn_nag
You can also build it locally.
docker build -t stelligent/cfn_nag .
You can mount a local directory containing templates into the Docker container and then call cfn_nag in the container. This example uses the test templates used in unit testing cfn_nag:
$ docker run -v `pwd`/spec/test_templates:/templates -t stelligent/cfn_nag /templates/json/efs/filesystem_with_encryption.json
{
"failure_count": 0,
"violations": [
]
}
$ docker run -v `pwd`/spec/test_templates:/templates -t stelligent/cfn_nag /templates/json/efs/filesystem_with_no_encryption.json
{
"failure_count": 1,
"violations": [
{
"id": "F27",
"type": "FAIL",
"message": "EFS FileSystem should have encryption enabled",
"logical_resource_ids": [
"filesystem"
]
}
]
}
Running as a GitHub Action
cfn_nag_scan
can be run as part of a GitHub Workflow to evaluate code during continuous integration pipelines.
In your GitHub Workflow file, create a step which uses the cfn_nag Action:
- name: Simple test
uses: stelligent/cfn_nag@master
with:
input_path: tests
More information about the GitHub Action can be found here.
Results Filtering
Profiles
cfn-nag supports the notion of a "profile" which is effectively an allow list of rules to apply. The profile is a text file
that must contain a rule identifier per line. When specified via the --profile-path
command line argument,
cfn-nag will ONLY return violations from those particular rules.
The motivation behind creating a "profile" is that different developers might care about different rules. For example, an "infrastructure_developer" might care about IAM rules, while an "app_developer" might not even be able to create IAM resources and therefore not care about those rules.
Here is an example profile:
F1
F2
F27
W3
W5
Global Deny List
The deny list is basically the opposite of the profile: it's a list of rules to NEVER apply. When specified via the
--deny-list-path
command line argument, cfn-nag will NEVER return violations from those particular rules specified
in the file.
In case a rule is specified in both, the deny list will take priority over the profile, and the rule will not be applied.
The format is as follows. The only two salient fields are RulesToSuppress
and the id
per item. The reason
won't
be interpreted by cfn-nag, but it is recommended to justify and document why the rule should never be applied.
RulesToSuppress:
- id: W3
reason: W3 is something we never care about at enterprise X
Per-Resource Rule Suppression
In the event that there is a rule that you want to suppress, a cfn_nag
Metadata
key can be added to the affected resource to tell cfn_nag to not raise a failure or warning for that rule.
For example, if you are setting up a public-facing ELB that's open to inbound connections from the internet with resources like the following:
public_alb.yaml
# Partial template
PublicAlbSecurityGroup:
Properties:
GroupDescription: 'Security group for a public Application Load Balancer'
VpcId:
Ref: vpc
Type: AWS::EC2::SecurityGroup
PublicAlbSecurityGroupHttpIngress:
Properties:
CidrIp: 0.0.0.0/0
FromPort: 80
GroupId:
Ref: PublicAlbSecurityGroup
IpProtocol: tcp
ToPort: 80
Type: AWS::EC2::SecurityGroupIngress
cfn_nag will raise warnings like the following:
$ cfn_nag_scan -i public_alb.yaml
------------------------------------------------------------
public_alb.yaml
------------------------------------------------------------------------------------------------------------------------
| WARN W9
|
| Resources: ["PublicAlbSecurityGroup"]
|
| Security Groups found with ingress cidr that is not /32
------------------------------------------------------------
| WARN W2
|
| Resources: ["PublicAlbSecurityGroup"]
|
| Security Groups found with cidr open to world on ingress. This should never be true on instance. Permissible on ELB
Failures count: 0
Warnings count: 2
By adding the metadata, these warnings can be suppressed:
public_alb_with_suppression.yaml
# Partial template
PublicAlbSecurityGroup:
Properties:
GroupDescription: 'Security group for a public Application Load Balancer'
VpcId:
Ref: vpc
Type: AWS::EC2::SecurityGroup
Metadata:
cfn_nag:
rules_to_suppress:
- id: W9
reason: "This is a public facing ELB and ingress from the internet should be permitted."
- id: W2
reason: "This is a public facing ELB and ingress from the internet should be permitted."
PublicAlbSecurityGroupHttpIngress:
Properties:
CidrIp: 0.0.0.0/0
FromPort: 80
GroupId:
Ref: PublicAlbSecurityGroup
IpProtocol: tcp
ToPort: 80
Type: AWS::EC2::SecurityGroupIngress
$ cfn_nag_scan -i public_alb_with_suppression.yaml
------------------------------------------------------------
public_alb_with_supression.yaml
------------------------------------------------------------
Failures count: 0
Warnings count: 0
Setting Template Parameter Values
CloudFormation Template Parameters can present a problem for static analysis as the values are specified at the point of deployment. In other words, the values aren't available when the static analysis is done - static analysis can only look at the "code" that is in front of it. Therefore a security group ingress rule of 0.0.0.0/0 won't be flagged if the cidr is parameterized and the 0.0.0.0/0 is passed in at deploy time.
To allow for checking parameter values, a user can specify the parameter values in a JSON file passed on the command line
to both cfn_nag
and cfn_nag_scan
with the --parameter-values-path=<filename/uri>
flag.
The format of the JSON is a single key, "Parameters", whose value is a dictionary with each key/value pair mapping to the Parameters:
{
"Parameters": {
"Cidr": "0.0.0.0/0"
}
}
This will provide "0.0.0.0/0" to the following Parameter:
Parameters:
Cidr:
Type: String
BEWARE that if there are extra parameters in the JSON, they are quietly ignored (to allow cfn_nag_scan
to apply
the same JSON across all the templates).
If the JSON is malformed or doesn't meet the above specification, then parsing will fail with a FATAL violation.
Mappings
Prior to 0.5.55, calls to Fn::FindInMap were effectively ignored. The underlying model would
leave them be, and so they would appear as Hash values to rules. For example: { "Fn::FindInMap" => [map1, key1, key2]}
Starting in 0.5.55, the model will attempt to compute the value for a call to FindInMap and present that value to the rules. This evaluation supports keys that are:
- static text
- references to parameters (with parameter substitution)
- references to AWS pseudofunctions (see next section)
- nested maps
If the evaluation logic can't figure out the value for a key, it will default to the old behavior of returning the Hash for the whole expression.
AWS Pseudofunctions
Also prior to 0.5.55, calls to AWS pseudofunctions were effectively ignored. The underlying model would
leave them be, and so they would appear as Hash values to rules. For example: {"Ref"=>"AWS::Region"}
.
A common use case is to organize mappings by region, so pseudofunction evaluation is important to better supporting
map evaluation.
Starting in 0.5.55, the model will present the following AWS pseudofunctions to rules with the default values:
'AWS::URLSuffix' => 'amazonaws.com',
'AWS::Partition' => 'aws',
'AWS::NotificationARNs' => '',
'AWS::AccountId' => '111111111111',
'AWS::Region' => 'us-east-1',
'AWS::StackId' => 'arn:aws:cloudformation:us-east-1:111111111111:stack/stackname/51af3dc0-da77-11e4-872e-1234567db123',
'AWS::StackName' => 'stackname'
Additionally, the end user can override the value supplied via the traditional parameter substitution mechanism. For example:
{
"Parameters": {
"AWS::Region": "eu-west-1"
}
}
Controlling the Behavior of Conditions
Up until version 0.4.66 of cfn_nag, the underlying model did not do any processing of Fn::If within a template. This meant that if a property had a conditional value, it was up to the rule to parse the Fn::If. Given that an Fn::If could appear just about anywhere, it created a whack-a-mole situation for rule developers. At best, the rule logic could ignore values that were Hash presuming the value wasn't a Hash in the first place.
In order to address this issue, the default behavior for cfn_nag is now to substitute Fn::If with the true outcome. This means by default that rules will not inspect the false outcomes for security violations.
In addition to substituting Fn::If at the property value level, the same behavior is applied to Fn::If at the top-level of Properties. For example:
Resource1:
Type: Foo
Properties: !If
- IsNone
- Description: Up
- Description: DOwn
Will look the same as:
Resource1:
Type: Foo
Properties:
Description: Up
To provide some control over this behavior, a user can specify the condition values in a JSON file passed on the command line
to both cfn_nag
and cfn_nag_scan
with the --condition-values-path=<filename/uri>
flag.
The format of the JSON is a a dictionary with each key/value pair mapping to the Conditions:
{
"Condition1": true,
"Condition2": false
}
Stelligent Policy Complexity Metrics (spcm)
The basis for SPCM is described in the blog post Thought Experiment Proposed Complexity Metric for IAM Policy Documents.
Starting in version 0.6.0 of cfn_nag:
-
spcm_scan
can scan a directory of CloudFormation templates (like cfn_nag_scan) and generate a report with the SPCM metrics in either JSON or HTML format - A rule is added (to cfn_nag) to warn on an IAM::Policy or IAM::Role with a SPCM score of >= 50 (default)
- The rule threshold can be controlled via the command line:
cfn_nag_scan --rule-arguments spcm_threshold:100
- Custom rule developers can now develop rules to accept end user values for settings via the same
--rule-arguments
mechanism. The Rule object only needs to declare anattr_accessor
, e.g.attr_accessor :spcm_threshold
and cfn_nag will take care of the details to inject values from the--rule-arguments
Distribution of Custom Rules
The release of 0.5.x includes some major changes in how custom rules (can) be distributed and loaded. Before this release,
there were two places where rules were loaded from: the lib/cfn-nag/custom_rules
directory within the core cfn_nag gem,
and the custom-rule-directory specified on the command line.
There are two use cases that forced a redesign of how/where custom rules are loaded. The rule loading mechanism has been generalized such that custom rule repositories can be used to discover rules.
-
A bunch of "rule files" sitting around on a filesystem isn't great from a traditional software development perspective. There is no version or traceability on these files, so 0.5.x introduces the notion of a "cfn_nag rule gem". A developer can develop custom rules as part of a separate gem, version it and install it... and those rules are referenced from cfn_nag as long as the gem metadata includes
cfn_nag_rules => true
. For a gem named like "cfn-nag-hipaa-rules", any *.rb under lib/cfn-nag-hipaa-rules will be loaded. Any custom rules should derive from CfnNag::BaseRule in cfn-nag/base_rule (not cfn-nag/custom-rules/base). If the rule must derive from something else, defining a methodcfn_nag_rule?
that returns true will also cause it to be loaded as a rule. -
When cfn_nag is running in an AWS Lambda - there isn't really a filesystem (besides /tmp) in the traditional sense. Therefore, only core rules are usable from the Lambda. To support custom rules, cfn_nag supports discovering rules from an S3 bucket instead of the filesystem.
Everything you've likely seen about how to develop custom rules in Ruby still holds true.
To discover rules from an S3 bucket, create a file s3.yml
with this content:
---
repo_class_name: S3BucketBasedRuleRepo
repo_arguments:
s3_bucket_name: cfn-nag-rules-my-enterprise
prefix: /rules
To apply *Rule.rb files in the bucket cfn-nag-rules-my-enterprise with the prefix /rules (e.g. /rules/MyNewRule.rb), specify this file on the command line to cfn_nag as such:
cat my_cfn_template.yml | cfn_nag --rule-repository s3.yml
If rules are in more than one bucket, then create multiple s3*.yml files and specify them in the --rule-repository
argument.
If the ambient AWS credentials have permission to access the bucket cfn-nag-rules-enterprise
then it will find all rules
like /rules/*Rule.rb
. If a particular aws_profile should be used, add it as a key under repo_arguments
, e.g
aws_profile: my_aws_profile
Beyond the filesystem, gem installs and S3 - the new architecture theoretically supports developing other "rule repositories" to load rules from DynamoDb, relational databases, or other web services.
Development
New Rules
To author new rules for your own use and/or community contribution, see Custom Rule Development for details.
A screencast demonstrating soup-to-nuts TDD custom rule development is available here:
https://www.youtube.com/watch?v=JRZct0naFd4&t=1601s
Specs
To run the specs, you need to ensure you have Docker installed and cfn_nag dependencies installed via
gem install bundle
bundle install
Then, to run all of the specs, just run rake test:all
.
To run the end-to-end tests, run rake test:e2e
. The script will bundle all gems in the Gemfile, build and install the cfn_nag gem locally, install spec dependencies, and then executes tests tagged with 'end_to_end'. It will also pull down sample templates provided by Amazon and run cfn_nag_scan against them, to see if any known-good templates cause exceptions within cfn-nag.
Local Install
To install the current git branch locally:
bundle install
scripts/deploy_local.sh
VS Code Remote Development
There is a complete remote development environment created and setup with all the tools and settings pre-configured for ease in rule development and creation. You can enable this by using the VS Code Remote development functionality.
- Install the VS Code Remote Development extension pack
- Open the repo in VS Code
- When prompted
Folder contains a dev container configuration file. Reopen folder to develop in a container
click theReopen in Container
button - When opening in the future use the
[Dev Container] cfn_nag Development
option
More information about the VS Code Remote Development setup can be found here, VS Code Remote Development.
Support
To report a bug or request a feature, submit an issue through the GitHub repository via: https://github.com/stelligent/cfn_nag/issues/new