CloudBurn Logo
CloudBurnHome
  • Cost estimation

    • AWS Simple Pricing CalculatorEstimate your AWS stack
    • IaC Cost EstimatorReview costs before merge

    Cost analysis

    • AWS Cost TreeSee where your spend went

    Cost Optimization

    • Unused resourcesFind resources to remove
    • Resource efficiencyImprove what you keep
    • Commitment savingsReview plans and reservations
    • Cost GovernanceBudgets, alerts, and tags

    Product

    • RoadmapWhat's coming next
    • ChangelogProduct updates
    • DocsGuides and reference
    • AboutWhy CloudBurn exists
  • Pricing
  • Blog
  • Tools
Join the CloudBurn Discord community
Join the waitlistWaitlist
Join the CloudBurn Discord community1.8k
Navigation
    • Overview
    • Installation
    • Configuration
    • GitHub Action
    • MCP Plugin
    • VS Code Extension
      • Scan IaC Files
      • Discover AWS
      • scan
      • discover
      • config
      • rules list
      • completion
      • estimate
      • Exit Codes
      • Output Formats
      • CI/CD Integration
      • Resource Explorer Setup
    • Overview
    • Connect an AWS Account
    • Set Up PR Cost Estimation
    • Plans and Billing
    • Workspaces and Members
    • AWS Cost Tree
      • Usage Assumptions
      • Examples
      • Unused Resources
      • Resource Efficiency
      • Commitment Savings
      • Cost Governance
    • Overview
    • Understanding Rules
      • CloudFront
      • CloudTrail
      • CloudWatch
      • AWS Config
      • Cost Explorer
      • Cost Guardrails
      • Cost Optimization Hub
      • DynamoDB
      • EBS
      • EC2
      • ECR
      • ECS
      • EKS
      • ElastiCache
      • ELB
      • EMR
      • KMS
      • Lambda
      • RDS
      • Redshift
      • Route 53
      • S3
      • SageMaker
      • Secrets Manager
      • Tagging
    • Overview
    • Installation
      • Static IaC Scan
      • Discovery Scan
      • CloudBurnClient
      • Types
      • Package Exports
      • Custom Config
      • AWS Credentials
    • Overview
    • Installation
    • Configuration
    • GitHub Action
    • MCP Plugin
    • VS Code Extension
      • Scan IaC Files
      • Discover AWS
      • scan
      • discover
      • config
      • rules list
      • completion
      • estimate
      • Exit Codes
      • Output Formats
      • CI/CD Integration
      • Resource Explorer Setup
    • Overview
    • Connect an AWS Account
    • Set Up PR Cost Estimation
    • Plans and Billing
    • Workspaces and Members
    • AWS Cost Tree
      • Usage Assumptions
      • Examples
      • Unused Resources
      • Resource Efficiency
      • Commitment Savings
      • Cost Governance
    • Overview
    • Understanding Rules
      • CloudFront
      • CloudTrail
      • CloudWatch
      • AWS Config
      • Cost Explorer
      • Cost Guardrails
      • Cost Optimization Hub
      • DynamoDB
      • EBS
      • EC2
      • ECR
      • ECS
      • EKS
      • ElastiCache
      • ELB
      • EMR
      • KMS
      • Lambda
      • RDS
      • Redshift
      • Route 53
      • S3
      • SageMaker
      • Secrets Manager
      • Tagging
    • Overview
    • Installation
      • Static IaC Scan
      • Discovery Scan
      • CloudBurnClient
      • Types
      • Package Exports
      • Custom Config
      • AWS Credentials
Loading documentation page
CloudBurn Logo
CloudBurn

Open-source AWS cost checks and an upcoming platform for cost estimation, optimization, and governance.

1.8k

Product

  • Pricing
  • Roadmap
  • Changelog
  • About
  • Blog
  • Waitlist
  • Docs
  • Contact

Free Tools

  • EC2 Pricing Calculator
  • S3 Pricing Calculator
  • Bedrock Pricing Calculator
  • Fargate Pricing Calculator
  • RDS Pricing Calculator
  • ECS Pricing Calculator
  • Aurora Pricing Calculator
  • All AWS pricing calculators →

CloudBurn Platform · early 2027

Price changes before you deploy. Fix the waste after.

Join now for 30% off, for as long as you keep your plan.

Join the waitlist

Two emails a month at most. Unsubscribe anytime. By signing up you agree to the privacy policy.

CloudBurn © 2026 | Terms & Privacy

Built with ❤️ by Towards the Cloud

  • Pricing
  • Blog
  • Tools
      • Overview
      • Installation
        • CloudBurnClient
        • Types
        • Package Exports
      • Overview
      • Installation
        • CloudBurnClient
        • Types
        • Package Exports
    CloudBurn SDK

    Types

    Browse CloudBurn SDK TypeScript types for configuration, rules, findings, scan results, and AWS discovery. Review field definitions and public import examples.

    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;
    };
    
    FieldTypeDescription
    enabledRulesstring[]Allowlist of rule IDs to run. If set, only these rules execute.
    disabledRulesstring[]Denylist of rule IDs to skip.
    failOnSeverityLowest severity that makes the scan report a policy violation. When set, scanStatic() and discover() populate ScanResult.policy automatically.
    servicesstring[]Filter to specific AWS services (e.g. ['ec2', 'ebs']).
    formatConfigOutputFormatOutput format for CLI use.

    ConfigOutputFormat

    type ConfigOutputFormat = 'json' | 'table';
    

    Scan result types

    ScanResult

    type ScanResult = {
      capabilities?: AwsCapabilityOutcome[];
      diagnostics?: ScanDiagnostic[];
      evidence?: AwsEvidenceProvenance[];
      evaluations?: ScanEvaluations;
      policy?: ScanPolicyResult;
      providers: ProviderFindingGroup[];
      suppressed?: SuppressedFinding[];
    };
    
    FieldTypeDescription
    capabilitiesAwsCapabilityOutcome[]Readiness projected from collected discovery evidence. Discovery only; see AwsCapabilityOutcome.
    diagnosticsScanDiagnostic[]Access errors or warnings that did not stop the scan.
    evidenceAwsEvidenceProvenance[]Freshness and coverage of collected evidence. Discovery only, and only when discover({ cache }) is configured.
    evaluationsScanEvaluationsPer-rule outcomes and inspected resources. Discovery only, and only when includeEvaluationResources is set.
    policyScanPolicyResultPresent when failOn is configured for the scanned mode. See ScanPolicyResult.
    providersProviderFindingGroup[]Findings grouped by cloud provider.
    suppressedSuppressedFinding[]IaC findings matched by an inline cloudburn-ignore comment. See SuppressedFinding.

    ScanPolicyResult

    type ScanPolicyResult = {
      qualifyingFindingCount: number;
      threshold?: Severity;
      violated: boolean;
    };
    
    FieldTypeDescription
    qualifyingFindingCountnumberNumber of active findings at or above threshold.
    thresholdSeverityThe failOn severity that was evaluated.
    violatedbooleantrue 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: 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[];
    };
    
    FieldTypeDescription
    providerCloudProviderThe cloud provider for this group.
    rulesFinding[]All rule findings for this provider.

    Finding

    type Finding = {
      ruleId: string;
      service: string;
      source: Source;
      severity: Severity;
      message: string;
      findings: FindingMatch[];
    };
    
    FieldTypeDescription
    ruleIdstringThe rule identifier (e.g. CLDBRN-AWS-EBS-1).
    servicestringAWS service name (e.g. ebs).
    sourceSourceWhether this came from 'iac' or 'discovery'.
    severitySeverityThe rule's configured severity.
    messagestringHuman-readable description of the issue.
    findingsFindingMatch[]Individual resources that triggered this rule.

    FindingMatch

    type FindingMatch = {
      actionType?: string;
      resourceId: string;
      resourceType?: string;
      accountId?: string;
      region?: string;
      recommendation?: FindingRecommendation;
      impact?: FindingImpact;
      location?: SourceLocation;
    };
    
    FieldTypeDescription
    actionTypestringExact recommended operation, set when one resource can produce several distinct findings.
    resourceIdstringThe resource identifier or name.
    resourceTypestringProvider resource namespace, set when it is needed to tell otherwise identical resource IDs apart.
    accountIdstringAWS account ID (discovery scans only).
    regionstringAWS region (discovery scans only).
    recommendationFindingRecommendationEvidence source and optional computed resource/opportunity identity. See FindingRecommendation.
    impactFindingImpactIndependently tagged current cost and potential savings. See FindingImpact.
    locationSourceLocationFile location (IaC scans only).

    Rule-declared finding precedence compares canonical opportunities scoped by provider, account, region, resource namespace, canonical resource ID, and action. Equivalent ARN and short-ID forms can share an identity. An enabled rule declaring supersedesRuleIds can replace another rule's finding for the same opportunity; incomplete or conflicting scope is preserved. See Finding precedence for the rules that own this behavior.

    EvidenceProvenance

    type EvidenceProvenance = {
      source: string;
      sourceDetail?: string;
      sourceId?: string;
      observedAt?: string;
      refreshedAt?: string;
    };
    

    Identifies the evidence system that produced a recommendation, such as cloudburn or aws-cost-optimization-hub. sourceDetail names an upstream source when supplied, such as ComputeOptimizer. sourceId is the source's recommendation identifier, separate from resource identity. Timestamps retain source observation and refresh times; missing times are not inferred from scan execution or cache access.

    RecommendationIdentity

    type RecommendationIdentity = {
      resourceKey: string;
      opportunityId: string;
    };
    

    Versioned canonical keys for a fully scoped match. resourceKey identifies the provider, account, region, resource namespace, and resource. opportunityId additionally identifies the recommended action, so competing recommendations for the same action can be compared.

    FindingRecommendation

    type FindingRecommendation = EvidenceProvenance & Partial<RecommendationIdentity>;
    

    The provenance and optional computed identities attached to FindingMatch.recommendation. A match can carry provenance even when its scope is insufficient to compute canonical identities.

    ImpactPeriod

    type ImpactPeriod = 'hour' | 'day' | 'month' | 'year';
    

    The financial reporting period of an amount.

    ImpactWindow

    type ImpactWindow = { start?: string; end?: string; lookbackDays?: number };
    

    Observation boundaries supplied by the evidence source. Endpoints are omitted when unknown.

    ImpactUnknownReason

    type ImpactUnknownReason = { code: string; message: string };
    

    Explains why a financial amount cannot be established.

    FinancialEvidence

    type FinancialEvidence =
      | { confidence: 'exact' | 'estimated'; amount: number; currency: string; period: ImpactPeriod }
      | {
          confidence: 'unknown';
          amount?: never;
          currency?: string;
          period?: ImpactPeriod;
          reason: ImpactUnknownReason;
        };
    

    exact marks measured or billed evidence; estimated marks a modeled projection. An unknown value has no amount and carries a reason. A known zero and an unknown amount are distinct.

    FindingImpact

    type FindingImpact = EvidenceProvenance & {
      currentCost: FinancialEvidence;
      potentialSavings: FinancialEvidence;
      window?: ImpactWindow;
    };
    

    Financial evidence attached to FindingMatch.impact. Current cost and potential savings are independent measurements with their own confidence, currency, and period. The SDK preserves source values without summing them or converting their units. Narrow confidence before reading an amount:

    for (const provider of result.providers) {
      for (const finding of provider.rules) {
        for (const match of finding.findings) {
          const savings = match.impact?.potentialSavings;
          if (savings && savings.confidence !== 'unknown') {
            console.log(`${match.resourceId}: ${savings.amount} ${savings.currency}/${savings.period}`);
          }
        }
      }
    }
    

    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;
    };
    
    FieldTypeDescription
    idstringUnique rule identifier.
    namestringShort display name.
    descriptionstringDetailed explanation of what the rule checks.
    messagestringThe finding message shown in results.
    providerCloudProviderCloud provider this rule targets.
    servicestringAWS service this rule targets.
    severitySeverityThe rule's configured severity.
    supportsSource[]Whether the rule supports 'iac', 'discovery', or both.
    supersedesRuleIdsstring[]Rule IDs whose identical resource findings this rule replaces. See Finding precedence.
    discoveryDependenciesdataset keysDatasets the live evaluator requires. A rule is skipped when one is unavailable.
    optionalDiscoveryDependenciesdataset keysDatasets the evaluator may use when another active rule already requested them. Never collected on its own.
    staticDependenciesdataset keysDatasets the static evaluator requires.
    getLiveEvaluationCoveragefunctionReports resource-level assessed and unknown coverage independently of grouped findings.

    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[];
    };
    
    FieldTypeDescription
    assessedFindingMatch[]Resources with enough evidence to establish a finding or a non-finding.
    unknownFindingMatch[]Resources that could not be assessed because required evidence was unavailable or incomplete.

    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[];
    };
    
    FieldTypeDescription
    resourceSetsEvaluationResourceSet[]Deduplicated resource identities. A set shared by several rules is emitted once.
    rulesRuleEvaluation[]One entry per selected discovery rule, including rules that were skipped or found nothing.

    RuleEvaluation

    type RuleEvaluation = Omit<BuiltInRuleMetadata, 'id'> & {
      coverage?: LiveEvaluationCoverage;
      findingCount: number;
      resourceSetId?: string;
      ruleId: string;
      status: 'triggered' | 'passed' | 'not_applicable' | 'unknown';
      source: 'discovery';
      reason?: string;
    };
    
    FieldTypeDescription
    coverageLiveEvaluationCoverageAssessed and unknown resource identities, present when the rule reports metric coverage.
    findingCountnumberNumber of resource matches this rule produced.
    resourceSetIdstringKey into ScanEvaluations.resourceSets, present when resource identities were projected.
    ruleIdstringThe rule identifier.
    statusunionOutcome of the evaluation. See the table below.
    source'discovery'Always 'discovery'; static scans do not produce evaluations.
    reasonstringWhy a rule was skipped or could not assess every resource.

    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.

    StatusMeaning
    triggeredThe rule produced at least one finding.
    passedThe rule ran with complete evidence and found nothing.
    unknownThe rule ran but could not assess some resources because evidence was incomplete or a region was unavailable.
    not_applicableThe rule was skipped, usually because a required dataset was unavailable or an AWS service was not enrolled.

    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;
    };
    
    FieldTypeDescription
    regionstringAWS region, or 'global' for resources without one.
    resourceTypestringProvider resource namespace.
    arnstringResource ARN when AWS supplies one.
    dataunknownProvider-normalized evidence, present when a check needs auditable detail beyond identity.
    namestringResource name when available.
    tagsRecord<string, string>Resource tags when the dataset collects them.
    createdAtstringISO 8601 creation timestamp when available.
    lastActivityAtstringISO 8601 timestamp of the last observed activity when available.

    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 };
    };
    
    FieldTypeDescription
    modeEvidenceCacheModenormal reuses fresh evidence, refresh requires recollection, off bypasses all reuse and storage.
    directorystringPrivate local persistence directory. The SDK has no default; omit for in-process memory only. Mutually exclusive with store.
    storeEvidenceCacheStoreAlternative persistence and atomic coordination supplied by a hosted consumer. Mutually exclusive with directory.
    authorizationContextstringEffective permission or session-policy revision. Required for reuse with long-term credentials; must be non-empty when passed.
    maxEntriesnumberMaximum durable entry count. Default 1000.
    maxBytesnumberMaximum durable serialized bytes. Default 134217728 (128 MiB).
    ttlMsobjectFreshness overrides in milliseconds. Zero disables reuse for that evidence.

    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';
    };
    
    FieldTypeDescription
    source'live' | 'cache'Whether this artifact was collected during this scan or reused.
    collectedAtstringISO 8601 time the evidence was collected from AWS.
    observedAtstringISO 8601 observation time the evidence describes.
    observationWindowobjectStart and end of the observed window, for metric and billing evidence.
    completebooleanWhether collection finished. Incomplete evidence is never stored for reuse.
    cacheStatusunionWhy this artifact was collected or reused.

    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

    AwsCapability

    type AwsCapability =
      | 'cost-optimization-hub-enrollment'
      | 'compute-optimizer-enrollment'
      | 'resource-explorer-aggregator'
      | 'cost-explorer-access'
      | 'budgets-access';
    

    An AWS evidence capability from AWS_CAPABILITIES. Use getRuleCapabilities() to inspect a built-in rule's direct requirements before scanning.

    AwsCapabilityStatus

    type AwsCapabilityStatus = 'available' | 'partial' | 'unavailable' | 'error';
    

    Readiness projected from dataset outcomes: available means the relevant evidence loaded successfully; partial retains gaps or incomplete evidence; unavailable means no usable evidence established readiness; error records collection errors or throttling when no successful evidence remains.

    AwsCapabilityReason

    type AwsCapabilityReason =
      | 'not-enrolled'
      | 'aggregator-required'
      | 'region-not-enabled'
      | 'default-view-required'
      | 'filtered-view'
      | 'tags-view-required'
      | 'access-denied'
      | 'throttled'
      | 'service-error'
      | 'incomplete-evidence'
      | 'data-unavailable'
      | 'dataset-unavailable'
      | 'not-assessed';
    

    Bounded codes explaining partial, unavailable, or errored evidence. not-assessed means a catalog-backed dataset matched no resources and never made a service call.

    AwsCapabilityScope

    type AwsCapabilityScope =
      | { type: 'account' }
      | { type: 'all-regions' }
      | { type: 'regional'; regions: string[] }
      | { type: 'recommendation-source'; accountId: string; region?: string };
    

    The scope of a capability observation. A recommendation-source outcome establishes only that usable recommendations from that source were returned for those records, account, and optional region. It does not certify current upstream enrollment or complete coverage.

    AwsCapabilityOutcome

    type AwsCapabilityOutcome = {
      capability: AwsCapability;
      status: AwsCapabilityStatus;
      reasons: AwsCapabilityReason[];
      scope: AwsCapabilityScope;
      datasetKeys: DiscoveryDatasetKey[];
    };
    

    Populates ScanResult.capabilities on live discovery scans, including scans without evidence caching or evaluation-resource output. Outcomes reflect collected evidence and diagnostics; projecting them makes no extra AWS readiness calls and changes no setup or enrollment. Unrequested capabilities are absent, so an empty array is not a blanket readiness check. DiscoveryDatasetKey is an internal union; it is not exported by name from @cloudburn/sdk.

    A successful empty account-scoped dataset can still establish availability. A successful tagging query proves access to its aggregator view, without proving that all enabled regions are indexed. Keep the outcome's scope when showing readiness to users.

    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. AwsCredentialIdentity and AwsCredentialIdentityProvider are defined by @aws-sdk/types; import those names from that package when needed. 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.

    Event kindFires when
    'catalog'The Resource Explorer catalog finishes loading. Fires once.
    'dataset'Each discovery dataset (EC2 instances, RDS snapshots, and so on) finishes loading.
    'rule'Each rule finishes evaluating, once all its required evidence is ready. Added in SDK 0.35.

    '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;
    };
    
    FieldTypeDescription
    aws.credentialsAwsClientCredentialsCredentials for this call instead of the ambient credential provider chain.
    signalAbortSignalCancels active requests, retries, pagination, and queued work.
    timeoutMsnumberTotal operation deadline in milliseconds. Defaults to 300000, five minutes.

    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;
    };
    
    FieldTypeDescription
    aggregatorRegionstringRegion hosting the aggregator index, if one exists.
    accessibleRegionCountnumberNumber of regions the SDK could access.
    coverage'full' | 'partial' | 'local_only' | 'none'Overall coverage level.
    indexedRegionCountnumberNumber of regions with an active index.
    regionsAwsDiscoveryRegionStatus[]Per-region status details.
    totalRegionCountnumberTotal number of AWS regions checked.
    warningstringOptional 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 a setup task was created or newly indexed regions were observed. 'EXISTING' means existing indexes were reused; the call may still promote a local index or add tags to the default view. Inspect aggregatorAction, indexType, verificationStatus, and warning to distinguish a verified aggregator from a timed-out or local-only setup.

    AwsSupportedResourceType

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

    Returned by listSupportedDiscoveryResourceTypes(). Lists resource types supported by AWS Resource Explorer. This is an indexing catalog, not a list of resource types covered by CloudBurn rules; use Rules for rule coverage.


    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.

    ServiceExported types
    CloudFrontAwsCloudFrontDistribution
    CloudTrailAwsCloudTrailTrail
    CloudWatch LogsAwsCloudWatchLogGroup, AwsCloudWatchLogStream
    ConfigAwsConfigRecordingFrequencyReview, AwsConfigRecordingModeOverride
    Cost ExplorerAwsCostUsage, AwsSageMakerSavingsPlansCoverage
    Cost Optimization HubAwsCostOptimizationHubRecommendation, AwsCostOptimizationHubReservationRecommendation, AwsCostOptimizationHubRightsizingRecommendation, AwsCostOptimizationHubUpgradeRecommendation, AwsCostOptimizationHubIdleRecommendation, AwsCostOptimizationHubGravitonRecommendation, AwsCostOptimizationHubSavingsPlansRecommendation
    Hub configuration shapesAwsCostOptimizationHubAutoScalingConfiguration, AwsCostOptimizationHubAutoScalingUpgradeConfiguration, AwsCostOptimizationHubComputeConfiguration, AwsCostOptimizationHubDbConfiguration, AwsCostOptimizationHubDynamoDbReservationConfiguration, AwsCostOptimizationHubEbsUpgradeConfiguration, AwsCostOptimizationHubEc2ReservationConfiguration, AwsCostOptimizationHubEc2UpgradeConfiguration, AwsCostOptimizationHubElastiCacheReservationConfiguration, AwsCostOptimizationHubGravitonConfiguration, AwsCostOptimizationHubInstanceConfiguration, AwsCostOptimizationHubMemoryDbReservationConfiguration, AwsCostOptimizationHubOpenSearchReservationConfiguration, AwsCostOptimizationHubRdsReservationConfiguration, AwsCostOptimizationHubRdsStorageUpgradeConfiguration, AwsCostOptimizationHubRdsUpgradeConfiguration, AwsCostOptimizationHubRedshiftReservationConfiguration, AwsCostOptimizationHubReservationConfiguration, AwsCostOptimizationHubRightsizingConfigurationMap, AwsCostOptimizationHubServiceConfiguration, AwsCostOptimizationHubVolumeConfiguration
    DynamoDBAwsDynamoDbTable, AwsDynamoDbAutoscaling
    EBSAwsEbsVolume, AwsEbsSnapshot
    EC2 and ELBAwsEc2Instance, AwsEc2ReservedInstance, AwsEc2LoadBalancer, AwsEc2TargetGroup, AwsEc2TransitGatewayVpcAttachmentActivity
    ECS and EKSAwsEcsCluster, AwsEcsClusterMetric, AwsEcsContainerInstance, AwsEcsService, AwsEcsServiceAutoscaling, AwsEksNodegroup
    ElastiCacheAwsElastiCacheCluster, AwsElastiCacheReservedNode
    EMRAwsEmrCluster, AwsEmrClusterMetric
    KMSAwsKmsKeyChurnReview, AwsKmsKeyUsage, AwsKmsKeyUsageEvidence, AwsKmsAliasPatternGroup
    LambdaAwsLambdaFunction, AwsLambdaFunctionMetric
    RDSAwsRdsInstance, AwsRdsInstanceActivity, AwsRdsInstanceCpuMetric, AwsRdsReservedInstance, AwsRdsSnapshot
    RedshiftAwsRedshiftCluster, AwsRedshiftClusterMetric, AwsRedshiftReservedNode
    Route 53AwsRoute53Zone, AwsRoute53Record, AwsRoute53HealthCheck
    SageMakerAwsSageMakerEndpointActivity, AwsSageMakerNotebookInstance
    Secrets ManagerAwsSecretsManagerSecret

    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.

    DeprecatedReplacement
    RuleConfigCloudBurnModeConfig
    ScanSourceSource

    What's next

    Package ExportsAll named exports and their signatures
    CloudBurnClientMethod reference with full parameter types
    RulesBrowse available rules
    ← PreviousCloudBurnClientNext →Package Exports

    CloudBurn Platform · early 2027

    Price changes before you deploy. Fix the waste after.

    Join now for 30% off, for as long as you keep your plan.

    Join the waitlist

    Two emails a month at most. Unsubscribe anytime. By signing up you agree to the privacy policy.