• Stars
    star
    2,417
  • Rank 19,030 (Top 0.4 %)
  • Language
    Python
  • License
    MIT No Attribution
  • Created over 6 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

CloudFormation Linter

AWS CloudFormation Linter

[cfn-lint logo]

Testing PyPI version PyPI downloads PyPI downloads codecov Discord Shield

Validate AWS CloudFormation yaml/json templates against the AWS CloudFormation Resource Specification and additional checks. Includes checking valid values for resource properties and best practices.

Warning

This is an attempt to provide validation for AWS CloudFormation templates properties and their values. For values things can get pretty complicated (mappings, joins, splits, conditions, and nesting those functions inside each other) so it's a best effort to validate those values but the promise is to not fail if we can't understand or translate all the things that could be going on.

Contribute

We encourage you to contribute to cfn-lint! Please check out the Contributing Guidelines for more information on how to proceed.

Community

Join us on Discord! Connect & interact with CloudFormation developers & experts, find channels to discuss and get help for cfn-lint, CloudFormation registry, StackSets, Guard and more:

Join our Discord

Serverless Application Model

The Serverless Application Model (SAM) is supported by the linter. The template is transformed using AWS SAM before the linter processes the template.

To get information about the SAM Transformation, run the linter with --info

Install

Python 3.7+ is supported.

Pip

pip install cfn-lint. If pip is not available, run python setup.py clean --all then python setup.py install.

Homebrew (macOS)

brew install cfn-lint

Docker

In cfn-python-lint source tree:

docker build --tag cfn-python-lint:latest .

In repository to be linted:

docker run --rm -v `pwd`:/data cfn-python-lint:latest /data/template.yaml

Editor Plugins

There are IDE plugins available to get direct linter feedback from you favorite editor:

GitHub Action

Online demo

Basic Usage

  • cfn-lint template.yaml
  • cfn-lint -t template.yaml

Multiple files can be linted by either specifying multiple specific files:

  • cfn-lint template1.yaml template2.yaml
  • cfn-lint -t template1.yaml template2.yaml

or by using wildcards (globbing):

Lint all yaml files in path:

  • cfn-lint path/*.yaml

Lint all yaml files in path and all subdirectories (recursive):

  • cfn-lint path/**/*.yaml

Note: If using sh/bash/zsh, you must enable globbing. (setopt -s globstar for sh/bash, setopt extended_glob for zsh).

Exit Codes

cfn-lint will return a non zero exit if there are any issues with your template. The value is dependent on the severity of the issues found. For each level of discovered error cfn-lint will use bitwise OR to determine the final exit code. This will result in these possibilities.

  • 0 is no issue was found
  • 2 is an error
  • 4 is a warning
  • 6 is an error and a warning
  • 8 is an informational
  • 10 is an error and informational
  • 12 is an warning and informational
  • 14 is an error and a warning and an informational
Configuring Exit Codes

cfn-lint allows you to configure exit codes. You can provide the parameter --non-zero-exit-code with a value of informational, warning, error, or none. cfn-lint will determine the exit code based on the match severity being the value of the parameter --non-zero-exit-code and higher. The exit codes will remain the same as above.

The order of severity is as follows:

  1. informational default
  2. warning
  3. error
  4. none Exit code will always be 0 unless there is a syntax error
Specifying the template as an input stream

The template to be linted can also be passed using standard input:

  • cat path/template.yaml | cfn-lint -
Specifying the template with other parameters
  • cfn-lint -r us-east-1 ap-south-1 -- template.yaml
  • cfn-lint -r us-east-1 ap-south-1 -t template.yaml

Configuration

Command Line

From a command prompt run cfn-lint <path to template> to run standard linting of the template.

Config File

It will look for a configuration file in the following locations (by order of preference):

  • .cfnlintrc, .cfnlintrc.yaml or .cfnlintrc.yml in the current working directory
  • ~/.cfnlintrc for the home directory

In that file you can specify settings from the parameter section below.

Example:

templates:
  - test/fixtures/templates/good/**/*.yaml
ignore_templates:
  - codebuild.yaml
include_checks:
  - I
custom_rules: custom_rules.txt

Parameters

Optional parameters:

Command Line Metadata Options Description
-h, --help Get description of cfn-lint
-z, --custom-rules filename Text file containing user-defined custom rules. See here for more information
-t, --template filename Alternative way to specify Template file path to the file that needs to be tested by cfn-lint
-f, --format format quiet, parseable, json, junit, pretty, sarif Output format
-l, --list-rules List all the rules
-r, --regions regions [REGIONS [REGIONS ...]], ALL_REGIONS Test the template against many regions. Supported regions
-b, --ignore-bad-template ignore_bad_template Ignores bad template errors
--ignore-templates IGNORE_TEMPLATES [IGNORE_TEMPLATES ...] Ignore templates from being scanned
-a, --append-rules append_rules [RULESPATH [RULESPATH ...]] Specify one or more rules paths using one or more --append-rules arguments. Each path can be either a directory containing python files, or an import path to a module.
-i, --ignore-checks ignore_checks [IGNORE_CHECKS [IGNORE_CHECKS ...]] Only check rules whose ID do not match or prefix these values. Examples:
- A value of W will disable all warnings
- W2 disables all Warnings for Parameter rules.
- W2001 will disable rule W2001
-e, --include-experimental include_experimental Whether rules that still in an experimental state should be included in the checks
-c, --include-checks INCLUDE_CHECKS [INCLUDE_CHECKS ...] Include rules whose id match these values
-m, --mandatory-checks Rules to check regardless of ignore configuration
--non-zero-exit-code informational (default), warning, error, none] Exit code will be non zero from the specified rule class and higher
-x, --configure-rule CONFIGURE_RULES [CONFIGURE_RULES ...] Provide configuration for a rule. Format RuleId:key=value. Example: E3012:strict=true
-D, --debug Specify to enable debug logging. Debug logging outputs detailed information about rules processing, useful for debugging rules.
-I, --info Specify to enable logging. Outputs additional information about the template processing.
-u, --update-specs Update the CloudFormation Resource Specifications. You may need sudo to run this. You will need internet access when running this command
-o, --override-spec filename Spec-style file containing custom definitions. Can be used to override CloudFormation specifications. More info here
-g, --build-graph Creates a file in the same directory as the template that models the template's resources in DOT format
-s, --registry-schemas one or more directories of CloudFormation Registry Resource Schemas
-v, --version Version of cfn-lint

Info Rules

To maintain backwards compatibility info rules are not included by default. To include these rules you will need to include -c I or --include-checks I

Metadata

Template Based Metadata

Inside the root level Metadata key you can configure cfn-lint using the supported parameters.

Metadata:
  cfn-lint:
    config:
      regions:
        - us-east-1
        - us-east-2
      ignore_checks:
        - E2530

Resource Based Metadata

Inside a resources Metadata key you can configure cfn-lint to ignore checks. This will filter out failures for the resource in which the Metadata belongs. Keep in mind that AWS::Serverless resources may lose metadata during the Serverless transform

Resources:
  myInstance:
    Type: AWS::EC2::Instance
    Metadata:
      cfn-lint:
        config:
          ignore_checks:
            - E3030
    Properties:
      InstanceType: nt.x4superlarge
      ImageId: ami-abc1234

Precedence

cfn-lint applies configurations from several sources. The rules at lower levels are overridden by those at higher levels.

  1. cfnlintrc configurations
  2. Template Metadata configurations
  3. CLI parameters

Configure Rules

Certain rules support configuration properties. You can configure these rules by using configure_rules parameter.

From the command line the format is RuleId:key=value, for example: E3012:strict=true. From the cfnlintrc or Metadata section the format is

Metadata:
  cfn-lint:
    config:
      configure_rules:
        RuleId:
          key: value

The configurable rules have a non-empty Config entry in the table here.

Getting Started Guides

There are getting started guides available in the documentation section to help with integrating cfn-lint or creating rules.

Rules

This linter checks the AWS CloudFormation template by processing a collection of Rules, where every rule handles a specific function check or validation of the template.

This collection of rules can be extended with custom rules using the --append-rules argument.

More information describing how rules are set up and an overview of all the Rules that are applied by this linter are documented here.

Custom Rules

The linter supports the creation of custom one-line rules which compare any resource with a property using pre-defined operators. These custom rules take the following format:

<Resource Type> <Property[*]> <Operator> <Value> [Error Level] [Custom Error Message]

Example

A separate custom rule text file must be created.

The example below validates example_template.yml does not use any EC2 instances of size m4.16xlarge

custom_rule.txt

AWS::EC2::Instance InstanceSize NOT_EQUALS "m4.16xlarge" WARN "This is an expensive instance type, don't use it"

example_template.yml

AWSTemplateFormatVersion: "2010-09-09"
Resources:
        myInstance:
                Type: AWS::EC2::Instance
                Properties:
                        InstanceType: m4.16xlarge
                        ImageId: ami-asdfef

The custom rule can be added to the configuration file or ran as a command line argument

The linter will produce the following output, running cfn-lint example_template.yml -z custom_rules.txt:

W9001  This is an expensive instance type, don't use it
mqtemplate.yml:6:17

More information describing how custom rules are setup and an overview of all operators available is documented here.

Customize specifications

The linter follows the AWS CloudFormation Resource Specifications by default. However, for your use case specific requirements might exist. For example, within your organisation it might be mandatory to use Tagging.

The linter provides the possibility to implement these customized specifications using the --override-spec argument.

More information about how this feature works is documented here

pre-commit

If you'd like cfn-lint to be run automatically when making changes to files in your Git repository, you can install pre-commit and add the following text to your repositories' .pre-commit-config.yaml:

repos:
- repo: https://github.com/aws-cloudformation/cfn-lint
  rev: v0.77.6  # The version of cfn-lint to use
  hooks:
    - id: cfn-lint
      files: path/to/cfn/dir/.*\.(json|yml|yaml)$

If you are using a .cfnlintrc and specifying the templates or ignore_templates we would recommend using the .cfnlintrc exlusively to determine which files should be scanned and then using:

repos:
- repo: https://github.com/aws-cloudformation/cfn-lint
  rev: v0.77.6 # The version of cfn-lint to use
  hooks:
    - id: cfn-lint-rc

Note: When mixing .cfnlintrc ignore_templates and files option in your .pre-commit-config.yaml cfn-lint may return a file not found error

  • If you exclude the files: line above, every json/yml/yaml file will be checked.
  • You can see available cfn-lint versions on the releases page.

More Repositories

1

aws-cloudformation-templates

A collection of useful CloudFormation templates
Python
4,619
star
2

cloudformation-guard

Guard offers a policy-as-code domain-specific language (DSL) to write rules and validate JSON- and YAML-formatted data such as CloudFormation Templates, K8s configurations, and Terraform JSON plans/configurations against those rules. Take this survey to provide feedback about cfn-guard: https://amazonmr.au1.qualtrics.com/jfe/form/SV_bpyzpfoYGGuuUl0
Rust
1,267
star
3

cloudformation-coverage-roadmap

The AWS CloudFormation Public Coverage Roadmap
1,105
star
4

rain

A development workflow tool for working with AWS CloudFormation.
Go
785
star
5

awesome-cloudformation

A curated list of resources and projects for working with AWS CloudFormation.
575
star
6

custom-resource-helper

Simplify best practice Custom Resource creation, sending responses to CloudFormation and providing exception, timeout trapping, and detailed configurable logging.
Python
377
star
7

cloudformation-cli

The CloudFormation Provider Development Toolkit allows you to author your own resource providers and modules that can be used by CloudFormation.
Python
319
star
8

cfn-lint-visual-studio-code

CloudFormation Linter IDE integration, autocompletion, and documentation
JavaScript
254
star
9

cfn-language-discussion

Language discussions for CloudFormation template language
142
star
10

cloudformation-template-schema

Inline syntax validation, documentation links and autocompletion for your CloudFormation templates.
Java
141
star
11

aws-cloudformation-samples

Python
135
star
12

cloudformation-cli-python-plugin

The CloudFormation Provider Development Toolkit Python Plugin allows you to autogenerate Python code based on an input schema.
Python
108
star
13

aws-guard-rules-registry

Rules Registry for Compliance Frameworks
Python
106
star
14

cloudformation-resource-schema

The CloudFormation Resource Schema defines the shape and semantic for resources provisioned by CloudFormation. It is used by provider developers using the CloudFormation RPDK.
Java
92
star
15

community-registry-extensions

Python
85
star
16

aws-cloudformation-macros

This repository hosts examples of AWS CloudFormation macros.
Python
82
star
17

aws-cloudformation-resource-providers-awsutilities-commandrunner

Java
80
star
18

cloudformation-cli-go-plugin

The CloudFormation Provider Development Toolkit Go Plugin allows you to autogenerate Go code based on an input schema.
Go
52
star
19

aws-cloudformation-resource-providers-cloudformation

The CloudFormation Resource Provider Package For AWS CloudFormation
Java
48
star
20

resource-providers-list

Index page for AWS CloudFormation resource provider repos
47
star
21

cloudformation-cli-typescript-plugin

The CloudFormation Provider Development Toolkit Node.js Plugin allows you to autogenerate TypeScript code based on an input schema.
TypeScript
42
star
22

aws-cloudformation-resource-providers-logs

The CloudFormation Resource Provider Package For Amazon CloudWatch Logs
Java
32
star
23

cloudformation-cli-java-plugin

The CloudFormation Provider Development Toolkit Java Plugin allows you to autogenerate java code based on an input schema.
Java
29
star
24

aws-cloudformation-resource-providers-codeartifact

The CloudFormation Resource Provider Package for the AWS CodeArtifact service
Java
27
star
25

aws-cloudformation-resource-providers-rds

The CloudFormation Resource Provider Package For Amazon Relational Database Service
Java
27
star
26

cfn-lint-atom

Provides IDE specific integration to cfn-lint
JavaScript
27
star
27

aws-cloudformation-resource-providers-ssm

The CloudFormation Resource Provider Package For AWS Systems Manager
Java
24
star
28

aws-cloudformation-resource-providers-ses

The CloudFormation Resource Provider Package For Amazon Simple Email Service
Java
22
star
29

aws-cloudformation-resource-providers-sns

The CloudFormation Resource Provider Package For Amazon Simple Notification Service (Amazon SNS). Amazon SNS is a fully managed messaging service for both application-to-application (A2A) and application-to-person (A2P) communication.
Java
16
star
30

aws-cloudformation-resource-providers-kms

AWS Key Management Service (KMS) makes it easy for you to create and manage cryptographic keys and control their use across a wide range of AWS services and in your applications. AWS KMS is a secure and resilient service that uses hardware security modules that have been validated under FIPS 140-2, or are in the process of being validated, to protect your keys. AWS KMS is integrated with AWS CloudTrail to provide you with logs of all key usage to help meet your regulatory and compliance needs.
Java
14
star
31

aws-cloudformation-resource-providers-ecr

The CloudFormation Resource Provider Package For Amazon ECR
Java
11
star
32

aws-cloudformation-resource-providers-imagebuilder

The CloudFormation Resource Provider Package For EC2 Image Builder
Java
11
star
33

cloudformation-pkl

Pkl
11
star
34

aws-cloudformation-resource-providers-accessanalyzer

The CloudFormation Resource Provider Package For AWS IAM Access Analyzer
Java
8
star
35

aws-cloudformation-resource-providers-codeguru-profiler

The CloudFormation Resource Provider Package For Amazon CodeGuru.
Java
8
star
36

aws-cloudformation-resource-providers-rds-proxy

The CloudFormation Resource Provider Package For Amazon RDS Proxy
Java
7
star
37

aws-cloudformation-resource-providers-transitgateway

The CloudFormation Resource Provider Package For AWS Transit Gateway
Java
7
star
38

aws-cloudformation-resource-providers-organizations

The CloudFormation Resource Provider Package For AWS Organizations
Java
6
star
39

aws-cloudformation-resource-providers-stepfunctions

The CloudFormation Resource Provider Package For AWS Step Functions
Java
6
star
40

resource-schema-guard-rail

The CloudFormation Resource Schema Guard Rail allows you to evaluate resource schema compliance against CloudFormation enforced best practices
Python
6
star
41

iac-model-evaluation

HCL
6
star
42

aws-cloudformation-resource-providers-cost-explorer

CloudFormation Resource Provider Package for AWS Cost Explorer
Java
5
star
43

aws-cloudformation-resource-providers-sso

Java
5
star
44

aws-cloudformation-resource-providers-mwaa

Amazon Managed Workflows for Apache Airflow provider type for AWS CloudFormation
Java
4
star
45

aws-cloudformation-resource-providers-devops-guru

Java
4
star
46

aws-cloudformation-resource-providers-rolesanywhere

Java
4
star
47

aws-cloudformation-resource-providers-networkfirewall

Java
4
star
48

aws-cloudformation-resource-providers-cur

Java
4
star
49

aws-cloudformation-resource-providers-kendra

AWS Kendra CloudFormation Resource Providers
Java
4
star
50

aws-cloudformation-resource-providers-glue

The CloudFormation Resource Provider Package For AWS Glue
Java
4
star
51

aws-cloudformation-resource-providers-connect

The CloudFormation Resource Provider package for Amazon Connect
Java
4
star
52

cloudformation-cli-java-plugin-testing-support

Testing Framework for the CloudFormation Provider Development Toolkit Java Plugin allows you to autogenerate java code based on an input schema.
Java
3
star
53

aws-cloudformation-resource-providers-nimblestudio

Java
3
star
54

aws-cloudformation-resource-providers-sagemaker

Java
3
star
55

aws-cloudformation-resource-providers-codegurureviewer

Java
3
star
56

aws-cloudformation-resource-providers-timestream

Java
3
star
57

aws-cloudformation-resource-providers-applicationinsights

Java
3
star
58

aws-cloudformation-resource-providers-aps

AWS CloudFormation resource provider for AWS Managed Service for Prometheus
Go
3
star
59

aws-cloudformation-resource-providers-lookoutvision

The CloudFormation Resource Provider Package for Amazon Lookout for Vision
Java
3
star
60

aws-cloudformation-resource-providers-auditmanager

The CloudFormation resource provider package for AWS Audit Manager
Java
3
star
61

aws-cloudformation-resource-providers-acmpca

CloudFormation Resource Provider for the Amazon Certificate Manager Private Certificate Authority (ACM-PCA) Service.
Java
3
star
62

aws-cloudformation-resource-providers-customer-profiles

Java
3
star
63

aws-cloudformation-resource-providers-msk-serverless

Java
3
star
64

aws-cloudformation-resource-providers-ec2-lgw

Java
3
star
65

aws-cloudformation-resource-providers-wafv2

The CloudFormation Resource Provider Package For Amazon WAF v2.
Java
3
star
66

aws-cloudformation-resource-providers-lightsail

Java
3
star
67

aws-cloudformation-resource-providers-synthetics

Cloudformation resources for Cloudwatch Synthetics
Java
3
star
68

aws-cloudformation-resource-providers-athena

The CloudFormation Resource Provider Package For Amazon Athena
Java
3
star
69

aws-cloudformation-resource-providers-redshift

The CloudFormation Resource Provider Package For Amazon Redshift
Java
3
star
70

aws-cloudformation-resource-providers-ec2-flowlog

The CloudFormation Resource Provider Package For VPC Flow Logs Service
Java
3
star
71

cloudformation-cli-hooks-extension

This CloudFormation CLI extension library provides more commands for managing and configuring your Resource Hooks.
Python
3
star
72

aws-cloudformation-resource-providers-vpc-lattice

The CloudFormation Resource Provider Package For AWS VPC Lattice
Java
3
star
73

aws-cloudformation-resource-providers-licensemanager

Java
2
star
74

aws-cloudformation-resource-providers-device-advisor

https://docs.aws.amazon.com/iot/latest/developerguide/device-advisor.html
Kotlin
2
star
75

aws-cloudformation-resource-providers-resource-explorer

The CloudFormation Resource Provider Package For AWS Resource Explorer
Java
2
star
76

aws-cloudformation-resource-providers-frauddetector

Python
2
star
77

aws-cloudformation-resource-providers-budgets

https://aws.amazon.com/aws-cost-management/aws-budgets/
Java
2
star
78

aws-cloudformation-resource-providers-events

The CloudFormation Resource Provider Package For Amazon CloudWatch Events
Java
2
star
79

aws-cloudformation-resource-providers-route53resolver-outpostresolver

https://aws.amazon.com/route53/
Java
2
star
80

aws-cloudformation-resource-providers-databrew

Java
2
star
81

aws-cloudformation-resource-providers-rekognition

AWS Rekognition
Java
2
star
82

aws-cloudformation-resource-providers-amplify

The CloudFormation Resource Provider Package For AWS Amplify Console
Java
2
star
83

aws-cloudformation-resource-providers-macie

Java
2
star
84

aws-cloudformation-resource-providers-globalaccelerator

Kotlin
2
star
85

aws-cloudformation-resource-providers-memorydb

The CloudFormation Resource Provider Package For Amazon MemoryDB Service
Java
2
star
86

aws-cloudformation-resource-providers-iotwireless

Java
2
star
87

aws-cloudformation-resource-providers-iotfleetindexing

Java
2
star
88

aws-cloudformation-resource-providers-ec2-acmcerts

Java
2
star
89

aws-cloudformation-resource-providers-kafkaconnect

The CloudFormation Resource Provider Package For Amazon MSK Connect
Java
2
star
90

aws-cloudformation-resource-providers-kinesisfirehose

The CloudFormation Resource Provider Package For Amazon Kinesis Data Firehose
Java
2
star
91

aws-cloudformation-resource-providers-opsworkscm

The CloudFormation Resource Provider Package For AWS OpsWorks CM
Java
2
star
92

aws-cloudformation-resource-providers-eventschemas

Java
1
star
93

aws-cloudformation-resource-providers-fms

The CloudFormation Resource Provider Package For Amazon Firewall Manager
Java
1
star
94

aws-cloudformation-resource-providers-ses-mailmanager

AWS SES MailManager CloudFormation Resources
Java
1
star
95

aws-cloudformation-resource-providers-transfer

The CloudFormation Resource Provider Package For AWS Transfer Family
Java
1
star
96

aws-cloudformation-resource-providers-route53-recovery-readiness

Java
1
star
97

aws-cloudformation-resource-providers-datasync

The CloudFormation Resource Provider package for AWS DataSync
Java
1
star
98

aws-cloudformation-resource-providers-iot

The CloudFormation Resource Provider Package For AWS IoT
Java
1
star
99

aws-cloudformation-resource-providers-ec2-nat-gateway

The CloudFormation Resource Provider Package For VPC NAT Gateway
Java
1
star
100

aws-cloudformation-resource-providers-route53-recovery-control

Java
1
star