cloudburn discover

Synopsis

cloudburn discover [flags]
cloudburn discover <subcommand> [flags]

Description

Queries live AWS resources via AWS Resource Explorer, enriches them with service-specific data via hydrators, and evaluates cost optimization rules against the results.

Resource Explorer must be set up before running discovery with catalog-backed rules, which includes the AWS Core preset. Use cloudburn discover init to create the required indexes. A run whose enabled rules only read account-scoped datasets, such as the Cost Optimization Hub rules, skips the Resource Explorer catalog.

Flags

The CLI targets one region per run. Multi-region discovery stays available through the SDK and still needs a Resource Explorer aggregator plus an unfiltered default view in the aggregator region.

Opt-in rules

Some built-in rules sit outside the AWS Core preset because they need AWS setup CloudBurn will not perform for you. Activate them per run with --enabled-rules, or per project in discovery.enabled-rules. See Enabling and Disabling Rules for the list and why each rule is excluded.

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

--enabled-rules replaces the preset, so a run that lists only opt-in rules checks only those rules. List the other rule IDs you still want, or use a config file when the selection gets long.

Discovery timeout

A discovery run has a total deadline of five minutes. --timeout <seconds> changes it:

cloudburn discover --timeout 600

The value must be a whole number of seconds between 1 and 2147483. When the deadline expires, CloudBurn stops the remaining AWS work and exits with code 2 reporting the timeout. SDK callers set the same deadline with timeoutMs and can pass their own AbortSignal.

Evidence cache

Discovery reuses fresh, complete evidence it collected on an earlier run instead of calling AWS again. Rules and configuration are evaluated on every run, so a cached run still reflects your current rule selection.

cloudburn discover --cache refresh
cloudburn discover --cache off
cloudburn discover --cache-dir /path/to/evidence --cache-context policy-revision-2

Reusing customer evidence requires a safe scope. Temporary AWS credentials supply one through their session; long-term credentials do not, so pass --cache-context to identify the permissions the evidence was collected under. An account ID or role ARN alone is not enough. Without either, customer evidence reuse stays off and only public pricing is reused. Cache entries never contain credentials.

A cache hit is not proof of AWS coverage. Source delays and unknown resources stay visible through evidence completeness, coverage, and diagnostics. Table output ends with a freshness summary, and --format json keeps the full evidence array. See Evidence freshness.

Progress output

While discovery runs, CloudBurn streams progress to stderr when stderr is attached to an interactive terminal: catalog ready, datasets completed, and one line per rule as it finishes with its ID, status, and finding count.

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)

A rule line reports triggered, passed, not_applicable, or unknown. These lines are provisional: they describe the work finished so far, and the final report plus the exit code are authoritative. Progress is silent for piped or scripted runs, --debug tracing takes priority over progress lines when both would apply, and --format json still writes one final result to stdout.

Subcommands

init

Synopsis

cloudburn discover init [flags]

Description

Sets up AWS Resource Explorer indexes across all enabled regions and promotes the index in the specified region to the aggregator. By default, the current active region (from your AWS profile or AWS_REGION environment variable) becomes the aggregator. If indexes already exist, they are reused.

See the Resource Explorer Setup guide for a detailed walkthrough.

Flags

Example

cloudburn discover init
cloudburn discover init --region eu-west-1

status

Synopsis

cloudburn discover status

Description

Displays the current state of Resource Explorer in your account, including which regions are indexed and whether an aggregator is configured.

Output format

Table output prints an account summary, then one row per enabled region:

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

+--------------+---------------------+---------+------------+
| Region       | IndexType           | Status  | ViewStatus |
+--------------+---------------------+---------+------------+
| eu-west-1    | aggregator (active) | indexed | present    |
| eu-central-1 | local               | indexed | present    |
+--------------+---------------------+---------+------------+

Columns with no data for any region are dropped, so a Notes column appears only when CloudBurn has something to report about a region.

A warning field is added to the summary when Resource Explorer setup is incomplete. --format json returns the same data as { "summary": ..., "regions": [...] }.

Example

cloudburn discover status
cloudburn --format json discover status

supported-resource-types

Synopsis

cloudburn discover supported-resource-types

Description

Lists all AWS resource types that CloudBurn's discovery mode supports. Use this to understand which services and resource types are covered before running a scan. Output has two columns, ResourceType and Service; a resource type CloudBurn cannot map to a service is reported as unknown.

Example

cloudburn discover supported-resource-types

Exit codes

cloudburn discover 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 missing credentials, a Resource Explorer that is not set up, or an expired --timeout deadline. The Exit codes guide has the full contract.

Examples

Run discovery in the current region:

cloudburn discover

Scan a specific region with JSON output:

cloudburn --format json discover --region us-west-2

Filter to EC2 and EBS rules only:

cloudburn discover --service ec2,ebs

Enable the opt-in account-wide tagging rule and fail CI when it finds untagged resources. --enabled-rules replaces the preset, so the selected set contains only this low-severity rule — the gate must be low to ever trip:

cloudburn discover --enabled-rules CLDBRN-AWS-TAGGING-1 --fail-on low

Force a fresh collection and give the run ten minutes:

cloudburn discover --cache refresh --timeout 600

What's next