Quickstart: Discover AWS Resources

This tutorial walks you through scanning your live AWS account for cost optimization opportunities using CloudBurn's discovery mode.

Prerequisites

• CloudBurn CLI installed (see Installation)
• AWS credentials configured (via ~/.aws/credentials, environment variables, or an IAM role)
• Permissions to use AWS Resource Explorer in your account

How discovery works

Step 1: Set up Resource Explorer

CloudBurn uses AWS Resource Explorer to list resources across your account. Run the init command to create the required indexes:

cloudburn discover init

This creates local indexes across all enabled regions and promotes your current region to the aggregator, enabling multi-region scans. See the Resource Explorer Setup guide for details.

Step 2: Check status

Verify that Resource Explorer is ready:

cloudburn discover status

Expected output when ready:

+-----------------------+-----------+
| Field                 | Value     |
+-----------------------+-----------+
| accessibleRegionCount | 17        |
| aggregatorRegion      | eu-west-1 |
| coverage              | full      |
| indexedRegionCount    | 17        |
| totalRegionCount      | 17        |
+-----------------------+-----------+

Indexing can take a few minutes after init. Re-run status until the regions you care about report indexed. See Output format for every field.

Step 3: Run discovery

Once the index is active, run the discovery scan:

cloudburn discover

CloudBurn queries Resource Explorer, enriches the resource data via hydrators, then evaluates all applicable rules. Findings are printed as a table.

On an interactive terminal, progress goes to stderr while the run works through its catalog, datasets, and rules:

discover: catalog ready with 412 resources from eu-central-1
discover: datasets 7/18 loaded (aws-ec2-instances)
discover: rules 12/78 (CLDBRN-AWS-EBS-1: triggered, findings: 3, provisional)

Those rule lines are provisional, so treat the final table and exit code as the result. See Progress output.

A run has a five-minute deadline. If your account is large enough to need longer, raise it with --timeout <seconds>:

cloudburn discover --timeout 600

Step 4: Scan a specific region

To scan a specific region instead of your current region:

cloudburn discover --region us-west-2

Step 5: Filter by service

To limit the scan to specific AWS services:

cloudburn discover --service ec2,ebs

Expected output:

+----------+------------------+----------+-----------+---------+--------------+-----------------------+--------------+--------------+----------------------------------------------------+
| Provider | RuleId           | Severity | Source    | Service | ResourceType | ResourceId            | AccountId    | Region       | Message                                            |
+----------+------------------+----------+-----------+---------+--------------+-----------------------+--------------+--------------+----------------------------------------------------+
| aws      | CLDBRN-AWS-EBS-1 | medium   | discovery | ebs     | ec2:volume   | vol-0abc123def456789a | 123456789012 | eu-central-1 | EBS volumes should use current-generation storage. |
+----------+------------------+----------+-----------+---------+--------------+-----------------------+--------------+--------------+----------------------------------------------------+

Evidence: 0 cached, 4 collected; 0 incomplete.
Oldest observation: 2026-02-04T09:12:31.004Z

The trailing summary tells you where the run's evidence came from. See Evidence freshness.

Step 6: Re-run without paying for the same AWS calls

Discovery caches the evidence it collects per user, so the next run reuses whatever is still fresh and complete. Rules and configuration are re-evaluated every time, so a cached run still reflects your current rule selection. Customer evidence is only reused inside a safe authorization scope: temporary credentials (an assumed role, SSO, or OIDC session) carry one, while long-term access keys need --cache-context naming the permission set they run under.

# Reuse fresh evidence (the default) with temporary credentials
cloudburn discover

# Reuse fresh evidence with long-term access keys
cloudburn discover --cache-context readonly-policy-v1

# Collect everything again
cloudburn discover --cache refresh

Evidence cache covers the cache directory, the authorization context that long-term credentials need, and how to turn caching off.

Step 7: Turn on an opt-in rule

The default AWS Core preset leaves out the rules that need AWS setup CloudBurn will not do for you, such as Cost Optimization Hub enrollment:

cloudburn discover --enabled-rules CLDBRN-AWS-COSTOPTIMIZATIONHUB-3

--enabled-rules replaces the preset, so that run checks only the rule you listed. See Opt-in rules for the full list and what each one requires.

What's next