Find Unused CloudFront Distributions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadDistributionsMetricsBuckets",
      "Effect": "Allow",
      "Action": [
        "cloudfront:ListDistributions",
        "cloudwatch:GetMetricData",
        "s3:ListAllMyBuckets"
      ],
      "Resource": "*"
    },
    {
      "Sid": "HeadOriginBuckets",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::*"
    },
    {
      "Sid": "DisableOnlyWithApply",
      "Effect": "Allow",
      "Action": [
        "cloudfront:GetDistributionConfig",
        "cloudfront:UpdateDistribution"
      ],
      "Resource": "arn:aws:cloudfront::123456789012:distribution/*"
    }
  ]
}

// find-unused-cloudfront-distributions.ts
// Lists CloudFront distributions with their viewer requests and bytes downloaded over --days days,
// flags distributions with no requests, S3 origins whose bucket no longer exists, and settings that
// bill every month (dedicated-IP SSL, AWS WAF web ACL, Anycast static IP list).
// Report only by default. --apply --disable E1,E2 sets Enabled=false on the named distributions,
// and only if they had zero requests in the window. It never deletes anything.
// Usage: npx tsx find-unused-cloudfront-distributions.ts [--days 30] [--disable E123ABC [--apply]]
import {
  CloudFrontClient,
  GetDistributionConfigCommand,
  UpdateDistributionCommand,
  paginateListDistributions,
  type DistributionSummary,
} from "@aws-sdk/client-cloudfront";
import { CloudWatchClient, GetMetricDataCommand, type MetricDataQuery } from "@aws-sdk/client-cloudwatch";
import { S3Client, HeadBucketCommand, paginateListBuckets, S3ServiceException } from "@aws-sdk/client-s3";

const args = process.argv.slice(2);
const flag = (name: string): string | undefined => {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
};
const days = Number(flag("--days") ?? 30);
const toDisable = new Set((flag("--disable") ?? "").split(",").map((s) => s.trim()).filter(Boolean));
const apply = args.includes("--apply");

// CloudFront is global: its API and its CloudWatch metrics are both in us-east-1.
const cloudfront = new CloudFrontClient({ region: "us-east-1" });
const cloudwatch = new CloudWatchClient({ region: "us-east-1" });
const s3 = new S3Client({ region: "us-east-1", followRegionRedirects: true });

interface Row {
  Id: string;
  Domain: string;
  Enabled: boolean;
  Requests: number;
  GBOut: string;
  S3Origins: string;
  MonthlyExtras: string;
  Verdict: string;
}

const errorText = (err: unknown): string => (err instanceof Error ? `${err.name}: ${err.message}` : String(err));

/** Bucket name from an S3 REST or website endpoint origin, or undefined for other origins. */
function bucketFromOrigin(domain: string): string | undefined {
  const m = /^(.+?)\.s3(?:[.-][a-z0-9-]+)?\.amazonaws\.com$/.exec(domain) // bucket.s3.amazonaws.com, bucket.s3.eu-west-1.amazonaws.com
    ?? /^(.+?)\.s3-website[.-][a-z0-9-]+\.amazonaws\.com$/.exec(domain); // website endpoints
  return m?.[1];
}

async function ownBuckets(): Promise<Set<string>> {
  const names = new Set<string>();
  for await (const page of paginateListBuckets({ client: s3 }, {})) {
    for (const b of page.Buckets ?? []) if (b.Name) names.add(b.Name);
  }
  return names;
}

/** "missing" when S3 answers 404 (the name is free for anyone to create), "other account" otherwise. */
async function bucketState(bucket: string): Promise<"missing" | "other account"> {
  try {
    await s3.send(new HeadBucketCommand({ Bucket: bucket }));
    return "other account";
  } catch (err) {
    return err instanceof S3ServiceException && err.$metadata.httpStatusCode === 404 ? "missing" : "other account";
  }
}

async function traffic(ids: string[]): Promise<Map<string, { requests: number; bytes: number }>> {
  const result = new Map<string, { requests: number; bytes: number }>();
  const end = new Date();
  const start = new Date(end.getTime() - days * 86_400_000);
  for (let i = 0; i < ids.length; i += 250) { // 2 queries per distribution, 500 per call
    const byQuery = new Map<string, { id: string; metric: "Requests" | "BytesDownloaded" }>();
    const queries: MetricDataQuery[] = [];
    ids.slice(i, i + 250).forEach((id, n) => {
      for (const metric of ["Requests", "BytesDownloaded"] as const) {
        const Id = `${metric === "Requests" ? "r" : "b"}${i + n}`;
        byQuery.set(Id, { id, metric });
        queries.push({
          Id,
          MetricStat: {
            Metric: {
              Namespace: "AWS/CloudFront",
              MetricName: metric,
              Dimensions: [{ Name: "DistributionId", Value: id }, { Name: "Region", Value: "Global" }],
            },
            Period: 86_400,
            Stat: "Sum",
          },
        });
      }
    });
    let NextToken: string | undefined;
    do {
      const out = await cloudwatch.send(new GetMetricDataCommand({ MetricDataQueries: queries, StartTime: start, EndTime: end, NextToken }));
      for (const r of out.MetricDataResults ?? []) {
        const q = byQuery.get(r.Id ?? "");
        if (!q) continue;
        const entry = result.get(q.id) ?? { requests: 0, bytes: 0 };
        const sum = (r.Values ?? []).reduce((s, v) => s + v, 0);
        if (q.metric === "Requests") entry.requests += sum;
        else entry.bytes += sum;
        result.set(q.id, entry);
      }
      NextToken = out.NextToken;
    } while (NextToken);
  }
  return result;
}

function extras(d: DistributionSummary): string[] {
  const out: string[] = [];
  if (d.ViewerCertificate?.SSLSupportMethod === "vip") out.push("dedicated-IP SSL");
  if (d.WebACLId) out.push("WAF web ACL");
  if (d.AnycastIpListId) out.push("Anycast IP list");
  return out;
}

async function main(): Promise<void> {
  const dists: DistributionSummary[] = [];
  for await (const page of paginateListDistributions({ client: cloudfront }, {})) {
    dists.push(...(page.DistributionList?.Items ?? []));
  }
  if (dists.length === 0) {
    console.log("No CloudFront distributions in this account.");
    return;
  }
  const usage = await traffic(dists.map((d) => d.Id ?? ""));
  const mine = await ownBuckets();
  const stateCache = new Map<string, string>();

  const rows: Row[] = [];
  for (const d of dists) {
    const id = d.Id ?? "";
    const u = usage.get(id) ?? { requests: 0, bytes: 0 };
    const s3Notes: string[] = [];
    for (const o of d.Origins?.Items ?? []) {
      const bucket = bucketFromOrigin(o.DomainName ?? "");
      if (!bucket || mine.has(bucket)) continue;
      const state = stateCache.get(bucket) ?? (await bucketState(bucket));
      stateCache.set(bucket, state);
      s3Notes.push(`${bucket} (${state})`);
    }
    const verdicts: string[] = [];
    if (s3Notes.some((n) => n.endsWith("(missing)"))) verdicts.push("dangling S3 origin");
    if (u.requests === 0) verdicts.push(d.Enabled ? "no requests: disable?" : "disabled, no requests: delete?");
    rows.push({
      Id: id,
      Domain: d.Aliases?.Items?.[0] ?? d.DomainName ?? "",
      Enabled: d.Enabled ?? false,
      Requests: Math.round(u.requests),
      GBOut: (u.bytes / 1e9).toFixed(2),
      S3Origins: s3Notes.join(", ") || "ok",
      MonthlyExtras: extras(d).join(", ") || "none",
      Verdict: verdicts.join("; ") || "in use",
    });
  }
  rows.sort((a, b) => a.Requests - b.Requests);
  console.table(rows);
  const unused = rows.filter((r) => r.Requests === 0);
  const dangling = rows.filter((r) => r.Verdict.includes("dangling"));
  console.log(`${unused.length} of ${rows.length} distributions had no viewer requests in ${days} days; ` +
    `${dangling.length} point at an S3 bucket that no longer exists.`);

  for (const id of toDisable) {
    const row = rows.find((r) => r.Id === id);
    if (!row || row.Requests > 0) {
      console.log(`skip ${id}: ${row ? `${row.Requests} requests in ${days} days` : "not found"}`);
      continue;
    }
    if (!row.Enabled) {
      console.log(`skip ${id}: already disabled`);
      continue;
    }
    if (!apply) {
      console.log(`would disable ${id} (${row.Domain}) (re-run with --apply)`);
      continue;
    }
    try {
      // UpdateDistribution replaces the whole config, so send back what GetDistributionConfig returned.
      const current = await cloudfront.send(new GetDistributionConfigCommand({ Id: id }));
      if (!current.DistributionConfig) throw new Error("no DistributionConfig returned");
      await cloudfront.send(new UpdateDistributionCommand({
        Id: id,
        IfMatch: current.ETag,
        DistributionConfig: { ...current.DistributionConfig, Enabled: false },
      }));
      console.log(`disabled ${id}; wait for Status Deployed before any delete`);
    } catch (err) {
      console.error(`disable ${id}: ${errorText(err)}`);
    }
  }
}

main().catch((err) => {
  console.error(errorText(err));
  process.exit(1);
});

npm install @aws-sdk/client-cloudfront @aws-sdk/client-cloudwatch @aws-sdk/client-s3
npm install --save-dev tsx typescript @types/node

# Report over the default 30 days, or 90 for seasonal sites
AWS_PROFILE=readonly npx tsx find-unused-cloudfront-distributions.ts
AWS_PROFILE=readonly npx tsx find-unused-cloudfront-distributions.ts --days 90

# Preview, then disable one distribution
AWS_PROFILE=readonly npx tsx find-unused-cloudfront-distributions.ts --disable E2B3C4D5E6F7A8
AWS_PROFILE=ops-admin npx tsx find-unused-cloudfront-distributions.ts --disable E2B3C4D5E6F7A8 --apply

┌─────────┬──────────────────┬──────────────────────────┬─────────┬──────────┬──────────┬─────────────────────────────────┬────────────────────┬──────────────────────────────────────────────────────┐
│ (index) │ Id               │ Domain                   │ Enabled │ Requests │ GBOut    │ S3Origins                       │ MonthlyExtras      │ Verdict                                              │
├─────────┼──────────────────┼──────────────────────────┼─────────┼──────────┼──────────┼─────────────────────────────────┼────────────────────┼──────────────────────────────────────────────────────┤
│ 0       │ 'E2B3C4D5E6F7A8' │ 'promo-2025.example.com' │ true    │ 0        │ '0.00'   │ 'promo-2025-assets (missing)'   │ 'WAF web ACL'      │ 'dangling S3 origin; no requests: disable?'          │
│ 1       │ 'E3C4D5E6F7A8B9' │ 'legacy.example.com'     │ true    │ 0        │ '0.00'   │ 'ok'                            │ 'dedicated-IP SSL' │ 'no requests: disable?'                              │
│ 2       │ 'E4D5E6F7A8B9C0' │ 'd444.cloudfront.net'    │ false   │ 0        │ '0.00'   │ 'old-docs (missing)'            │ 'none'             │ 'dangling S3 origin; disabled, no requests: delete?' │
│ 3       │ 'E5E6F7A8B9C0D1' │ 'media.example.com'      │ true    │ 1200     │ '3.10'   │ 'partner-media (other account)' │ 'none'             │ 'in use'                                             │
│ 4       │ 'E1A2B3C4D5E6F7' │ 'www.example.com'        │ true    │ 48210000 │ '912.00' │ 'ok'                            │ 'none'             │ 'in use'                                             │
└─────────┴──────────────────┴──────────────────────────┴─────────┴──────────┴──────────┴─────────────────────────────────┴────────────────────┴──────────────────────────────────────────────────────┘
3 of 5 distributions had no viewer requests in 30 days; 2 point at an S3 bucket that no longer exists.
would disable E2B3C4D5E6F7A8 (promo-2025.example.com) (re-run with --apply)
skip E5E6F7A8B9C0D1: 1200 requests in 30 days