Package Exports

All exports are available from a single entry point:

import {
  CloudBurnClient,
  builtInRuleMetadata,
  getRuleCapabilities,
  AWS_CAPABILITIES,
  parseIaC,
  evaluateScanPolicy,
  assertValidAwsRegion,
  assertSupportedAwsRegion,
  withAwsClientCredentials,
  isAwsDiscoveryErrorCode,
  createEvidenceCache,
  createMemoryEvidenceCacheStore,
  awsCorePreset,
  SEVERITIES,
} from '@cloudburn/sdk';

Exports

Everything else the package exports is a type. See Types Reference for the complete list.

CloudBurnClient

The main SDK class. See CloudBurnClient reference for full documentation.

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

const client = new CloudBurnClient();

builtInRuleMetadata

An array of BuiltInRuleMetadata objects describing all rules that ship with CloudBurn. This is a plain serializable array — no class instances, safe to JSON.stringify.

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

// List all AWS EC2 rules
const ec2Rules = builtInRuleMetadata.filter(
  (rule) => rule.provider === 'aws' && rule.service === 'ec2'
);

for (const rule of ec2Rules) {
  console.log(`${rule.id}: ${rule.name}`);
}

Each entry is typed as BuiltInRuleMetadata:

type BuiltInRuleMetadata = {
  id: string;
  name: string;
  description: string;
  message: string;
  provider: CloudProvider;
  service: string;
  severity: Severity;
  supports: Source[];
  supersedesRuleIds?: string[];
};

Entries are sorted by provider, then service, then numeric rule ID. supersedesRuleIds is only present on rules that declare precedence over another rule's identical findings.

See Rules for a browsable list of all built-in rules.

getRuleCapabilities

Lists the AWS capabilities required by a built-in rule's direct discovery dependencies. It performs no AWS calls and reads no account configuration.

getRuleCapabilities(ruleId: string): AwsCapability[]

Returns: A fresh, sorted array of unique capabilities. Optional supporting datasets do not contribute. IaC-only rules and rules without capability-gated datasets return an empty array. An unknown built-in rule ID throws an Error.

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

console.log(getRuleCapabilities('CLDBRN-AWS-COSTOPTIMIZATIONHUB-1'));
// ['cost-optimization-hub-enrollment']

Use this for rule setup guidance before scanning. Read ScanResult.capabilities after discovery to see what the collected evidence established.

AWS_CAPABILITIES

The closed capability catalog, re-exported from @cloudburn/rules:

const AWS_CAPABILITIES: readonly [
  'cost-optimization-hub-enrollment',
  'compute-optimizer-enrollment',
  'resource-explorer-aggregator',
  'cost-explorer-access',
  'budgets-access',
];

AwsCapability is (typeof AWS_CAPABILITIES)[number]. Access-only capabilities record service dependencies; they do not make Cost Explorer or Budgets rules opt-in.

parseIaC

Parses IaC files and returns structured resource objects without running any rules.

parseIaC(
  path: string,
  options?: {
    sourceKinds?: ('cloudformation' | 'terraform')[];
  }
): Promise<IaCResource[]>

type IaCResource = {
  provider: CloudProvider;
  type: string;
  name: string;
  location?: SourceLocation;
  attributeLocations?: Record<string, SourceLocation>;
  suppressions?: IaCSuppression[];
  attributes: Record<string, unknown>;
};

Parameters:

Returns: An array of parsed resource objects, each containing the cloud provider, resource type, name, attributes, source location, per-attribute locations, and any inline cloudburn-ignore suppressions found on the resource. IaCResource is a structural shape; the name itself is not exported from @cloudburn/sdk. Files the parser could not read or recognize are skipped silently here; use scanStatic() if you need those reported as ScanResult.diagnostics.

Example:

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

const resources = await parseIaC('./infrastructure');

for (const resource of resources) {
  console.log(`${resource.provider}/${resource.type} "${resource.name}"`);
  if (resource.location) {
    console.log(`  at ${resource.location.path}:${resource.location.line}`);
  }
}

evaluateScanPolicy

Evaluates a ScanResult against an inclusive severity threshold and returns whether the scan should be treated as a policy violation.

evaluateScanPolicy(result: ScanResult, threshold?: Severity): ScanPolicyResult

Parameters:

Returns: ScanPolicyResult — qualifyingFindingCount, the evaluated threshold, and violated.

scanStatic() and discover() already call this internally when CloudBurnModeConfig.failOn is set, populating ScanResult.policy automatically. Call evaluateScanPolicy() directly when you want to apply a threshold that differs from the loaded config, or re-evaluate a result you've filtered yourself.

Example:

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

const result = await client.scanStatic('./infrastructure');
const policy = evaluateScanPolicy(result, 'medium');

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

assertValidAwsRegion

Validates that a value matches the shape of an AWS region string and returns it narrowed to AwsRegion. Does not check it against the list of known AWS regions; use assertSupportedAwsRegion for that.

assertValidAwsRegion(region: string | undefined): AwsRegion

Use this to validate user-supplied or environment-supplied region values before passing them to SDK methods.

Throws: AwsDiscoveryError with code INVALID_AWS_REGION when the value is missing or does not match the AWS region pattern.

Example:

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

// throws if AWS_REGION is unset or malformed
const region = assertValidAwsRegion(process.env.AWS_REGION);

const result = await client.discover({ target: { mode: 'region', region } });

assertSupportedAwsRegion

Validates that a string is a known, supported AWS region. Throws an AwsDiscoveryError with code INVALID_AWS_REGION if the region is not in the known AWS regions list.

assertSupportedAwsRegion(region: string | undefined): AwsRegion

Use this when you need to verify that a region is not just well-formed but also a real, supported AWS region.

Throws: AwsDiscoveryError if the region is not recognized.

Example:

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

const region = assertSupportedAwsRegion('us-east-1'); // returns typed AwsRegion
assertSupportedAwsRegion('not-a-region'); // throws AwsDiscoveryError

withAwsClientCredentials

Runs a callback with ambient AWS credentials applied to every AWS client the CloudBurn SDK creates inside it, without threading credentials through each call site. Clients you construct yourself (for example new S3Client()) do not consult this context and keep their own credential chain.

withAwsClientCredentials<T>(
  credentials: AwsClientCredentials | undefined,
  fn: () => Promise<T>
): Promise<T>

Parameters:

Returns: The callback's resolved value.

Every discovery method calls this internally when you pass options.aws.credentials, so most callers never need withAwsClientCredentials directly. Reach for the per-call option first. Use this export when you need to scope credentials across a wider block of code, such as a multi-account loop that calls several SDK methods per account.

Example:

import { withAwsClientCredentials } from '@cloudburn/sdk';
import { fromTemporaryCredentials } from '@aws-sdk/credential-providers';

const credentials = fromTemporaryCredentials({
  params: { RoleArn: 'arn:aws:iam::111111111111:role/cloudburn-readonly' },
});

const result = await withAwsClientCredentials(credentials, () =>
  client.discover({ target: { mode: 'current' } }),
);

See AWS Credentials for the multi-account pattern.

isAwsDiscoveryErrorCode

Type guard that checks whether a string is a known CloudBurn discovery error code.

isAwsDiscoveryErrorCode(code: string): code is AwsDiscoveryErrorCode

Returns: true if code is a recognized discovery error code.

Use this to handle specific discovery errors in ScanDiagnostic.code:

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

const result = await client.discover();

for (const diag of result.diagnostics ?? []) {
  if (diag.code && isAwsDiscoveryErrorCode(diag.code)) {
    console.error(`Discovery error [${diag.code}]: ${diag.message}`);
  }
}

Known error codes:

AwsDiscoveryErrorCode is the union of these values. It is not exported as a type; use the guard to narrow a ScanDiagnostic.code string.

createEvidenceCache

Builds a standalone evidence cache with the same semantics discover({ cache }) uses internally. Reach for it only when you cache evidence outside a CloudBurn scan; discover() builds its own cache from AwsEvidenceCacheOptions.

createEvidenceCache(options?: EvidenceCacheOptions): EvidenceCache

Parameters:

With neither directory nor store, the cache keeps evidence in process memory only. Passing both throws. Every numeric option must be a positive safe integer, and leaseMs and pollMs must not exceed 2147483647.

Returns: An EvidenceCache whose load() reuses fresh complete evidence or coalesces one cancellable refresh across concurrent callers.

Example:

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

const cache = createEvidenceCache({ directory: '/home/example/.cache/cloudburn/evidence' });

const { value, provenance } = await cache.load({
  key: { kind: 'my-inventory', accountId, region },
  ttlMs: 600_000,
  load: async () => ({ value: await collectInventory(), complete: true }),
});

console.log(`${provenance.source} evidence collected at ${provenance.collectedAt}`);

Incomplete loads (complete: false) are returned to the caller but never stored for reuse.

createMemoryEvidenceCacheStore

Creates an isolated in-process EvidenceCacheStore with the same atomic contract as persistent stores.

createMemoryEvidenceCacheStore(): EvidenceCacheStore

Use it as the reference implementation when writing your own store, or to give several CloudBurnClient instances one shared in-memory cache:

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

const store = createMemoryEvidenceCacheStore();

const result = await client.discover({ cache: { store, mode: 'normal' } });

A single CloudBurnClient already reuses one memory store across calls when you pass cache without a directory or store, so pass a store explicitly only when clients must share it.

awsCorePreset

The default AWS rule preset, re-exported from @cloudburn/rules. Lists the rule IDs enabled by default for AWS discovery and IaC scans, excluding the rules that need explicit AWS setup before they can return anything useful.

Opt in to those through config.discovery.enabledRules, which replaces the preset rather than merging with it. See Enabling and Disabling Rules for the opt-in rules and what each one requires.

const awsCorePreset: {
  id: string;
  name: string;
  description: string;
  ruleIds: string[];
};

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

console.log(`Default rule count: ${awsCorePreset.ruleIds.length}`);

SEVERITIES

The ordered severity tuple, re-exported from @cloudburn/rules. Severity is (typeof SEVERITIES)[number].

const SEVERITIES: readonly ['high', 'medium', 'low'];

Use this to build a severity picker or to validate a user-supplied failOn value before passing it to CloudBurnModeConfig:

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

const requested = process.env.FAIL_ON;
if (requested && !SEVERITIES.includes(requested as (typeof SEVERITIES)[number])) {
  throw new Error(`Invalid severity "${requested}". Use one of: ${SEVERITIES.join(', ')}`);
}

What's next