Config Schema Reference

Source of truth: packages/sdk/src/types.ts (type), packages/sdk/src/config/defaults.ts (defaults), packages/sdk/src/config/merge.ts (merge behavior).

CloudBurnConfig Fields

Field	Type	Default	Description
iac	CloudBurnModeConfig	{}	Default rule and format settings for cloudburn scan.
discovery	CloudBurnModeConfig	{}	Default rule and format settings for cloudburn discover.

Each mode uses the same fields:

Field	Type	Default	Description
enabled-rules	string[]	unset	If present, only the listed rule IDs remain active; otherwise AWS Core is used.
disabled-rules	string[]	unset	Rule IDs to remove from the active set after enabled-rules is applied.
services	string[]	unset	Service allowlist applied before enabled-rules and disabled-rules.
format	'json' | 'table'	unset	Default CLI output format for that mode when --format is not passed.
fail-on	'high' | 'medium' | 'low'	unset	Exit with code 1 when an active finding meets or exceeds this severity.

Custom rule injection is not part of the current configuration schema. The supported rule-selection controls are the mode-local enabled-rules, disabled-rules, and services fields above.

Merge Behavior

mergeConfig(partial?) in config/merge.ts:

1. Start with defaultConfig.
2. Merge iac and discovery independently.
3. Replace enabledRules and disabledRules arrays when an override is present.
4. Replace services arrays when an override is present.
5. Replace failOn when an override is present.
6. Preserve untouched fields in the other mode or on the same mode.

The CloudBurnClient facade also merges runtime overrides through mergeConfig().

Config Loading

loadConfig(path?) in config/loader.ts behaves as follows:

• explicit path: load that exact file
• no path outside CI: search upward from process.cwd() for .cloudburn.yml or .cloudburn.yaml
• no path in CI (CI is set to a truthy value other than false, 0, or an empty string): skip implicit discovery entirely and return defaults
• stop the upward search at the git root if one exists, otherwise at the filesystem root
• if no config file is found, return defaults

This CI trust boundary means a repository fail-on setting is not active unless the caller passes that file explicitly, for example cloudburn scan ./iac --config .cloudburn.yml. Pin --fail-on directly in the workflow when the threshold must not be changeable by repository config.

Validation fails fast for:

• invalid YAML
• unknown top-level or section keys
• invalid field types
• invalid format
• invalid fail-on
• unknown services
• unknown rule IDs
• rule IDs that do not support the targeted mode
• the same rule ID appearing in both enabled-rules and disabled-rules
• both .cloudburn.yml and .cloudburn.yaml in the same directory

Starter YAML

Printed by cloudburn config --print-template (from packages/cloudburn/src/commands/config.ts):

# Static IaC scan configuration.
# enabled-rules replaces the AWS Core preset with only the listed rule IDs.
# It can also activate opt-in rules that are not in AWS Core.
# disabled-rules removes specific rule IDs from the selected set.
# services restricts scans to rules for the listed services.
# format sets the default output format when --format is not passed.
# fail-on gates CI on findings at or above high, medium, or low severity.
iac:
  enabled-rules:
    - CLDBRN-AWS-EBS-1
  disabled-rules:
    - CLDBRN-AWS-EC2-2
  services:
    - ebs
    - ec2
  format: table
  # fail-on: high

# Live AWS discovery configuration.
# Use the same rule controls here to tune discover runs separately from IaC scans.
discovery:
  enabled-rules:
    - CLDBRN-AWS-EBS-1
  disabled-rules:
    - CLDBRN-AWS-S3-1
  services:
    - ebs
    - s3
  format: json
  # fail-on: high

fail-on is inclusive: high gates only high-severity findings, medium gates high and medium, and low gates every active finding. Inline-suppressed IaC findings never trigger the gate. On the CLI, an explicit --fail-on takes precedence over --exit-code; --exit-code retains its compatibility behavior of gating on any active finding.

Live Discovery Semantics

See docs/architecture/cli.md for the full discover command behavior, region resolution order, and discover init semantics.