CloudBurnClient

CloudBurnClient is the main entry point for the CloudBurn SDK. All scan and discovery operations are performed through this class.

Constructor

new CloudBurnClient(options?: {
  debugLogger?: (message: string) => void;
})

Parameters:

AWS credentials are resolved automatically from the default credential chain when discovery methods are called.

Example:

// Default — no debug logging
const client = new CloudBurnClient();

// With debug logging to stderr
const client = new CloudBurnClient({
  debugLogger: (msg) => process.stderr.write(`[debug] ${msg}\n`),
});

Methods overview

scanStatic

scanStatic(
  path: string,
  config?: Partial<CloudBurnConfig>,
  options?: { configPath?: string }
): Promise<ScanResult>

Analyzes IaC files at the given path. Does not require AWS credentials.

Parameters:

Returns: Promise<ScanResult>

Example:

const client = new CloudBurnClient();

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

discover

discover(options?: {
  target?: AwsDiscoveryTarget;
  config?: Partial<CloudBurnConfig>;
  configPath?: string;
}): Promise<ScanResult>

Scans live AWS resources using AWS Resource Explorer. Requires AWS credentials and an initialized Resource Explorer.

Parameters:

Target modes:

Returns: Promise<ScanResult>

If some services or regions are inaccessible, they appear in result.diagnostics with status: 'access_denied' rather than causing the scan to fail.

Example:

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

initializeDiscovery

initializeDiscovery(options?: {
  region?: string;
}): Promise<AwsDiscoveryInitialization>

Sets up AWS Resource Explorer for CloudBurn discovery scans. Creates an aggregator index in the specified region and local indexes in all other enabled regions.

Call this once per AWS account. On subsequent calls it detects existing setup and returns status: 'EXISTING' without making changes.

Parameters:

Returns: Promise<AwsDiscoveryInitialization>

The returned object includes status ('CREATED' or 'EXISTING'), the aggregatorRegion, coverage summary, and verificationStatus indicating whether the index was confirmed as active.

Example:

const init = await client.initializeDiscovery({ region: 'us-east-1' });
console.log(`Status: ${init.status}`);
console.log(`Aggregator: ${init.aggregatorRegion}`);
console.log(`Coverage: ${init.coverage}`);

getDiscoveryStatus

getDiscoveryStatus(options?: {
  region?: string;
}): Promise<AwsDiscoveryStatus>

Returns the current state of AWS Resource Explorer indexing.

Parameters:

Returns: Promise<AwsDiscoveryStatus>

Coverage values:

Example:

const status = await client.getDiscoveryStatus();
console.log(`Coverage: ${status.coverage}`);
console.log(`Indexed regions: ${status.indexedRegionCount} / ${status.totalRegionCount}`);

listSupportedDiscoveryResourceTypes

listSupportedDiscoveryResourceTypes(): Promise<AwsSupportedResourceType[]>

Returns all AWS resource types that CloudBurn supports for discovery scans.

Returns: Promise<AwsSupportedResourceType[]>

loadConfig

loadConfig(path?: string): Promise<CloudBurnConfig>

Loads a CloudBurn configuration file from disk.

Parameters:

Returns: Promise<CloudBurnConfig>

The walk-up algorithm starts at the current working directory and checks each parent directory until it finds a .cloudburn.yml file or reaches the git root (a directory containing .git). If no config is found, default config values are returned.

In CI environments (when the CI environment variable is set and truthy), implicit config discovery is skipped entirely and defaults are used. Pass an explicit path to load config in CI.

Example:

// Auto-discover config
const config = await client.loadConfig();

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

What's next