Skip to content

config-schema.md

Latest commit

 

History

History
111 lines (88 loc) · 5.22 KB

config-schema.md

File metadata and controls

111 lines (88 loc) · 5.22 KB
Raw

Config Schema Reference

Implementation sources: SDK types, defaults, validation, loading, and merging. This reference is manually maintained alongside those sources.

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.