Understanding Rules

This page explains the structure of a rule, what a finding looks like, and how to control which rules run.

Rule Anatomy

Every CloudBurn rule exposes the following properties:

Field	Type	Description
`id`	`string`	Unique rule identifier (e.g., `CLDBRN-AWS-EC2-3`)
`name`	`string`	Human-readable rule name
`description`	`string`	What the rule checks and why it matters
`message`	`string`	Finding message template shown in output
`provider`	`string`	Cloud provider (`aws`)
`service`	`string`	AWS service short name (e.g., `ec2`, `s3`)
`supports`	`string[]`	Scan types this rule supports: `discovery`, `iac`, or both

Finding Anatomy

When a rule detects a problem, it produces a finding. The overall result for a scan run looks like this:

{
  "ruleId": "CLDBRN-AWS-EC2-3",
  "service": "ec2",
  "source": "discovery",
  "message": "Elastic IP address is not associated with any resource",
  "findings": [
    {
      "resourceId": "eipalloc-0abc1234def56789",
      "accountId": "123456789012",
      "region": "us-east-1",
      "location": "arn:aws:ec2:us-east-1:123456789012:elastic-ip/eipalloc-0abc1234def56789"
    }
  ]
}

Field	Description
`ruleId`	The rule that produced this finding
`service`	AWS service the finding belongs to
`source`	How the finding was detected: `discovery` or `iac`
`message`	Human-readable description of the problem
`findings[]`	One entry per affected resource
`findings[].resourceId`	The specific resource ID (instance ID, bucket name, etc.)
`findings[].accountId`	AWS account that owns the resource
`findings[].region`	AWS region where the resource lives
`findings[].location`	Full ARN or path to the resource

Discovery vs IaC Scan Types

Discovery

Discovery rules scan live AWS resources. CloudBurn uses AWS Resource Explorer to enumerate resources and then calls service APIs to gather the data each rule needs.

Requires AWS credentials with read access to the scanned accounts
Reflects the actual state of your infrastructure right now
Can detect runtime issues like idle resources, missing attachments, and low utilization

IaC

IaC rules scan Terraform (.tf) and CloudFormation (.json and .yaml) template files statically. No AWS credentials required.

Works in CI pipelines before resources are deployed
Catches misconfigurations at the point of authorship
Covers Terraform resource types like aws_instance, aws_lambda_function, and CloudFormation types like AWS::EC2::Instance

Both

Some rules support both modes. In discovery mode they evaluate the live resource; in IaC mode they evaluate the template. The rule ID and finding format are identical regardless of source.

Enabling and Disabling Rules

Config File (`.cloudburn.yml`)

Rules are configured per scan mode (iac or discovery):

iac:
  # Run only these rules for IaC scans
  enabled-rules:
    - CLDBRN-AWS-EC2-1
    - CLDBRN-AWS-S3-1

discovery:
  # Exclude specific rules from discovery scans
  disabled-rules:
    - CLDBRN-AWS-EC2-11
    - CLDBRN-AWS-EC2-12

Use enabled-rules when you want an explicit allowlist. Use disabled-rules when you want to suppress a small number of rules while running everything else. See the Configuration reference for the full schema.

CLI Flags

# Run only specific rules
cloudburn discover --enabled-rules CLDBRN-AWS-EC2-3,CLDBRN-AWS-S3-1

# Exclude specific rules
cloudburn scan --disabled-rules CLDBRN-AWS-EC2-11,CLDBRN-AWS-EC2-12

SDK

import { CloudBurnClient } from '@cloudburn/sdk';

const client = new CloudBurnClient();

// Discovery scan with rule filter
await client.discover({
  config: {
    discovery: {
      enabledRules: ['CLDBRN-AWS-EC2-3', 'CLDBRN-AWS-S3-1'],
    },
  },
});

// IaC scan with rule exclusion
await client.scanStatic('./iac', {
  iac: {
    disabledRules: ['CLDBRN-AWS-EC2-11'],
  },
});

Service Filtering

You can limit scans to specific AWS services rather than filtering by individual rule IDs.

Config file:

discovery:
  services:
    - ec2
    - s3
    - rds

CLI:

cloudburn discover --service ec2,s3

SDK:

await client.discover({
  config: {
    discovery: {
      services: ['ec2', 's3'],
    },
  },
});

Conservative Evaluation

Rules skip resources when the data needed to make a confident determination is incomplete. This means CloudBurn produces fewer false positives — if a rule cannot conclusively identify waste, it does not flag the resource. You will not be chased to remediate something that turns out to be fine.

What's Next

Rules Overview — full list of rules by service
CLI scan command — run IaC scans
CLI discover command — scan live resources
SDK Reference — integrate CloudBurn programmatically

Understanding Rules