cloudburn

CloudBurn CLI for catching cost issues before you deploy with scan, then running the same policies against live AWS with discover.

scan checks Terraform and CloudFormation. discover uses AWS Resource Explorer as a live service catalog so CloudBurn can find deployed resources and run rules against them.

Installation

CloudBurn requires Node.js 24+.

npm install --global cloudburn

If you want to keep it local to a project:

npm install cloudburn
npx cloudburn scan ./main.tf

Getting Started

Config

Config is optional. By default, CloudBurn runs the AWS Core preset for the mode you use. Account-wide rules such as CLDBRN-AWS-TAGGING-1 are opt-in through enabled-rules because they require an accessible Resource Explorer aggregator.

Create a starter config with:

cloudburn config --init

If you want to print the current discovered config file:

cloudburn config --print

If you want to inspect the starter template without writing a file:

cloudburn config --print-template

CloudBurn does not implicitly trust repository config in CI. Pass the exact file explicitly when you want CI to use its rule selection, output defaults, or severity gate:

cloudburn scan ./iac --config .cloudburn.yml
cloudburn discover --config .cloudburn.yml

Scan

Use scan to check Terraform and CloudFormation before you deploy.

cloudburn scan ./main.tf
cloudburn scan ./template.yaml
cloudburn scan ./iac --exit-code
cloudburn scan ./iac --fail-on high
cloudburn --format json scan ./iac

--fail-on high|medium|low exits with code 1 when an active finding meets or exceeds the selected severity. The same threshold can be configured as iac.fail-on. Plain --exit-code continues to gate on any active finding. In CI, configured thresholds apply only when the config is passed with --config as shown above.

Terraform and CloudFormation YAML support resource-local exceptions. Put one of these comments immediately above or inside the resource; text after the directive is retained as an optional reason:

# cloudburn-ignore CLDBRN-AWS-EBS-1 migration scheduled
resource "aws_ebs_volume" "legacy" {
  type = "gp2"
}

# cloudburn-ignore-all approved temporary exception
resource "aws_ebs_volume" "temporary" {
  type = "gp2"
}

Suppressed findings remain available in JSON output under suppressed, are counted in table output, and never fail CI gates. CloudFormation JSON does not support comments and therefore cannot contain inline suppressions.

Discover

Use discover to run the same rules against live AWS resources.

Run cloudburn discover init first. It automatically configures AWS Resource Explorer indexes, which CloudBurn uses as its live service catalog before it evaluates rules.

By default, cloudburn discover runs against your active AWS region. You can pass --region <region> to target one explicit region.

cloudburn discover init
cloudburn discover
cloudburn discover --region eu-central-1
cloudburn discover --config .cloudburn.yml --enabled-rules CLDBRN-AWS-EBS-1
cloudburn discover --enabled-rules CLDBRN-AWS-TAGGING-1
cloudburn discover --service ec2,s3
cloudburn discover --fail-on high
cloudburn --debug discover --region eu-central-1
cloudburn rules list
cloudburn rules list --service ec2 --source discovery --severity high

The discovery config equivalent is discovery.fail-on.

The CLI targets one region per run. Multi-region discovery remains available through the SDK and still needs an AWS Resource Explorer aggregator plus an unfiltered default view in the aggregator region. CLDBRN-AWS-TAGGING-1 is opt-in and requires an accessible aggregator; a local-only setup cannot run account-wide tagging discovery. Use --debug to print SDK and provider execution tracing to stderr without changing the normal stdout format.

Shell Completion

Inspect the available completion subcommands:

cloudburn completion
cloudburn completion zsh --help

Generate a completion script for your shell and source it directly:

source <(cloudburn completion zsh)
source <(cloudburn completion bash)
cloudburn completion fish | source

To enable completion persistently, add one of these lines to your shell config:

# ~/.zshrc
source <(cloudburn completion zsh)

# ~/.bashrc
source <(cloudburn completion bash)

# ~/.config/fish/config.fish
cloudburn completion fish | source

Docs

• Full docs: cloudburn.io/docs
• Rule reference: docs/reference/rule-ids.md
• Config reference: docs/reference/config-schema.md

License

Apache-2.0