@cloudburn/sdk

The CloudBurn SDK lets you run the same cost policy engine inside your own codebase. It handles config loading, Terraform and CloudFormation parsing, live AWS discovery, and rule evaluation.

Use it when you want CloudBurn in internal tooling, custom automations, or your own platform instead of calling the CLI.

Installation

npm install @cloudburn/sdk

Optimization contract upgrade

The coordinated #269 release completes the contract introduced in SDK 0.37.0 / rules 0.34.0, with immutable rule IDs, package-consumer validation, and these integration notes. SDK 0.37.1 pins rules 0.34.1; applications that import rules directly must use that same rules version. Install SDK 0.37.1 exactly and regenerate the application lockfile. The accompanying CLI is 0.18.6. Node.js 24 or newer is required.

Intentional pre-1.0 breaking changes from SDK 0.36.x / rules 0.33.x:

• Hub dataset currencyCode, estimatedMonthlyCost, estimatedMonthlySavings, and estimatedSavingsPercentage are nullable. A complete recommendation can now survive missing financial values. Update runtime guards and use impact.currentCost / impact.potentialSavings, narrowing each by confidence; unknown has no amount and must never become zero. Known zero remains valid.
• Canonical resource/action identity, freshness deduplication, and deterministic precedence can change finding membership, counts, and order. Hub Graviton recommendations supersede equivalent native EC2/RDS recommendations; different actions stay distinct. Savings Plans resource namespaces now distinguish purchase families.
• Accept and preserve capabilities, optional recommendation, and optional impact in application result/artifact schemas. Use final providers findings for retained opportunities. evaluations and their resource sets describe evidence before precedence and cannot be counted as additional opportunities. Replace provisional progress with the resolved result.

CloudBurn Cloud's integration issue #141 owns the SDK dependency/lockfile update, result guards, worker, and new artifact schema. Replace its pre-launch contract directly; no compatibility adapter, dual shape, or data migration is provided. Product profile membership stays application-owned. All current rule IDs remain unchanged and are immutable going forward.

Minimal integration

This read-only example runs one configured-region scan with a caller-owned selection. Replace the example IDs with the union of the application's versioned profile IDs. Use the application's existing scoped AWS credentials; the example never initializes or enrolls AWS services.

import { CloudBurnClient, getRuleCapabilities, type FinancialEvidence } from '@cloudburn/sdk';

const enabledRules = ['CLDBRN-AWS-COSTOPTIMIZATIONHUB-4'];
const requirements = enabledRules.map((ruleId) => ({ ruleId, capabilities: getRuleCapabilities(ruleId) }));
const result = await new CloudBurnClient().discover({
  target: { mode: 'region', region: 'eu-west-1' },
  config: { discovery: { enabledRules } },
  includeEvaluationResources: true,
  timeoutMs: 13 * 60_000,
});

const displayAmount = (value: FinancialEvidence | undefined) =>
  !value || value.confidence === 'unknown' ? null : `${value.amount} ${value.currency}/${value.period}`;

for (const provider of result.providers) {
  for (const rule of provider.rules) {
    for (const finding of rule.findings) {
      console.log({
        ruleId: rule.ruleId,
        resourceId: finding.resourceId,
        recommendation: finding.recommendation,
        currentCost: displayAmount(finding.impact?.currentCost),
        potentialSavings: displayAmount(finding.impact?.potentialSavings),
      });
    }
  }
}
console.log({ requirements, capabilities: result.capabilities, evaluations: result.evaluations });

Keep each capability outcome's scope and machine-readable reasons. available describes observed evidence readiness, not a passing rule or complete account coverage. A recommendation-source observation does not certify direct Compute Optimizer enrollment. A missing outcome is not proof of availability.

Retain recommendation source, source ID, timestamps, and opaque identity keys without parsing those keys or promising cross-scan identity stability. Identity and precedence identify competing opportunities within a scan; different opportunityId values do not prove savings are additive. Only aggregate known, compatible currency/period/window figures after proving non-overlap, and report unpriced coverage separately. Preserve the full evidence envelope in stored results; formatted strings in this example are presentation only. See the authoritative finding contract for shapes and precedence rules.

Getting Started

Static scans

Use scanStatic() to run the built-in rules against Terraform or CloudFormation.

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

const client = new CloudBurnClient();
const result = await client.scanStatic('./iac');

for (const providerGroup of result.providers) {
  for (const ruleGroup of providerGroup.rules) {
    console.log(
      providerGroup.provider,
      ruleGroup.ruleId,
      ruleGroup.severity,
      ruleGroup.source,
      ruleGroup.findings.length,
    );
  }
}

Static scans recognize resource-local cloudburn-ignore <rule-id> [reason] and cloudburn-ignore-all [reason] comments in Terraform and CloudFormation YAML. Matches removed by these directives are retained in result.suppressed; active findings remain in result.providers.

Both modes accept a failOn threshold. When configured, the SDK evaluates it and exposes the effective threshold, qualifying finding count, and violation status on result.policy:

const result = await client.scanStatic('./iac', {
  iac: { failOn: 'high' },
});

if (result.policy?.violated) {
  console.error(`${result.policy.qualifyingFindingCount} high-severity findings`);
}

Use the exported evaluateScanPolicy(result, threshold?) helper to apply a runtime threshold or an any-finding policy without rerunning the scan. SDK policy evaluation reports state; it does not change the host process exit code.

Live discovery

Use initializeDiscovery() first to set up AWS Resource Explorer. CloudBurn uses it to select catalog-backed resources; independent account collection can run alongside catalog preparation.

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

const client = new CloudBurnClient();

await client.initializeDiscovery();

const currentRegion = await client.discover();
const explicitRegion = await client.discover({
  target: { mode: 'regions', regions: ['eu-central-1'] },
});
const multipleRegions = await client.discover({
  target: { mode: 'regions', regions: ['eu-central-1', 'us-east-1'] },
});
const auditableResult = await client.discover({
  includeEvaluationResources: true,
  config: {
    discovery: {
      enabledRules: ['CLDBRN-AWS-CLOUDWATCH-1', 'CLDBRN-AWS-CLOUDWATCH-2'],
    },
  },
});

discover(), getDiscoveryStatus(), initializeDiscovery(), and listSupportedDiscoveryResourceTypes() each have a five-minute total deadline. All accept the additive AwsDiscoveryExecutionOptions: timeoutMs, signal, and aws.credentials. Set timeoutMs to allow a longer operation, or pass an AbortSignal to cancel it:

const controller = new AbortController();
const result = await client.discover({
  target: { mode: 'regions', regions: ['eu-west-1'] },
  timeoutMs: 600_000,
  signal: controller.signal,
});

An expired deadline rejects with TimeoutError; cancellation rejects with the signal's reason. Both stop work owned exclusively by that caller without returning partial results. A shared evidence refresh continues while another caller still needs it. Cancellation during initialization stops further setup work; mutations already accepted by AWS remain in place and a later initialization observes that state. AWS clients and lookup caches belong to their managed execution and are released when it ends.

Discovery progress

Pass onProgress to receive catalog, dataset, and provisional rule events while discovery runs:

const startedAt = performance.now();
let firstResultMs: number | undefined;
const result = await client.discover({
  onProgress(event) {
    if (event.kind !== 'rule') return;
    firstResultMs ??= performance.now() - startedAt;
    console.error(`${event.ruleId}: ${event.status}, ${event.findingCount} findings (provisional)`);
  },
});
console.error({ firstResultMs, totalMs: performance.now() - startedAt });

A rule event includes normalized findings, status, an optional reason, completion counts, and elapsedMs since rule selection. Events arrive in completion order. Every rule event has provisional: true: another rule may supersede its findings, or a later catalog failure may invalidate its scope. Replace progress state with the resolved ScanResult; never persist provisional events as final scan results. Cancellation rejects even when events were already delivered.

Required evidence and any optional evidence selected by the scan must finish before a rule event. Optional dependencies alone do not trigger extra collection. Empty catalog pages with continuation tokens never release a rule. A resource type becomes ready only after all its selected-region queries finish pagination; a shared packed query releases its types together. Cached types can become ready while unrelated cache misses are still loading.

Debug logging reports sdk: live scan timing with firstRuleMs and totalMs, measured from rule selection. firstRuleMs is null when no provisional evaluation was requested or emitted. The example above measures the entire public call, including setup, so its values can differ. See the progress reference for the event fields and compatibility notes.

Reusable evidence

SDK reuse is off unless you configure cache. A configured cache without a directory uses memory on this client; provide a private directory to reuse evidence across clients and local processes:

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

Temporary credentials derive a session-specific reuse scope. Long-term credentials require an explicit permission context revision; an account or role ARN alone is insufficient. Every scan validates its identity and current Resource Explorer view. Change authorizationContext when effective permissions or relevant execution conditions change. Use refresh to require recollection, or off to bypass all evidence reuse and storage. Failed refreshes block reuse of older evidence until a complete refresh succeeds.

Rules, configuration, and precedence run again on every scan. evidence reports source, collection/observation times, completeness, and resource-level assessed/unknown coverage. Initial freshness policies are tunable proposals: catalogs 3 minutes, inventory 10 minutes, activity 5 minutes, billing/recommendations 6 hours, and public pricing 12 hours. Some datasets use complete days or months; rolling windows align to freshness intervals. See the cache reference for exact scope, freshness tradeoffs, cancellation, local leases, limits, and the EvidenceCacheStore contract for hosted consumers.

Request scheduling and service coverage

Catalog, control-plane, and collector requests share AWS quota limits across operations and independent SDK or CLI processes running as the same OS user. Quotas use the signing caller's account, resolved once per run. If that lookup fails, collectors continue with isolated in-memory limits for that run. Shared coordination requires writable local storage. It uses $XDG_CACHE_HOME/cloudburn/aws-admission-v1 when configured, or ~/.cache/cloudburn/aws-admission-v1, with a shared temporary-directory fallback when a new default cache cannot be created. Set CLOUDBURN_AWS_ADMISSION_DIR to choose a shared writable path for containers or other constrained environments. Existing state errors fail without bypassing coordination. CLOUDBURN_AWS_QUOTA_OVERRIDES accepts JSON policies such as {"logs:DescribeLogStreams":{"ratePerSecond":5,"burst":1}}. See AWS request scheduling for defaults, retry behavior, telemetry, and coordination limits.

Status inspects up to 5 regions concurrently and returns regions sorted by name. Regional status probes make at most 2 attempts so persistent throttling or transport failures yield status evidence promptly. Initialization retains its existing setup verification, local fallback, and default-view tag behavior. Normal discovery and status remain read-only. The initial STS identity request uses a separate bounded in-memory budget because the account is not yet known; subsequent requests use the resolved account. Transit Gateway public pricing keeps its own 5-second timeout within the operation deadline. A pricing-only failure leaves activity evidence usable.

discover() defaults to the current AWS region and the AWS Core preset. You can also target one or more explicit AWS regions with { target: { mode: 'regions', regions: [...] } }. Multi-region discovery requires an AWS Resource Explorer aggregator index. Rules that need explicit AWS setup are opt-in through config.discovery.enabledRules. CLDBRN-AWS-TAGGING-1 needs an accessible aggregator, CLDBRN-AWS-LAMBDA-4 needs AWS Compute Optimizer enrollment, and CLDBRN-AWS-COSTOPTIMIZATIONHUB-1 needs AWS Cost Optimization Hub enrollment.

Set includeEvaluationResources when a caller needs audit evidence for checks that did not produce findings. The optional result.evaluations value contains normalized identities from the primary resource dataset supplied to each completed live rule. Shared resource sets are emitted once and referenced by rule entries. Every selected rule is represented as triggered, passed, unknown, or not_applicable; unresolved and skipped rules include a reason. Metric-dependent rules include per-rule coverage.assessed and coverage.unknown resource identities. A triggered result can retain unknown resources, and primary resource sets are not a guarantee of complete assessment. Applications that validate status strings must accept unknown. The result reference describes coverage and nullable metric fields. Rule entries also carry generic rule and service metadata so callers can select checks and build their own product views without re-querying AWS or maintaining a second copy of rule descriptions.

Live findings that correspond to a recommendation also carry normalized recommendation metadata: the producing source (cloudburn or aws-cost-optimization-hub), an optional sourceDetail such as ComputeOptimizer or CostExplorer, the source-side sourceId, and source-reported observedAt/refreshedAt timestamps that are omitted rather than guessed when the source does not report them. Scoped findings also carry opaque versioned resourceKey and opportunityId identity keys: resourceKey identifies the provider/account/Region/canonical resource, and opportunityId adds the action. Cross-rule precedence compares complete computed opportunity identities, so a different action or scope on the same resource is preserved. Legacy findings without a recommendation object can participate using complete scope fields; an explicit provenance-only recommendation without opportunityId skips precedence. Evaluation resource sets record pre-precedence evidence and are not totals. The finding reference documents the exact fields and precedence table.

Findings and evaluation resources can also carry optional impact metadata: currentCost and potentialSavings are independently tagged FinancialEvidence values — estimated for modeled figures (Hub recommendations and the AWS Config recording-frequency projection are both modeled), exact for measured or billed evidence, or unknown with a reason when the source did not supply a usable amount. An unknown amount is absent rather than zero, and the optional window mirrors only source-reported observation boundaries or lookback durations. Hub financial fields are nullable, so absent money never invalidates an otherwise complete recommendation. The SDK never aggregates or converts these values; see finding-shape.md for the exact semantics.

Every live discover() result also reports capabilities: a read-only readiness projection for the AWS capabilities the selected rules require. Each outcome reports available, partial, unavailable, or error with machine-readable reasons such as not-enrolled, aggregator-required, or data-unavailable, scoped to the account, the Regions that produced evidence, or all-regions when an all-Region target produced no observed regional evidence. Degraded scans — for example, one denied Cost Explorer dataset beside a successful one — report partial instead of hiding the failure. The projection never enrolls an account, updates Resource Explorer views, or adds readiness probes; callers own setup UI and enrollment workflows. The result reference describes the exact shape, statuses, reasons, and scopes.

Match outcomes by capability and scope, not capability alone: a recommendation-source outcome can coexist with a direct outcome for the same capability, and it only proves that returned Cost Optimization Hub records carried that upstream source — it does not certify current enrollment or complete source coverage, so an empty Hub response cannot establish Compute Optimizer readiness. CLDBRN-AWS-LAMBDA-4 needs Compute Optimizer enrollment directly, while recommendation-source outcomes can also surface Compute Optimizer evidence returned through Hub records.

const result = await client.discover();
const lambdaReadiness = result.capabilities?.find(
  (outcome) => outcome.capability === 'compute-optimizer-enrollment' && outcome.scope.type === 'regional',
);

getRuleCapabilities(ruleId) lists the AWS capabilities a built-in rule directly requires, without any AWS calls or probes. Only required discoveryDependencies contribute — optional supporting evidence is excluded — and IaC-only or ordinary inventory rules return []. Unknown rule IDs throw.

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

getRuleCapabilities('CLDBRN-AWS-LAMBDA-4'); // ['compute-optimizer-enrollment']

Evaluation resources can include provider-normalized data when a check needs auditable evidence beyond identity and timestamps. For example, CLDBRN-AWS-CONFIG-1 reports the affected resource type, current recording frequency, observation window, configuration-item volume, current and recently deleted resource counts, estimated monthly reduction, turnover-estimate reliability, recorder scope and overrides, public continuous and daily unit prices, and any Firewall Manager or paid service-linked recorder dependency. If bounded turnover inspection cannot decide an otherwise eligible above-threshold review, discovery emits a diagnostic and reports the rule as not_applicable instead of passed.

CLDBRN-AWS-ELB-5 evaluates HTTP request activity for Application Load Balancers and Classic Load Balancers with HTTP/HTTPS listeners only. Network, Gateway, and Classic TCP/SSL or unverified listeners remain in unknown coverage unless an empty-target cleanup rule already covers them. Missing or incomplete daily metrics cannot produce an idle finding. See ELB inventory and request activity for metric contracts and inventory reuse.

CLDBRN-AWS-KMS-1 reports a regional count of enabled customer-managed keys, the previous-full-month creation count, the UTC window boundaries, estimated monthly storage cost, repeated alias-pattern hashes, multi-Region and rotation counts, key-metadata completeness, and usage-evidence coverage. The SDK never returns raw aliases in this dataset. Denied DescribeKey calls leave a confirmed minimum count plus an explicit unreadable count.

CLDBRN-AWS-KMS-2 reuses the same KMS review scan and reports individual keys that are at least 90 days old with no recorded KMS cryptographic use during a complete 90-day tracking window. This covers never-used keys and keys whose last recorded use is at least 90 days old. The evidence includes the key ARN, creation date, tracking start, last use when present, multi-Region status, and an estimated monthly storage cost with its completeness flag. A shorter tracking window is skipped. Missing key or usage metadata makes this check not_applicable instead of passed. Because KMS cannot observe every possible use, the rule recommends disabling and monitoring a candidate before deletion. The shared loader requires kms:DescribeKey, kms:GetKeyLastUsage, kms:ListAliases, and kms:ListKeyRotations.

CLDBRN-AWS-EC2-14 checks available Transit Gateway VPC attachments over the previous 30 complete UTC days. A finding requires complete attachment-level BytesIn and BytesOut coverage with both totals equal to zero. Evaluation evidence includes the attachment, Transit Gateway, and VPC identities; Region; observed traffic; lookback length; and the public regional hourly and estimated monthly attachment price when AWS publishes it. Missing pricing does not block the rule, and attachments with incomplete CloudWatch evidence are skipped. The loader requires ec2:DescribeTransitGatewayAttachments, ec2:DescribeTransitGatewayVpcAttachments, and cloudwatch:GetMetricData.

CLDBRN-AWS-COSTOPTIMIZATIONHUB-1 reads account-scoped Compute, EC2 Instance, and SageMaker Savings Plans purchase recommendations from AWS Cost Optimization Hub. Evaluation evidence includes the Savings Plans type, account scope, hourly commitment, estimated monthly cost and savings, savings percentage, currency, commitment term, payment option, refresh time, recommendation source, and operational impact fields. EC2 Instance recommendations also retain the instance family and commitment Region. The SDK checks enrollment but never changes it. An account that is not enrolled, lacks cost-optimization-hub:ListEnrollmentStatuses, cost-optimization-hub:ListRecommendations, or cost-optimization-hub:GetRecommendation, or returns incomplete purchase evidence reports the rule as not_applicable instead of passed.

CLDBRN-AWS-COSTOPTIMIZATIONHUB-6 is an opt-in Graviton migration rule for standalone EC2 instances, EC2 Auto Scaling groups (single or mixed instance types), and RDS DB instances. Enable it through config.discovery.enabledRules. It uses the shared Hub loader with MigrateToGraviton; rightsizing and generation upgrades remain separate actions.

The loader requires cost-optimization-hub:ListEnrollmentStatuses, cost-optimization-hub:ListRecommendations, and cost-optimization-hub:GetRecommendation. It checks enrollment without changing it and queries the account through the us-east-1 Hub endpoint. Recommendations retain their own resource regions.

With includeEvaluationResources: true, AwsCostOptimizationHubGravitonRecommendation includes current and recommended typed configurations, resource ID and ARN, account and region, current monthly cost, savings and percentage, currency, implementation effort, restart and rollback flags, recommendation ID, source, and refresh timestamp. workloadCompatibility follows AWS's documented strategy mapping: EC2 and Auto Scaling High means inferred_compatible, while VeryHigh means unclassified. RDS Medium maps to not_applicable because that strategy does not classify an inferred application workload. An inference still requires application validation before migration; unclassified workloads have no confirmed compatibility.

Missing configuration, unsupported effort, incomplete evidence, unenrolled accounts, and denied access produce a diagnostic and not_applicable evaluation. An enrolled account with no matching recommendations passes. An enabled Hub finding takes precedence over the native CLDBRN-AWS-EC2-6 and CLDBRN-AWS-RDS-4 Graviton reviews for the same account, Region, canonical resource, and MigrateToGraviton action. ECS and EKS Graviton findings use different resource namespaces and stay separate; they cannot be summed with EC2/RDS findings across the underlying fleets. Evaluation evidence retains every rule's original result before precedence.

CLDBRN-AWS-COSTOPTIMIZATIONHUB-2 uses the same read-only enrollment, paginated recommendation, and bounded detail loading seam for EC2, RDS, OpenSearch, Redshift, ElastiCache, MemoryDB, and DynamoDB reservation purchases. Its evaluation evidence preserves account and Region, resource ID and ARN when AWS provides them, current monthly cost, estimated savings and percentage, currency, implementation effort, restart and rollback flags, source, refresh time, term, payment option, and the resource-type-specific purchase configuration. Repeated summaries are loaded once only when account, Region, resource type, resource ID, ARN, action, and recommendation ID all match. Reused IDs in different scopes are loaded separately. A Hub finding is suppressed only when an enabled native CloudBurn rule actually reports the same resource namespace and identity for the same reservation purchase action with direct service evidence. The presence of a native rule in the catalog is not enough. This precedence is declared by rule metadata rather than AWS-specific engine policy, and evaluation evidence retains the Hub rule's original triggered result. Unenrolled, denied, and incomplete responses make the Hub rule not_applicable.

Enable CLDBRN-AWS-COSTOPTIMIZATIONHUB-4 through config.discovery.enabledRules to read Hub rightsizing recommendations for standalone EC2 instances, EC2 Auto Scaling groups, EBS volumes, Lambda functions, ECS services, RDS DB instances, RDS DB instance storage, and Aurora DB cluster storage. It queries the current account through the Hub endpoint in us-east-1, across all recommendation Regions, without requiring Resource Explorer.

The rule uses cost-optimization-hub:ListEnrollmentStatuses, cost-optimization-hub:ListRecommendations, and cost-optimization-hub:GetRecommendation, plus sts:GetCallerIdentity for account identity. Grant the Hub actions on Resource: "*", as required by the Hub IAM reference. CloudBurn only reads enrollment; an administrator must enroll the account separately.

With includeEvaluationResources: true, the aws-cost-optimization-hub-rightsizing-recommendations resource set exposes AwsCostOptimizationHubRightsizingRecommendation. Narrow its resourceType discriminant to read the typed currentConfiguration and recommendedConfiguration; nested instance, mixed-instance, compute, and storage fields remain structured. Evidence retains resource identity, account, Region, currency, current monthly cost, estimated savings and percentage, implementation effort, restart and rollback flags, source, and refresh timestamp. Regional identity is required: a valid account-matching ARN supplies a missing Region; otherwise the evidence is incomplete. Lambda finding identity strips version and alias qualifiers to match the native rule, while evidence retains the original ARN. The existing purchase-recommendation action union remains unchanged.

Only the AWS Rightsize action qualifies. Generation upgrades and Graviton migrations are separate actions. CLDBRN-AWS-LAMBDA-4, when enabled and reporting the same Lambda ARN, account, and Region, suppresses the Hub duplicate using direct Compute Optimizer memory evidence. Low-utilization and migration findings do not suppress it. RDS instance and storage recommendations have separate evidence namespaces. Unenrolled accounts, denied access, and incomplete detail evidence produce diagnostics and not_applicable; an enrolled account with no recommendations passes.

Enable idle capacity recommendations with config.discovery.enabledRules: ['CLDBRN-AWS-COSTOPTIMIZATIONHUB-3']. The rule shares Hub enrollment, pagination, deduplication, and diagnostics with the purchase rules. It requires the same three Hub read permissions and sts:GetCallerIdentity; all Hub queries use us-east-1 and filter to the caller's account. Idle recommendations also filter to the discovery target's Regions. An all-region target leaves that filter unset.

With includeEvaluationResources: true, AwsCostOptimizationHubIdleRecommendation retains exact actions, typed current and recommended configurations, costs, savings, identity, and operational impact. Stop covers EC2 and RDS MySQL/PostgreSQL; Delete covers EBS, ECS, and Aurora MySQL/PostgreSQL instances; ScaleIn covers Auto Scaling groups. AWS classifies RDS engine eligibility; Hub configuration exposes instance class, not engine metadata. See AWS's action mapping.

An absent Stop/Delete target is represented as null. Missing ScaleIn targets, malformed supplied configuration, missing operational flags, denied requests, or unenrolled accounts make the rule not_applicable. CloudBurn never executes these actions or changes enrollment. The native unattached-volume rule can suppress the same EBS Delete finding when enabled; low utilization alone does not suppress Stop/Delete recommendations.

CLDBRN-AWS-COSTOPTIMIZATIONHUB-5 is opt-in through config.discovery.enabledRules. It reads only Upgrade recommendations for EC2 instances, Auto Scaling groups, EBS volumes, RDS DB instances, and RDS DB instance storage through the shared Hub loader in us-east-1. The three Hub IAM actions listed above require Resource: "*"; account identity also uses sts:GetCallerIdentity. CloudBurn never changes enrollment or resources.

AwsCostOptimizationHubUpgradeRecommendation is a discriminated union keyed by resourceType, with typed currentConfiguration and recommendedConfiguration. It retains identity, account, Region, cost, savings, currency, implementation effort, restart, rollback, source, and refresh evidence. Missing required configuration, identity, or operational data makes evaluation not_applicable; an enrolled account with a successful empty response passes. Missing financial values remain valid as unknown impact. The finding reference lists each configuration contract.

Enabled native EBS and RDS storage generation rules take precedence for the same account, Region, resource, and storage upgrade. RDS compute and storage findings use distinct namespaces. EC2 family preferences do not establish the same recommended upgrade and do not suppress Hub findings. Evaluation evidence retains the original Hub result.

CLDBRN-AWS-SAGEMAKER-3 reads SageMaker Savings Plans coverage from Cost Explorer for the last 30 complete days. It flags coverage below 80 percent only when uncovered On-Demand cost is at least 72 cost units. When Cost Optimization Hub returns a SageMaker purchase recommendation, that stronger finding suppresses the coverage warning for the account. Cost Optimization Hub is an optional dependency for this rule, so missing enrollment or access does not block coverage evaluation. Missing ce:GetSavingsPlansCoverage access, incomplete coverage values, or a Cost Explorer DataUnavailableException make the rule not_applicable.

The SDK does not define product profiles, remediation effort, commands, or persistence schemas. Applications select the discovery rules that fit their use case through config.discovery.enabledRules and transform the generic result at their own product boundary.

CloudFront discovery reuses ListDistributions summaries when the catalog has no distribution seeds. A page of 100 distributions with price-class evidence needs 1 list request and 0 GetDistribution requests, excluding account identity lookup. Pagination retains all listed distributions; a nonempty catalog selection uses detail requests only for those selected IDs and never lists additional distributions.

Grant cloudfront:ListDistributions for fallback discovery and cloudfront:GetDistribution for catalog hydration or fallback standard distributions missing their price class. Standard distributions retain supplied price classes, including None. Tenant-only distributions omit price-class evidence from both summary and detail responses because AWS does not support that setting for this variant; tenant-only summaries do not require a price-class lookup. These variants follow the AWS DistributionSummary contract. Fallback account identity uses sts:GetCallerIdentity; request activity also requires cloudwatch:GetMetricData in us-east-1. Necessary detail requests use at most 10 workers and retain the usual retry and cancellation behavior.

CloudFront distribution evidence includes optional lastModifiedTime as an ISO 8601 timestamp when AWS supplies it. Its absence does not trigger a detail request. Modification time does not establish creation time or replace the 30 complete daily observations required for a known request total. Incomplete, missing, and empty request evidence remains unknown.

Lower-level helpers

If you need more control, the SDK also exposes a lower-level parser:

• parseIaC(path) as a standalone export when you want normalized Terraform and CloudFormation resources without running rules

The CloudBurnClient also exposes helper methods:

• client.loadConfig(path?) to resolve CloudBurn config from disk
• client.getDiscoveryStatus() to inspect AWS Resource Explorer readiness
• client.listSupportedDiscoveryResourceTypes() to inspect the AWS resource types discovery can search

Docs

• Full docs: cloudburn.io/docs
• Architecture overview: docs/ARCHITECTURE.md
• Rule reference: docs/reference/rule-ids.md

License

Apache-2.0