Types

Every type with its own heading on this page is exported from @cloudburn/sdk as a TypeScript type import. A few shapes that those types refer to are internal to the engine and are shown inline only for context: IaCSuppression, AwsResourceProperty, DiscoveryDatasetKey, StaticDatasetKey, LiveEvaluationContext, and StaticEvaluationContext. Each is marked where it appears; import the public type that contains it instead.

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;
};

ConfigOutputFormat

type ConfigOutputFormat = 'json' | 'table';

Scan result types

ScanResult

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

ScanPolicyResult

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

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: IaCSuppression;
};

// IaCSuppression is owned by @cloudburn/rules and is not exported by name from @cloudburn/sdk
type IaCSuppression =
  | { kind: 'all'; location: SourceLocation; reason?: string }
  | { kind: 'rule'; location: SourceLocation; reason?: string; ruleId: string };

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', since suppression comments only apply to static scans. suppression.location points at the comment itself, not the resource. suppression.ruleId is present only when kind is 'rule'.

ProviderFindingGroup

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

Finding

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

FindingMatch

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

actionType, resourceType, resourceId, accountId, and region together form the identity used by rule-declared finding precedence: when an enabled rule declares supersedesRuleIds, its findings replace identical matches reported by those rules. See Finding precedence for the rules that own this behavior.

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[];
  supersedesRuleIds?: string[];
  discoveryDependencies?: DiscoveryDatasetKey[];
  optionalDiscoveryDependencies?: DiscoveryDatasetKey[];
  staticDependencies?: StaticDatasetKey[];
  evaluateLive?: (context: LiveEvaluationContext) => Finding | null;
  getLiveEvaluationCoverage?: (context: LiveEvaluationContext) => LiveEvaluationCoverage;
  evaluateStatic?: (context: StaticEvaluationContext) => Finding | null;
};

The evaluator functions and dataset key unions are internal to the engine. DiscoveryDatasetKey, StaticDatasetKey, LiveEvaluationContext, and StaticEvaluationContext are not part of the SDK's public export surface. See Understanding rules for how rules are authored.

BuiltInRuleMetadata

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

Serializable metadata subset of Rule, with no evaluator functions. This is the type of entries in the builtInRuleMetadata constant array. supersedesRuleIds is only present when the rule declares precedence over another rule.

LiveEvaluationCoverage

type LiveEvaluationCoverage = {
  assessed: FindingMatch[];
  unknown: FindingMatch[];
};

Re-exported from @cloudburn/rules. Reported per rule on RuleEvaluation and per evidence artifact on AwsEvidenceProvenance. A rule that triggered can still carry unknown resources, so a triggered result is not proof of complete assessment. See Live evaluation coverage for why a rule reports a resource as unknown.

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[];
};

Evaluation evidence types

These types populate ScanResult.evaluations and appear only on discovery scans run with discover({ includeEvaluationResources: true }). They let a caller audit rules that produced no finding, instead of inferring a pass from an empty result.

ScanEvaluations

type ScanEvaluations = {
  resourceSets: EvaluationResourceSet[];
  rules: RuleEvaluation[];
};

RuleEvaluation

type RuleEvaluation = Omit<BuiltInRuleMetadata, 'id'> & {
  coverage?: LiveEvaluationCoverage;
  findingCount: number;
  resourceSetId?: string;
  ruleId: string;
  status: 'triggered' | 'passed' | 'not_applicable' | 'unknown';
  source: 'discovery';
  reason?: string;
};

Each entry also carries the rule's own metadata (name, description, message, provider, service, severity, supports, and supersedesRuleIds when declared), so a caller can build a product view without a second copy of the rule catalog.

unknown was added in SDK 0.33. Code that validates status strings must accept it.

EvaluationResourceSet

type EvaluationResourceSet = {
  id: string;
  resources: EvaluatedResource[];
};

The id is the discovery dataset key the resources came from. When a rule ran with some regions excluded, the id is suffixed with :excluding:<region>,<region> so a partial set cannot be confused with a complete one.

EvaluatedResource

type EvaluatedResource = Omit<FindingMatch, 'region'> & {
  region: string;
  resourceType: string;
  arn?: string;
  data?: unknown;
  name?: string;
  tags?: Record<string, string>;
  createdAt?: string;
  lastActivityAt?: string;
};

The shape of data depends on the rule. It is typed as one of the AWS evidence types listed under Resource evidence types; narrow it yourself against the rule you requested.

Evidence cache types

Reusable evidence is off unless discover({ cache }) is configured. These types describe that opt-in.

AwsEvidenceCacheOptions

type AwsEvidenceCacheOptions = {
  mode?: 'normal' | 'refresh' | 'off';
  directory?: string;
  store?: EvidenceCacheStore;
  authorizationContext?: string;
  maxEntries?: number;
  maxBytes?: number;
  ttlMs?: { catalog?: number; datasets?: Record<string, number>; pricing?: number };
};

ttlMs.catalog covers Resource Explorer catalog artifacts, ttlMs.pricing covers public pricing lookups, and ttlMs.datasets is keyed by discovery dataset key. Every value must be a non-negative safe integer or the call throws a RangeError. The built-in defaults are 180000 ms for catalogs, 600000 ms for inventory datasets, 300000 ms for activity datasets, 21600000 ms for billing and recommendation datasets, and 43200000 ms for public pricing.

Temporary credentials derive a session-specific reuse scope on their own. Long-term credentials reuse nothing unless authorizationContext is set, because an account or role ARN alone cannot prove that effective permissions are unchanged. Failed refreshes block reuse of older evidence until a complete refresh succeeds.

The SDK never picks a cache directory for you. cloudburn discover --cache-dir defaults to $XDG_CACHE_HOME/cloudburn/evidence (or ~/.cache/cloudburn/evidence), but that default belongs to the CLI. An SDK caller that wants durable reuse passes directory explicitly.

AwsEvidenceProvenance

type AwsEvidenceProvenance = EvidenceCacheProvenance & {
  datasetKey: string;
  region?: string;
  coverage?: LiveEvaluationCoverage;
  diagnostics?: ScanDiagnostic[];
};

One entry per collected evidence artifact in ScanResult.evidence. datasetKey identifies the artifact, coverage reports which resources that artifact could and could not assess, and diagnostics carries the non-fatal problems recorded while collecting it.

EvidenceCacheProvenance

type EvidenceCacheProvenance = {
  source: 'live' | 'cache';
  collectedAt: string;
  observedAt: string;
  observationWindow?: { start: string; end: string };
  complete: boolean;
  cacheStatus?: 'miss' | 'hit' | 'stale' | 'corrupt' | 'obsolete' | 'refresh' | 'off';
};

EvidenceCacheMode

type EvidenceCacheMode = 'normal' | 'refresh' | 'off';

EvidenceCache

type EvidenceCache = {
  load: <T>(request: EvidenceCacheRequest<T>) => Promise<EvidenceCacheResult<T>>;
};

The generic cache boundary returned by createEvidenceCache(). load() reuses fresh, complete evidence or coalesces a cancellable refresh so concurrent callers share one collection.

EvidenceCacheOptions

type EvidenceCacheOptions = {
  directory?: string;
  store?: EvidenceCacheStore;
  maxEntries?: number;
  maxBytes?: number;
  leaseMs?: number;
  pollMs?: number;
  now?: () => number;
};

Passed to createEvidenceCache(). leaseMs defaults to 30000 and pollMs to 25. Every numeric option must be a positive safe integer. Passing both directory and store throws.

EvidenceCacheRequest

type EvidenceCacheRequest<T> = {
  key: unknown;
  ttlMs: number;
  mode?: EvidenceCacheMode;
  signal?: AbortSignal;
  load: (signal: AbortSignal) => Promise<EvidenceCacheLoad<T>>;
  validate?: (value: unknown) => value is T;
};

One evidence request. key must contain every scope and schema dimension that distinguishes the artifact, because it is hashed into the cache identity. ttlMs must be a non-negative finite number.

EvidenceCacheLoad

type EvidenceCacheLoad<T> = {
  value: T;
  complete: boolean;
  observedAt?: string;
  observationWindow?: { start: string; end: string };
};

What an EvidenceCacheRequest.load callback returns. complete: false keeps the value usable for this scan but blocks it from being stored for reuse.

EvidenceCacheResult

type EvidenceCacheResult<T> = {
  value: T;
  fingerprint: string;
  provenance: EvidenceCacheProvenance;
};

fingerprint is a stable SHA-256 digest of the normalized value, so a caller can tell whether reused evidence is byte-identical to what it saw before.

EvidenceCacheState

type EvidenceCacheState = {
  entry?: string;
  invalidated?: boolean;
  lease?: { token: string; expiresAt: number };
  accessedAt: number;
};

The opaque per-key state a custom EvidenceCacheStore persists. invalidated retains the previous payload but blocks reuse until a complete refresh succeeds.

EvidenceCacheStore

type EvidenceCacheStore = {
  update: <T>(
    key: string,
    transition: (state: EvidenceCacheState | undefined) => { state: EvidenceCacheState; value: T },
    signal?: AbortSignal,
  ) => Promise<T>;
  prune: (limits: { maxEntries: number; maxBytes: number; now: number }, signal?: AbortSignal) => Promise<void>;
};

The persistence contract for hosted consumers that cannot use a local directory. update() must apply the transition atomically and make each transition linearizable; prune() must evict least-recently-accessed inactive entries until both limits hold, and must never evict an entry holding a live lease. Keys are hashed evidence identities and never contain credentials. createMemoryEvidenceCacheStore() is the in-process reference implementation.

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: DiscoveryDatasetKey; totalDatasets: number }
  | {
      kind: 'rule';
      ruleId: string;
      provisional: true;
      status: RuleEvaluation['status'];
      findingCount: number;
      findings: FindingMatch[];
      reason?: string;
      completedRules: number;
      totalRules: number;
      elapsedMs: number;
    };

Passed to discover()'s onProgress callback while a live discovery run loads its resource catalog and datasets and evaluates rules, so callers can render feedback before the final ScanResult arrives. DiscoveryDatasetKey is a string union owned by @cloudburn/rules and is not exported by name from @cloudburn/sdk; treat datasetKey as a string.

'rule' events arrive in completion order, not rule order, because independent collection work runs in parallel. elapsedMs is measured from the moment rule selection completed, not from the call, so it does not include config loading or credential resolution. findings holds the normalized matches that rule produced.

A rule is released only after its required evidence, plus any optional evidence the scan happened to select, finishes loading. Optional dependencies never trigger extra collection on their own. A resource type becomes ready only once every selected-region query for it finishes pagination, so cached types can be released while unrelated cache misses are still loading.

Every 'rule' event sets provisional: true. A later rule can supersede its findings through rule-declared precedence, and a late catalog failure can invalidate its scope. Replace progress state with the resolved ScanResult and never persist a provisional event as a final scan result. Cancellation rejects the call even when events were already delivered.

AwsDiscoveryExecutionOptions

type AwsDiscoveryExecutionOptions = {
  aws?: { credentials?: AwsClientCredentials };
  signal?: AbortSignal;
  timeoutMs?: number;
};

Shared by discover(), getDiscoveryStatus(), initializeDiscovery(), and listSupportedDiscoveryResourceTypes(). An expired deadline rejects with a DOMException named TimeoutError; cancellation rejects with the signal's reason. Neither returns a partial result. timeoutMs must be a positive integer no greater than 2147483647.

AwsDiscoveredResource

type AwsDiscoveredResource = {
  arn: string;
  accountId: string;
  region: string;
  service: string;
  resourceType: string;
  name?: string;
  properties: AwsResourceProperty[]; // Resource Explorer property records
};

One resource as Resource Explorer reported it, before any rule evaluation. AwsResourceProperty itself is internal to the engine and is not exported from @cloudburn/sdk.

AwsDiscoveryCatalog

type AwsDiscoveryCatalog = {
  resources: AwsDiscoveredResource[];
  searchRegion: string;
  indexType: 'LOCAL' | 'AGGREGATOR';
  viewArn?: string;
};

The Resource Explorer catalog a discovery run selected resources from.

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;
};

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.

Resource evidence types

@cloudburn/sdk re-exports the provider-normalized evidence types that discovery datasets produce. They are the shapes you narrow EvaluatedResource.data to when you audit a specific rule with includeEvaluationResources. Field definitions live with the rule that consumes them, in Understanding rules.

AwsCostOptimizationHubRightsizingRecommendation and AwsCostOptimizationHubUpgradeRecommendation are discriminated unions keyed by resourceType; AwsCostOptimizationHubIdleRecommendation is keyed by actionType and currentResourceType, and its recommendedConfiguration is null when AWS supplies no target configuration for stopping or deleting capacity. Narrow the discriminant before reading currentConfiguration and recommendedConfiguration.

Deprecated aliases

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

What's next