Custom Configuration

CloudBurn configuration controls which rules run and which services are scanned. You can supply config as an inline object, load it from a file, or combine both.

Load config from disk

loadConfig() finds and loads the nearest .cloudburn.yml or .cloudburn.yaml file by walking up the directory tree from process.cwd(), stopping at the git root:

import { CloudBurnClient } from '@cloudburn/sdk';

const client = new CloudBurnClient();
const config = await client.loadConfig();

Provide an explicit path to skip the walk-up:

const config = await client.loadConfig('/project/.cloudburn.yml');

A directory holding both .cloudburn.yml and .cloudburn.yaml throws rather than picking one. In CI (when the CI environment variable is set to anything other than an empty string, 0, or false), the walk-up is skipped entirely and defaults are used, so pass an explicit path when you need config in CI.

Inline config

Pass a config object directly to scanStatic() or discover(). This takes precedence over any loaded config file:

const result = await client.scanStatic('./infrastructure', {
  iac: {
    services: ['ec2', 'ebs'],
  },
});

The same pattern works for discovery scans:

const result = await client.discover({
  config: {
    discovery: {
      services: ['ec2', 'rds'],
    },
  },
});

Override specific rules

Enable only specific rules (all others are skipped):

const result = await client.scanStatic('./iac', {
  iac: {
    enabledRules: ['CLDBRN-AWS-EBS-1', 'CLDBRN-AWS-EC2-1'],
    services: ['ebs', 'ec2'],
  },
});

Disable specific rules (all others still run):

const result = await client.scanStatic('./iac', {
  iac: {
    disabledRules: ['CLDBRN-AWS-EC2-2'],
  },
});

Fail on severity

Set failOn on a mode's config to turn active findings into a policy violation instead of just a result list. scanStatic() and discover() populate result.policy automatically whenever failOn is set for the mode being scanned:

const result = await client.scanStatic('./iac', {
  iac: { failOn: 'medium' },
});

if (result.policy?.violated) {
  console.error(`${result.policy.qualifyingFindingCount} findings at or above 'medium' severity`);
  process.exitCode = 1;
}

failOn accepts 'high', 'medium', or 'low' — set to 'medium' to fail on high and medium findings while leaving low-severity findings out of the count. Omit failOn (the default) to skip policy evaluation entirely; result.policy stays undefined. To evaluate a threshold that differs from the loaded config, or to re-check a result you've filtered yourself, call evaluateScanPolicy() directly instead of relying on the automatic behavior.

Merge file config with inline overrides

Load from disk and apply targeted overrides without losing the rest of the config:

const config = await client.loadConfig();

const result = await client.scanStatic('./iac', {
  ...config,
  iac: {
    ...config.iac,
    services: ['ec2'],
  },
});

Config file format

The SDK uses the same config format as the CLI. See Configuration for the full YAML schema.

What's next