cfn-lint

# AWS CloudFormation Linter Validate AWS CloudFormation yaml/json templates against the [AWS CloudFormation resource provider schemas](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-type-schemas.html) 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](https://github.com/aws-cloudformation/cfn-lint/blob/main/CONTRIBUTING.md) 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: #### Serverless Application Model The Serverless Application Model (SAM) is supported by the linter. The template is transformed using [AWS SAM](https://github.com/awslabs/serverless-application-model) before the linter processes the template. _To get information about the [SAM Transformation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-serverless.html), run the linter with `--info`_ ## Install Python 3.10 to 3.14 are supported. ### Pip `pip install cfn-lint`. If pip is not available, run `python setup.py clean --all` then `python setup.py install`. #### Optional dependencies `cfn-lint` has optional dependencies based on certain features you may need. * `pip install cfn-lint[full]` for installing all the optional dependencies. This will install all the dependencies for graph, junit, and sarif. * `pip install cfn-lint[graph]` for installing `pydot` to draw and output template graphs * `pip install cfn-lint[junit]` for installing the packages to output the `junit` format * `pip install cfn-lint[sarif]` for installing the packages to output the `sarif` format ### Homebrew (macOS) `brew install cfn-lint` ### Docker In `cfn-lint` source tree: ```shell docker build --tag cfn-lint:latest . ``` In repository to be linted: ```shell docker run --rm -v `pwd`:/data cfn-lint:latest /data/template.yaml ``` ### Editor Plugins There are IDE plugins available to get direct linter feedback from you favorite editor: - [Atom](https://atom.io/packages/atom-cfn-lint) - [Emacs](https://www.emacswiki.org/emacs/CfnLint) - NeoVim 0.2.0+/Vim 8 - [ALE](https://github.com/w0rp/ale#supported-languages) - [Coc](https://github.com/joenye/coc-cfn-lint) - [Syntastic](https://github.com/speshak/vim-cfn) - [Sublime](https://packagecontrol.io/packages/SublimeLinter-contrib-cloudformation) - [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=kddejong.vscode-cfn-lint) - [IntelliJ IDEA](https://plugins.jetbrains.com/plugin/10973-cfn-lint) ### [GitHub Action](https://github.com/marketplace/actions/cfn-lint-action) ### [Online demo](https://github.com/PatMyron/cfn-lint-online) ## 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. (`shopt -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_ 1. `warning` 1. `error` 1. `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 ` 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: ```yaml 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](#Custom-Rules) for more information | | -t, --template | | filename | Alternative way to specify Template file path to the file that needs to be tested by cfn-lint | | --deployment-files | deployment_files | | Specify deployment files that are used to configure the template runner. This will specify templates and parameters and you don't specify parameters or parameter files with this parameter. Examples of a deployment include: [GitSync](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/git-sync.html) | --parameters | parameters | | Specify a list of parameters using the format `Key=Value` | | --parameter-files | parameter_files | | A list of parameter files that would be used when using the aws cli | | -f, --format | format | quiet, parseable, json, junit, pretty, sarif | Output format | | -l, --list-rules | | | List all the rules | | -L, --list-templates | | | List all the templates would have linted | | -r, --regions | regions | [REGIONS [REGIONS ...]], ALL_REGIONS | Test the template against many regions. [Supported regions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-type-schemas.html) | | -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 | | INCLU