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 attempts to set up indexes across enabled regions and an aggregator, or reuses the existing setup. Check coverage and warnings because restricted permissions can leave only a local index. The CLI scans one region per run; an aggregator also enables multi-region scans through the SDK. 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
| Resource Explorer Setup | Detailed guide on configuring Resource Explorer indexes |
| cloudburn discover | Full reference for all discover flags and subcommands |
| Exit Codes | Use exit codes in CI/CD pipelines |