feat(rules): add AWS discovery rules for edge and cost services (#47)

Author: axonstone

.changeset/brisk-discovery-lattice.md

@@ -0,0 +1,5 @@
+---
+"@cloudburn/sdk": minor
+---
+
+Add AWS discovery loaders and registry wiring for API Gateway stages, CloudFront distributions, Cost Explorer service spend deltas, DynamoDB tables and autoscaling, Route 53 zones, records, and health checks, and Secrets Manager secrets.

.changeset/clear-rule-harvest.md

@@ -0,0 +1,5 @@
+---
+"@cloudburn/rules": minor
+---
+
+Add AWS discovery rules for API Gateway stage caching, CloudFront price class review, Cost Explorer month-over-month increases, DynamoDB stale tables and autoscaling coverage, Route 53 TTL and unused health checks, and unused Secrets Manager secrets.

docs/architecture/sdk.md

@@ -77,10 +77,11 @@ Current live-discovery behavior:
 - Discovery resolves the explicit default Resource Explorer view in the chosen search region and fails if no default view exists or if that default view applies additional filters.
 - Discovery setup returns existing local indexes without forcing aggregator creation, and `discover init` retries as local-only setup when cross-region aggregator creation is denied.
 - Catalog collection uses Resource Explorer `ListResources` with filter strings instead of `Search`, which avoids the 1,000-result ceiling on filter-only queries.
+- Account-scoped or fallback-backed datasets can bypass Resource Explorer seeding entirely by declaring no `resourceTypes`; the loader then receives `[]` and owns the account-level API call.
 - Resource Explorer inventory failures and dataset loader failures are fatal. The SDK does not degrade to partial live results.
 - Missing Lambda `Architectures` values from AWS are normalized to `['x86_64']`, matching the AWS default architecture.
 - Lambda hydrators limit in-flight `GetFunctionConfiguration` calls per region to avoid API throttling in large accounts.
-- Live scans require Resource Explorer access plus narrow hydrator permissions such as `application-autoscaling:DescribeScalableTargets`, `application-autoscaling:DescribeScalingPolicies`, `cloudtrail:DescribeTrails`, `cloudwatch:GetMetricData`, `ecs:DescribeContainerInstances`, `ecs:DescribeServices`, `ec2:DescribeVolumes`, `ec2:DescribeInstances`, `eks:ListNodegroups`, `eks:DescribeNodegroup`, `lambda:GetFunctionConfiguration`, `rds:DescribeDBInstances`, `s3:GetLifecycleConfiguration`, and `s3:GetIntelligentTieringConfiguration`.
+- Live scans require Resource Explorer access plus narrow hydrator permissions such as `apigateway:GetStage`, `application-autoscaling:DescribeScalableTargets`, `application-autoscaling:DescribeScalingPolicies`, `ce:GetCostAndUsage`, `cloudfront:GetDistribution`, `cloudfront:ListDistributions`, `cloudtrail:DescribeTrails`, `cloudwatch:GetMetricData`, `dynamodb:DescribeTable`, `ecs:DescribeContainerInstances`, `ecs:DescribeServices`, `ec2:DescribeVolumes`, `ec2:DescribeInstances`, `eks:ListNodegroups`, `eks:DescribeNodegroup`, `lambda:GetFunctionConfiguration`, `rds:DescribeDBInstances`, `route53:ListHealthChecks`, `route53:ListHostedZones`, `route53:ListResourceRecordSets`, `s3:GetLifecycleConfiguration`, `s3:GetIntelligentTieringConfiguration`, and `secretsmanager:DescribeSecret`.
 
 ## Public Result Shape
 

docs/reference/rule-ids.md

@@ -16,10 +16,15 @@ Format: `CLDBRN-{PROVIDER}-{SERVICE}-{N}`
 
 | ID                    | Name                                      | Service | Supports       | Status      |
 | --------------------- | ----------------------------------------- | ------- | -------------- | ----------- |
+| `CLDBRN-AWS-APIGATEWAY-1` | API Gateway Stage Caching Disabled    | apigateway | discovery   | Implemented |
+| `CLDBRN-AWS-CLOUDFRONT-1` | CloudFront Distribution Price Class All | cloudfront | discovery | Implemented |
 | `CLDBRN-AWS-CLOUDTRAIL-1` | CloudTrail Redundant Global Trails     | cloudtrail | discovery   | Implemented |
 | `CLDBRN-AWS-CLOUDTRAIL-2` | CloudTrail Redundant Regional Trails   | cloudtrail | discovery   | Implemented |
 | `CLDBRN-AWS-CLOUDWATCH-1` | CloudWatch Log Group Missing Retention | cloudwatch | discovery   | Implemented |
 | `CLDBRN-AWS-CLOUDWATCH-2` | CloudWatch Unused Log Streams          | cloudwatch | discovery   | Implemented |
+| `CLDBRN-AWS-COSTEXPLORER-1` | Cost Explorer Full Month Cost Changes | costexplorer | discovery | Implemented |
+| `CLDBRN-AWS-DYNAMODB-1` | DynamoDB Table Stale Data              | dynamodb | discovery     | Implemented |
+| `CLDBRN-AWS-DYNAMODB-2` | DynamoDB Table Without Autoscaling     | dynamodb | discovery     | Implemented |
 | `CLDBRN-AWS-EC2-1`    | EC2 Instance Type Not Preferred           | ec2     | iac, discovery | Implemented |
 | `CLDBRN-AWS-EC2-2`    | S3 Interface VPC Endpoint Used            | ec2     | iac            | Implemented |
 | `CLDBRN-AWS-EC2-3`    | Elastic IP Address Unassociated           | ec2     | discovery      | Implemented |
@@ -58,12 +63,19 @@ Format: `CLDBRN-{PROVIDER}-{SERVICE}-{N}`
 | `CLDBRN-AWS-REDSHIFT-1` | Redshift Cluster Low CPU Utilization    | redshift | discovery     | Implemented |
 | `CLDBRN-AWS-REDSHIFT-2` | Redshift Cluster Missing Reserved Coverage | redshift | discovery   | Implemented |
 | `CLDBRN-AWS-REDSHIFT-3` | Redshift Cluster Pause Resume Not Enabled | redshift | discovery    | Implemented |
+| `CLDBRN-AWS-ROUTE53-1` | Route 53 Record Higher TTL              | route53 | discovery      | Implemented |
+| `CLDBRN-AWS-ROUTE53-2` | Route 53 Health Check Unused            | route53 | discovery      | Implemented |
 | `CLDBRN-AWS-S3-1`     | S3 Missing Lifecycle Configuration        | s3      | iac, discovery | Implemented |
 | `CLDBRN-AWS-S3-2`     | S3 Bucket Storage Class Not Optimized     | s3      | iac, discovery | Implemented |
+| `CLDBRN-AWS-SECRETSMANAGER-1` | Secrets Manager Secret Unused    | secretsmanager | discovery | Implemented |
 | `CLDBRN-AWS-LAMBDA-1` | Lambda Cost Optimal Architecture          | lambda  | iac, discovery | Implemented |
 | `CLDBRN-AWS-LAMBDA-2` | Lambda Function High Error Rate           | lambda  | discovery      | Implemented |
 | `CLDBRN-AWS-LAMBDA-3` | Lambda Function Excessive Timeout         | lambda  | discovery      | Implemented |
 
+`CLDBRN-AWS-APIGATEWAY-1` flags REST API stages when `cacheClusterEnabled` is not explicitly `true`.
+
+`CLDBRN-AWS-CLOUDFRONT-1` reviews only distributions using `PriceClass_All`.
+
 `CLDBRN-AWS-EBS-1` flags previous-generation EBS volume types (`gp2`, `io1`, and `standard`) and does not flag current-generation HDD families such as `st1` or `sc1`.
 
 `CLDBRN-AWS-EBS-4` treats volumes above `100 GiB` as oversized enough to warrant explicit review.
@@ -76,6 +88,12 @@ Format: `CLDBRN-{PROVIDER}-{SERVICE}-{N}`
 
 `CLDBRN-AWS-CLOUDWATCH-2` flags log streams with no observed event history and log streams whose `lastIngestionTime` is more than 90 days old. Delivery-managed log groups remain exempt.
 
+`CLDBRN-AWS-COSTEXPLORER-1` compares the last two full months and flags only services with an existing prior-month baseline and a cost increase greater than `10` cost units.
+
+`CLDBRN-AWS-DYNAMODB-1` flags only tables whose parsed `latestStreamLabel` is older than `90` days. Tables without a stream label are skipped.
+
+`CLDBRN-AWS-DYNAMODB-2` reviews only provisioned-capacity tables and flags them when no table-level read or write autoscaling targets are configured.
+
 `CLDBRN-AWS-EC2-6` flags only families with a curated Graviton-equivalent path. Instances without architecture metadata or outside the curated family set are skipped.
 
 `CLDBRN-AWS-EC2-7` reviews only active reserved instances with an `endTime` inside the next 60 days.
@@ -120,6 +138,12 @@ Format: `CLDBRN-{PROVIDER}-{SERVICE}-{N}`
 
 `CLDBRN-AWS-REDSHIFT-3` flags only `available`, VPC-backed clusters with automated snapshots enabled, no HSM, and no Multi-AZ deployment when either the pause or resume schedule is missing.
 
+`CLDBRN-AWS-ROUTE53-1` reviews only non-alias records and treats `3600` seconds as the low-TTL floor.
+
+`CLDBRN-AWS-ROUTE53-2` flags only Route 53 health checks that are not referenced by any discovered record set.
+
+`CLDBRN-AWS-SECRETSMANAGER-1` flags secrets with no `lastAccessedDate` and secrets whose parsed last access is at least `90` days old.
+
 **Status key:**
 
 - **Implemented** — has evaluator coverage for every scan mode listed in `supports`

packages/rules/src/aws/apigateway/caching-disabled.ts

@@ -0,0 +1,25 @@
+import { createFinding, createFindingMatch, createRule } from '../../shared/helpers.js';
+
+const RULE_ID = 'CLDBRN-AWS-APIGATEWAY-1';
+const RULE_SERVICE = 'apigateway';
+const RULE_MESSAGE = 'API Gateway REST API stages should enable caching when stage caching is available.';
+
+/** Flag API Gateway REST API stages whose cache cluster is disabled. */
+export const apiGatewayCachingDisabledRule = createRule({
+  id: RULE_ID,
+  name: 'API Gateway Stage Caching Disabled',
+  description: 'Flag API Gateway REST API stages with caching disabled.',
+  message: RULE_MESSAGE,
+  provider: 'aws',
+  service: RULE_SERVICE,
+  supports: ['discovery'],
+  discoveryDependencies: ['aws-apigateway-stages'],
+  evaluateLive: ({ resources }) => {
+    const findings = resources
+      .get('aws-apigateway-stages')
+      .filter((stage) => stage.cacheClusterEnabled !== true)
+      .map((stage) => createFindingMatch(stage.stageArn, stage.region, stage.accountId));
+
+    return createFinding({ id: RULE_ID, service: RULE_SERVICE, message: RULE_MESSAGE }, 'discovery', findings);
+  },
+});

packages/rules/src/aws/apigateway/index.ts

@@ -0,0 +1,4 @@
+import { apiGatewayCachingDisabledRule } from './caching-disabled.js';
+
+// Intent: aggregate AWS API Gateway rule definitions.
+export const apigatewayRules = [apiGatewayCachingDisabledRule];

packages/rules/src/aws/cloudfront/distribution-pricing-class.ts

@@ -0,0 +1,27 @@
+import { createFinding, createFindingMatch, createRule } from '../../shared/helpers.js';
+
+const RULE_ID = 'CLDBRN-AWS-CLOUDFRONT-1';
+const RULE_SERVICE = 'cloudfront';
+const RULE_MESSAGE = 'CloudFront distributions using PriceClass_All should be reviewed for cheaper edge coverage.';
+
+/** Flag CloudFront distributions that use the most expensive global price class. */
+export const cloudFrontDistributionPricingClassRule = createRule({
+  id: RULE_ID,
+  name: 'CloudFront Distribution Price Class All',
+  description: 'Flag CloudFront distributions using PriceClass_All when a cheaper price class may suffice.',
+  message: RULE_MESSAGE,
+  provider: 'aws',
+  service: RULE_SERVICE,
+  supports: ['discovery'],
+  discoveryDependencies: ['aws-cloudfront-distributions'],
+  evaluateLive: ({ resources }) => {
+    const findings = resources
+      .get('aws-cloudfront-distributions')
+      .filter((distribution) => distribution.priceClass === 'PriceClass_All')
+      .map((distribution) =>
+        createFindingMatch(distribution.distributionArn, distribution.region, distribution.accountId),
+      );
+
+    return createFinding({ id: RULE_ID, service: RULE_SERVICE, message: RULE_MESSAGE }, 'discovery', findings);
+  },
+});

packages/rules/src/aws/cloudfront/index.ts

@@ -0,0 +1,4 @@
+import { cloudFrontDistributionPricingClassRule } from './distribution-pricing-class.js';
+
+// Intent: aggregate AWS CloudFront rule definitions.
+export const cloudfrontRules = [cloudFrontDistributionPricingClassRule];

packages/rules/src/aws/costexplorer/full-month-cost-changes.ts

@@ -0,0 +1,28 @@
+import { createFinding, createFindingMatch, createRule } from '../../shared/helpers.js';
+
+const RULE_ID = 'CLDBRN-AWS-COSTEXPLORER-1';
+const RULE_SERVICE = 'costexplorer';
+const RULE_MESSAGE =
+  'AWS services with cost increases greater than 10 USD between the last two full months should be reviewed.';
+// Match the upstream Thrifty default and only flag material month-over-month increases above ten cost units.
+const COST_INCREASE_THRESHOLD = 10;
+
+/** Flag AWS services whose spend increased materially between the last two full months. */
+export const costExplorerFullMonthCostChangesRule = createRule({
+  id: RULE_ID,
+  name: 'Cost Explorer Full Month Cost Changes',
+  description: 'Flag services with significant cost increases between the last two full months.',
+  message: RULE_MESSAGE,
+  provider: 'aws',
+  service: RULE_SERVICE,
+  supports: ['discovery'],
+  discoveryDependencies: ['aws-cost-usage'],
+  evaluateLive: ({ resources }) => {
+    const findings = resources
+      .get('aws-cost-usage')
+      .filter((service) => service.previousMonthCost > 0 && service.costIncrease > COST_INCREASE_THRESHOLD)
+      .map((service) => createFindingMatch(`cost/${service.serviceSlug}`, undefined, service.accountId));
+
+    return createFinding({ id: RULE_ID, service: RULE_SERVICE, message: RULE_MESSAGE }, 'discovery', findings);
+  },
+});

packages/rules/src/aws/costexplorer/index.ts

@@ -0,0 +1,4 @@
+import { costExplorerFullMonthCostChangesRule } from './full-month-cost-changes.js';
+
+// Intent: aggregate AWS Cost Explorer rule definitions.
+export const costexplorerRules = [costExplorerFullMonthCostChangesRule];