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. AWS clients and credential providers are imported lazily at that point, so constructing a client and running scanStatic() never load them.

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`),
});

Discovery runs also emit a sdk: live scan timing line carrying firstRuleMs and totalMs, both measured from the moment rule selection completed. firstRuleMs is null when no provisional rule evaluation was requested or emitted.

Shared discovery options

discover, getDiscoveryStatus, initializeDiscovery, and listSupportedDiscoveryResourceTypes all accept the same AwsDiscoveryExecutionOptions on top of their own options.

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>. When config.iac.failOn (or the loaded config's iac.fail-on) is set, the result's policy field is populated automatically — see ScanPolicyResult. IaC findings matched by an inline cloudburn-ignore comment are withheld from providers and listed in result.suppressed instead — see SuppressedFinding.

Example:

const client = new CloudBurnClient();

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

discover

discover(options?: AwsDiscoveryExecutionOptions & {
  target?: AwsDiscoveryTarget;
  config?: Partial<CloudBurnConfig>;
  configPath?: string;
  includeEvaluationResources?: boolean;
  onProgress?: (event: AwsDiscoveryProgressEvent) => void;
  cache?: AwsEvidenceCacheOptions;
}): Promise<ScanResult>

Scans live AWS resources using AWS Resource Explorer. Requires AWS credentials, and an initialized Resource Explorer for catalog-backed rules (the AWS Core preset). A run whose enabled rules only read account-scoped datasets skips the Resource Explorer catalog.

Parameters:

Plus the shared aws.credentials, signal, and timeoutMs options described above.

Target modes:

Returns: Promise<ScanResult>. result.capabilities reports readiness projected from collected AWS evidence; see AwsCapabilityOutcome. When config.discovery.failOn (or the loaded config's discovery.fail-on) is set, the result's policy field is populated automatically, see ScanPolicyResult. result.evaluations is present when includeEvaluationResources is set, see ScanEvaluations. result.evidence is present when cache is configured, see AwsEvidenceProvenance.

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'] } },
});

Scoped AWS credentials:

const result = await client.discover({
  target: { mode: 'current' },
  aws: { credentials: fromTemporaryCredentials({ params: { RoleArn: roleArn } }) },
});

See AWS Credentials for the multi-account pattern and the withAwsClientCredentials() alternative.

Progress events:

const result = await client.discover({
  onProgress: (event) => {
    if (event.kind === 'catalog') {
      console.log(`Catalog loaded: ${event.resourceCount} resources in ${event.searchRegion}`);
    } else if (event.kind === 'dataset') {
      console.log(`Dataset ${event.datasetKey} (${event.completedDatasets}/${event.totalDatasets}) loaded`);
    } else {
      console.log(`${event.ruleId}: ${event.status}, ${event.findingCount} findings after ${event.elapsedMs} ms`);
    }
  },
});

Rule events are provisional; the resolved ScanResult replaces them. See AwsDiscoveryProgressEvent.

Reusable evidence:

const result = await client.discover({
  cache: {
    directory: '/home/example/.cache/cloudburn/evidence',
    mode: 'normal',
    authorizationContext: 'production-readonly-policy-v3',
    ttlMs: { catalog: 180_000, datasets: { 'aws-ebs-volumes': 600_000 } },
  },
});

Reuse is off unless cache is passed. See AwsEvidenceCacheOptions.

Evaluation evidence:

const result = await client.discover({ includeEvaluationResources: true });

for (const evaluation of result.evaluations?.rules ?? []) {
  console.log(`${evaluation.ruleId}: ${evaluation.status}`);
}

Every selected rule is reported as triggered, passed, unknown, or not_applicable. Code that validates status strings must accept unknown.

initializeDiscovery

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

Attempts AWS Resource Explorer setup across enabled regions, with an aggregator in the selected region and local indexes elsewhere.

Call this during account setup rather than before every scan. Existing indexes can be reused with status: 'EXISTING', but the call may still promote a local index to an aggregator or update the default view to include tags. An explicit region that differs from an existing aggregator rejects with RESOURCE_EXPLORER_AGGREGATOR_SWITCH_REQUIRES_DELAY.

When cross-region setup or promotion is denied, the call can fall back to a local index and return a warning. Inspect indexType, coverage, and verificationStatus before assuming cross-region discovery is ready.

Parameters:

Plus the shared aws.credentials, signal, and timeoutMs options. Cancelling initialization stops further setup work; mutations AWS already accepted stay in place and a later call observes that state.

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?: AwsDiscoveryExecutionOptions & {
  region?: string;
}): Promise<AwsDiscoveryStatus>

Returns the current state of AWS Resource Explorer indexing. Regions are inspected concurrently, up to 5 at a time, and returned sorted by name. Each regional probe makes at most 2 attempts, so persistent throttling yields a status result promptly instead of stalling.

Parameters:

Plus the shared aws.credentials, signal, and timeoutMs options.

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(
  options?: AwsDiscoveryExecutionOptions
): Promise<AwsSupportedResourceType[]>

Returns AWS resource types supported by Resource Explorer. This indexing catalog does not establish which resource types CloudBurn rules evaluate; see Rules for rule coverage. Accepts the shared aws.credentials, signal, and timeoutMs options.

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 config file or reaches the git root (a directory containing .git). If no config is found, default config values are returned. A directory holding both .cloudburn.yml and .cloudburn.yaml throws.

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