Types | CloudBurn SDK

All types are exported from @cloudburn/sdk and are available as TypeScript type imports.

Config types

CloudBurnConfig

type CloudBurnConfig = {
  discovery: CloudBurnModeConfig;
  iac: CloudBurnModeConfig;
};

Top-level configuration object. discovery controls live AWS scans; iac controls static IaC scans.

CloudBurnModeConfig

type CloudBurnModeConfig = {
  enabledRules?: string[];
  disabledRules?: string[];
  failOn?: Severity;
  services?: string[];
  format?: ConfigOutputFormat;
};

Field	Type	Description
`enabledRules`	`string[]`	Allowlist of rule IDs to run. If set, only these rules execute.
`disabledRules`	`string[]`	Denylist of rule IDs to skip.
`failOn`	`Severity`	Lowest severity that makes the scan report a policy violation. When set, `scanStatic()` and `discover()` populate `ScanResult.policy` automatically.
`services`	`string[]`	Filter to specific AWS services (e.g. `['ec2', 'ebs']`).
`format`	`ConfigOutputFormat`	Output format for CLI use.

ConfigOutputFormat

type ConfigOutputFormat = 'json' | 'table';

Scan result types

ScanResult

type ScanResult = {
  diagnostics?: ScanDiagnostic[];
  policy?: ScanPolicyResult;
  providers: ProviderFindingGroup[];
  suppressed?: SuppressedFinding[];
};

Field	Type	Description
`diagnostics`	`ScanDiagnostic[]`	Access errors or warnings that did not stop the scan.
`policy`	`ScanPolicyResult`	Present when `failOn` is configured for the scanned mode. See ScanPolicyResult.
`providers`	`ProviderFindingGroup[]`	Findings grouped by cloud provider.
`suppressed`	`SuppressedFinding[]`	IaC findings matched by an inline `cloudburn-ignore` comment. See SuppressedFinding.

ScanPolicyResult

type ScanPolicyResult = {
  qualifyingFindingCount: number;
  threshold?: Severity;
  violated: boolean;
};

Field	Type	Description
`qualifyingFindingCount`	`number`	Number of active findings at or above `threshold`.
`threshold`	`Severity`	The `failOn` severity that was evaluated.
`violated`	`boolean`	`true` when `qualifyingFindingCount` is greater than zero.

Returned by evaluateScanPolicy() and populated automatically on ScanResult.policy when CloudBurnModeConfig.failOn is set for the scanned mode.

SuppressedFinding

type SuppressedFinding = {
  finding: FindingMatch;
  message: string;
  provider: CloudProvider;
  ruleId: string;
  service: string;
  severity: Severity;
  source: 'iac';
  suppression: {
    kind: 'all' | 'rule';
    location: SourceLocation;
    reason?: string;
    ruleId?: string; // present when suppression.kind is 'rule'
  };
};

One resource-level match that was withheld from ScanResult.providers because of an inline cloudburn-ignore or cloudburn-ignore-all comment directly above (or inside) the matching resource block in an IaC file. source is always 'iac' — suppression comments only apply to static scans. suppression.location points at the comment itself, not the resource.

ProviderFindingGroup

type ProviderFindingGroup = {
  provider: CloudProvider;
  rules: Finding[];
};

Field	Type	Description
`provider`	`CloudProvider`	The cloud provider for this group.
`rules`	`Finding[]`	All rule findings for this provider.

Finding

type Finding = {
  ruleId: string;
  service: string;
  source: Source;
  severity: Severity;
  message: string;
  findings: FindingMatch[];
};

Field	Type	Description
`ruleId`	`string`	The rule identifier (e.g. `CLDBRN-AWS-EBS-1`).
`service`	`string`	AWS service name (e.g. `ebs`).
`source`	`Source`	Whether this came from `'iac'` or `'discovery'`.
`severity`	`Severity`	The rule's configured severity.
`message`	`string`	Human-readable description of the issue.
`findings`	`FindingMatch[]`	Individual resources that triggered this rule.

FindingMatch

type FindingMatch = {
  resourceId: string;
  accountId?: string;
  region?: string;
  location?: SourceLocation;
};

Field	Type	Description
`resourceId`	`string`	The resource identifier or name.
`accountId`	`string`	AWS account ID (discovery scans only).
`region`	`string`	AWS region (discovery scans only).
`location`	`SourceLocation`	File location (IaC scans only).

SourceLocation

type SourceLocation = {
  path: string;
  line: number;
  column: number;
  endLine?: number;
  endColumn?: number;
};

Points to the specific position in an IaC file where the issue was found.

ScanDiagnostic

type ScanDiagnostic = {
  provider: CloudProvider;
  service: string;
  source: Source;
  status: 'access_denied' | 'error' | 'skipped' | 'throttled';
  message: string;
  code?: string;
  details?: string;
  region?: string;
  ruleId?: string;
};

Represents a non-fatal error encountered during scanning, such as insufficient IAM permissions for a specific service or region. status distinguishes access errors ('access_denied') from other failure modes: a dataset that could not be loaded ('error'), a rule that was intentionally skipped ('skipped'), or an AWS API rate limit ('throttled'). ruleId is set when a diagnostic traces back to a specific rule's evaluation rather than a whole dataset.

Rule types

Rule

type Rule = {
  id: string;
  name: string;
  description: string;
  message: string;
  provider: CloudProvider;
  service: string;
  severity: Severity;
  supports: Source[];
  // ...additional internal fields
};

Field	Type	Description
`id`	`string`	Unique rule identifier.
`name`	`string`	Short display name.
`description`	`string`	Detailed explanation of what the rule checks.
`message`	`string`	The finding message shown in results.
`provider`	`CloudProvider`	Cloud provider this rule targets.
`service`	`string`	AWS service this rule targets.
`severity`	`Severity`	The rule's configured severity.
`supports`	`Source[]`	Whether the rule supports `'iac'`, `'discovery'`, or both.

BuiltInRuleMetadata

type BuiltInRuleMetadata = Pick<Rule, 'id' | 'name' | 'description' | 'provider' | 'service' | 'severity' | 'supports'>;

Serializable metadata subset of Rule. This is the type of entries in the builtInRuleMetadata constant array.

Source

type Source = 'discovery' | 'iac';

Severity

type Severity = 'high' | 'medium' | 'low';

Ordered from most to least severe. Used by Rule.severity, Finding.severity, CloudBurnModeConfig.failOn, and ScanPolicyResult.threshold. Re-exported from @cloudburn/rules alongside the SEVERITIES constant, which lists the values in this same order.

CloudProvider

type CloudProvider = 'aws' | 'azure' | 'gcp';

RegisteredRules

type RegisteredRules = {
  activeRules: Rule[];
};

Discovery types

AwsRegion

type AwsRegion = 'af-south-1' | 'ap-east-1' | 'ap-northeast-1' | ... | 'us-west-2';

A string literal union of all known AWS region identifiers (e.g. 'us-east-1', 'eu-west-1'). Use assertSupportedAwsRegion() to validate and narrow a plain string to AwsRegion.

AwsDiscoveryTarget

type AwsDiscoveryTarget =
  | { mode: 'current' }
  | { mode: 'all' }
  | { mode: 'region'; region: string }
  | { mode: 'regions'; regions: AwsRegion[] };

Passed to discover() to control which regions are scanned. The regions mode scans a specific set of regions by their identifiers.

AwsClientCredentials

type AwsClientCredentials = AwsCredentialIdentity | AwsCredentialIdentityProvider;

An AWS SDK v3 credentials object or provider function, re-exported from @aws-sdk/types. Pass this to discover({ aws: { credentials } }) or to withAwsClientCredentials() to scope a discovery run to specific credentials instead of the ambient credential provider chain. See AWS Credentials.

AwsDiscoveryProgressEvent

type AwsDiscoveryProgressEvent =
  | { kind: 'catalog'; resourceCount: number; searchRegion: string }
  | { kind: 'dataset'; completedDatasets: number; datasetKey: string; totalDatasets: number };

Passed to discover()'s onProgress callback while a live discovery run loads its resource catalog and datasets, so callers can render feedback before the final ScanResult arrives. A 'catalog' event fires once the Resource Explorer catalog is loaded; 'dataset' events fire as each discovery dataset (EC2 instances, RDS snapshots, and so on) finishes loading.

AwsDiscoveryRegion

type AwsDiscoveryRegion = {
  region: string;
  type: 'local' | 'aggregator';
};

Describes one enabled Resource Explorer index region.

AwsDiscoveryRegionStatus

type AwsDiscoveryRegionStatus = {
  region: string;
  indexType?: 'local' | 'aggregator';
  isAggregator?: boolean;
  status: 'indexed' | 'not_indexed' | 'access_denied' | 'error' | 'unsupported';
  viewStatus?: 'present' | 'missing' | 'filtered' | 'access_denied' | 'error' | 'unknown';
  errorCode?: string;
  notes?: string;
};

Per-region breakdown within AwsDiscoveryStatus.

AwsDiscoveryStatus

type AwsDiscoveryStatus = {
  aggregatorRegion?: string;
  accessibleRegionCount: number;
  coverage: 'full' | 'partial' | 'local_only' | 'none';
  indexedRegionCount: number;
  regions: AwsDiscoveryRegionStatus[];
  totalRegionCount: number;
  warning?: string;
};

Field	Type	Description
`aggregatorRegion`	`string`	Region hosting the aggregator index, if one exists.
`accessibleRegionCount`	`number`	Number of regions the SDK could access.
`coverage`	`'full' \| 'partial' \| 'local_only' \| 'none'`	Overall coverage level.
`indexedRegionCount`	`number`	Number of regions with an active index.
`regions`	`AwsDiscoveryRegionStatus[]`	Per-region status details.
`totalRegionCount`	`number`	Total number of AWS regions checked.
`warning`	`string`	Optional warning message.

AwsDiscoveryInitialization

type AwsDiscoveryInitialization = {
  status: 'CREATED' | 'EXISTING';
  indexType: 'local' | 'aggregator';
  aggregatorRegion: string;
  aggregatorAction: 'created' | 'none' | 'promoted' | 'unchanged';
  createdIndexCount: number;
  reusedIndexCount: number;
  regions: string[];
  coverage: AwsDiscoveryStatus['coverage'];
  verificationStatus: 'verified' | 'timed_out';
  observedStatus: AwsDiscoveryStatus;
  taskId?: string;
  warning?: string;
};

Returned by initializeDiscovery(). status: 'CREATED' means new indexes were created; 'EXISTING' means the setup was already in place.

AwsSupportedResourceType

type AwsSupportedResourceType = {
  resourceType: string;
  service?: string;
};

Returned by listSupportedDiscoveryResourceTypes(). Lists the AWS resource types that Resource Explorer can index and that CloudBurn can discover.

Deprecated aliases

These types still work but are deprecated. Use the replacements shown.

Deprecated	Replacement
`RuleConfig`	`CloudBurnModeConfig`
`ScanSource`	`Source`

What's next


Package Exports	All named exports and their signatures
CloudBurnClient	Method reference with full parameter types
Rules	Browse available rules