[](https://cloudburn.io)
<div align="center">
<p align="center">
Open-source policy engine that blocks bad AWS spending patterns before they ship and remediates what's already burning.
<br /><br />
</p>
[](https://github.com/towardsthecloud/cloudburn/actions/workflows/ci.yml)
[](https://github.com/towardsthecloud/cloudburn/blob/main/LICENSE)
[](https://badge.fury.io/js/cloudburn)
[](https://github.com/marketplace/actions/cloudburn-scan)
[Changelog](https://cloudburn.io/changelog) | [Documentation](https://cloudburn.io/docs) | [Discord](https://discord.gg/CKKK5FRW3n)
</div>
CloudBurn runs deterministic cost rules against your Terraform and CloudFormation with `scan`, then runs those same rules against your live AWS account with `discover`. Wire it into CI to catch waste before deploy. Point it at a running account to find what's still burning money.
## Features
- **One rules engine, two modes.** 82 deterministic AWS cost rules for IaC and live accounts. See the [rule list](docs/reference/rule-ids.md).
- **Scan in CI.** Checks Terraform and CloudFormation in pull requests, CI jobs, and release pipelines, with a
[GitHub Action](https://github.com/marketplace/actions/cloudburn-scan) for pull request annotations and comments.
- **Discover in production.** Inspects deployed resources and shows what needs fixing.
- **Programmable.** The [SDK](packages/sdk/README.md) lets you run CloudBurn inside your own tooling.
- **Built for AI agents.** A [plugin](packages/mcp/README.md) gives Claude Code, Codex, and other agents read-only
CloudBurn tools and a skill for reviewing IaC and live accounts.
- **Machine and human friendly output.** `json` and `table` formats.
- **Check costs in your editor.** The [VS Code extension](packages/vscode/README.md) runs the CLI on save and shows
Terraform and CloudFormation findings in Problems. Available as a local VSIX preview.
## See It Run
### IaC scan
### Live discovery
## Installation
### Homebrew (macOS/Linux)
```bash
brew install towardsthecloud/tap/cloudburn
```
This installs Node.js automatically if you don't have it.
### npm
Requires Node.js 24+.
```bash
npm install --global cloudburn
```
Or run it without installing:
```bash
npx cloudburn scan ./main.tf
```
### GitHub Action
Get the [CloudBurn Scan action from the GitHub Marketplace](https://github.com/marketplace/actions/cloudburn-scan). It
scans your Terraform and CloudFormation in a workflow, annotates findings on the pull request, posts a sticky comment,
and can fail the job by severity. No Node.js setup or CLI install is needed.
```yaml
- uses: towardsthecloud/cloudburn-action@v1
with:
path: .
fail-on: high
```
See the [GitHub Action documentation](https://cloudburn.io/docs/cli/github-action) for all inputs, outputs, and examples.
### AI agents
Install the CloudBurn plugin to let your agent scan IaC and live accounts through a local MCP server. It needs
Node.js 24 or later.
```bash
# Claude Code
claude plugin marketplace add towardsthecloud/cloudburn-plugin
claude plugin install cloudburn@towardsthecloud
# Codex
codex plugin marketplace add towardsthecloud/cloudburn-plugin
codex plugin add cloudburn@towardsthecloud
# Skill only, for agents supported by skills.sh
npx skills add towardsthecloud/cloudburn-plugin
```
See the [MCP server README](packages/mcp/README.md) for the tools and for adding the server to other MCP clients.
## 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:
```bash
cloudburn config --init
```
Inspect the current discovered config file:
```bash
cloudburn config --print
```
Inspect the starter template without writing a file:
```bash
cloudburn config --print-template
```
CloudBurn reads `.cloudburn.yml` or `.cloudburn.yaml`. By default it searches upward from the current directory until it finds a config file or reaches the git root. In CI, implicit config discovery is skipped entirely; use `--config <path>` on `scan` or `discover` to opt into an exact file instead.
```yaml
iac:
enabled-rules:
- CLDBRN-AWS-EBS-1
- CLDBRN-AWS-RDS-1
disabled-rules:
- CLDBRN-AWS-EC2-2
format: table
fail-on: high
discovery:
enabled-rules:
- CLDBRN-AWS-EBS-1
disabled-rules:
- CLDBRN-AWS-S3-1
format: json
fail-on: medium
```
- Use `enabled-rules` when you want a mode to run only a specific set of rules.
- Use `disabled-rules` when you want to subtract a few rules from the active set.
- Use public rule IDs like `CLDBRN-AWS-EBS-1`; review the [rule ID compatibility policy](docs/reference/rule-ids.md#compatibility-status) when upgrading pinned configuration.
- Use `--config <path>` if you want `scan` or `discover` to load a specific config file.
- Use `fail-on` to make CI fail for findings at or above `high`, `medium`, or `low` severity.
### Scan
Point `scan` at your IaC files. It checks Terraform (`.tf`) and CloudFormation (`.yaml`, `.json`).
```bash
cloudburn scan ./main.tf
cloudburn scan ./template.yaml
cloudburn scan ./iac --exit-code
cloudburn scan ./iac --fail-on high
cloudburn --format json scan ./iac
```
Suppress an accepted finding on one Terraform or CloudFormation resource with a comment immediately above or inside
that resource. Include a reason after the rule ID when useful:
```hcl
# cloudburn-ignore CLDBRN-AWS-EBS-1 migration scheduled
resource "aws_ebs_volume" "legacy" {
type = "gp2"
}
```
Use `cloudburn-ignore-all <reason>` for a resource-wide exception. Suppressed findings remain in JSON output under
`suppressed` for auditability and never trigger `--exit-code` or `--fail-on`. CloudFormation JSON cannot carry comments,
so inline suppressions are supported in Terraform and CloudFormation YAML only.
### Discover
`discover` runs the same rules against live AWS resources. Initialize AWS Resource Explorer first, then run against the current AWS region or one explicit region.
```bash
cloudburn discover init
cloudburn discover
cloudburn discover --region eu-central-1
cloudburn discover --service ec2,s3
cloudburn discover --enabled-rules CLDBRN-AWS-TAGGING-1
cloudburn discover --fail-on high
cloudburn --debug discover --region eu-central-1
```
The CLI targets one region at a time. Multi-region discovery remains available through the SDK.
`CLDBRN-AWS-TAGGING-1` is opt-in and requires an accessible Resource Explorer aggregator; a local-only setup cannot run account-wide tagging discovery.
Use `--debug` to relay SDK and provider execution trace details to `stderr` while keeping normal command output on `stdout`.
Generate a starter config with `cloudburn config --init`. Full details in the [config reference](docs/reference/config-schema.md).
## AWS Permissions
CloudBurn needs Resource Explorer read/write access plus read-only permissions for the services behind the rules you enable (EC2, EBS, RDS, S3, Lambda, CloudTrail, CloudWatch, etc.). `discover init` uses `resource-explorer-2:UpdateView` to enable tag visibility for the opt-in global tagging rule. Which permissions you need depends on which rules you're running.
## Contributing
Want to help? Start with [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[Apache-2.0](LICENSE)