cloudburn scan

Synopsis

cloudburn scan [path] [flags]

Description

Runs a static analysis scan against Terraform (.tf) and CloudFormation (.json, .yaml, .yml) files. CloudBurn auto-detects file types — you don't need to specify which IaC format you're using.

When no [path] is provided, CloudBurn scans the current working directory recursively.

Arguments

Flags

By default, CloudBurn runs the AWS Core preset for the mode you use, which excludes the opt-in rules that need AWS-side setup. Those rules are all discovery-only, so they apply to cloudburn discover, not to static scans — config validation rejects rules that do not support the current scan mode. See Rules for the full catalog.

Suppressing findings inline

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"
}

cloudburn-ignore <rule-id> [reason] suppresses a single rule for the annotated resource. cloudburn-ignore-all [reason] suppresses every rule for that resource. Suppressed findings stay visible in JSON output under suppressed, are counted in table output, and never fail --exit-code or --fail-on gates. CloudFormation JSON does not support comments and therefore cannot carry inline suppressions — use CloudFormation YAML or disabled-rules instead.

Exit codes

cloudburn scan exits 0 when no finding trips a gate, 1 when an active finding satisfies --exit-code or --fail-on, and 2 on runtime or usage errors such as a missing path or invalid config. The Exit codes guide has the full contract, including how suppressed findings interact with gates.

Examples

Scan the current directory:

cloudburn scan

Scan a specific path:

cloudburn scan ./infrastructure

Scan only EBS rules and fail CI on any finding:

cloudburn scan --service ebs --exit-code

Fail CI only on high-severity findings:

cloudburn scan --fail-on high

Output as JSON:

cloudburn --format json scan ./iac

Run only specific rules:

cloudburn scan --enabled-rules CLDBRN-AWS-EBS-1,CLDBRN-AWS-EC2-2

Use a non-default config file (required in CI to apply its rule selection, output defaults, or severity gate):

cloudburn scan --config ./configs/.cloudburn.yml

Example JSON output structure (the raw ScanResult object is serialized directly):

{
  "providers": [
    {
      "provider": "aws",
      "rules": [
        {
          "ruleId": "CLDBRN-AWS-EBS-1",
          "service": "ebs",
          "severity": "medium",
          "source": "iac",
          "message": "EBS volumes should use current-generation storage.",
          "findings": [
            {
              "resourceId": "aws_ebs_volume.main",
              "location": {
                "path": "modules/storage/main.tf",
                "line": 12,
                "column": 1
              }
            }
          ]
        }
      ]
    }
  ]
}

When any finding is suppressed by an inline cloudburn-ignore comment, the JSON result also carries a top-level suppressed array. A config-file severity gate can populate policy, but explicit --fail-on and --exit-code flags are applied after serialization and do not replace that JSON field. Use the exit code for the final CLI gate verdict:

{
  "providers": [],
  "suppressed": [
    {
      "provider": "aws",
      "ruleId": "CLDBRN-AWS-EBS-1",
      "service": "ebs",
      "severity": "medium",
      "source": "iac",
      "message": "EBS volumes should use current-generation storage.",
      "finding": {
        "resourceId": "aws_ebs_volume.legacy",
        "location": { "path": "modules/storage/main.tf", "line": 12, "column": 1 }
      },
      "suppression": { "kind": "rule", "ruleId": "CLDBRN-AWS-EBS-1", "reason": "migration scheduled", "location": { "path": "modules/storage/main.tf", "line": 11, "column": 1 } }
    }
  ]
}

Rules

Rules evaluated by this scan are documented in Rules.

What's next