Find Unused Customer Managed KMS Keys

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListKeysAndEvents",
      "Effect": "Allow",
      "Action": [
        "kms:ListKeys",
        "kms:ListAliases",
        "cloudtrail:LookupEvents"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ReadKeyDetailsAndUsage",
      "Effect": "Allow",
      "Action": [
        "kms:DescribeKey",
        "kms:GetKeyLastUsage"
      ],
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/*"
    }
  ]
}

// find-unused-kms-keys.ts
// Reports customer managed KMS keys in one region with no cryptographic use in the last --days days.
// Uses KMS GetKeyLastUsage first, and CloudTrail event history (last 90 days) for keys whose usage
// tracking started after they were created. Read-only: it never disables or deletes a key.
// Usage: npx tsx find-unused-kms-keys.ts [--days 90]
import {
  KMSClient,
  paginateListKeys,
  paginateListAliases,
  DescribeKeyCommand,
  GetKeyLastUsageCommand,
} from "@aws-sdk/client-kms";
import { CloudTrailClient, LookupEventsCommand } from "@aws-sdk/client-cloudtrail";

const KEY_PER_MONTH = 1; // USD per customer managed key, us-east-1, as of September 2026 (up to $3 with rotations)

function arg(name: string): string | undefined {
  const i = process.argv.indexOf(name);
  return i === -1 ? undefined : process.argv[i + 1];
}

const kms = new KMSClient({}); // region from AWS_REGION or your profile
const cloudtrail = new CloudTrailClient({});
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

// Operations that count as using a key (the same list KMS tracks for GetKeyLastUsage).
const CRYPTO_OPS = new Set([
  "Decrypt", "DeriveSharedSecret", "Encrypt", "GenerateDataKey", "GenerateDataKeyPair",
  "GenerateDataKeyPairWithoutPlaintext", "GenerateDataKeyWithoutPlaintext", "GenerateMac",
  "ReEncrypt", "Sign", "Verify", "VerifyMac",
]);

// Most recent cryptographic CloudTrail event for this key in the last 90 days.
// Skips DescribeKey and other management calls (including this script's own). LookupEvents allows 2 calls/second.
async function lastTrailEvent(keyArn: string, maxPages = 10): Promise<{ name: string; time: Date } | undefined> {
  let NextToken: string | undefined;
  for (let page = 0; page < maxPages; page++) {
    await sleep(600);
    const res = await cloudtrail.send(
      new LookupEventsCommand({
        LookupAttributes: [{ AttributeKey: "ResourceName", AttributeValue: keyArn }],
        StartTime: new Date(Date.now() - 90 * 86_400_000),
        MaxResults: 50,
        NextToken,
      }),
    );
    const e = (res.Events ?? []).find((ev) => CRYPTO_OPS.has(ev.EventName ?? ""));
    if (e?.EventTime) return { name: e.EventName ?? "", time: e.EventTime };
    NextToken = res.NextToken;
    if (!NextToken) break;
  }
  return undefined;
}

async function main(): Promise<void> {
  const days = Number(arg("--days") ?? 90);
  const cutoff = Date.now() - days * 86_400_000;

  const aliases = new Map<string, string[]>();
  for await (const page of paginateListAliases({ client: kms }, {})) {
    for (const a of page.Aliases ?? []) {
      if (a.TargetKeyId && a.AliasName) aliases.set(a.TargetKeyId, [...(aliases.get(a.TargetKeyId) ?? []), a.AliasName]);
    }
  }

  const rows = [];
  let unusedCost = 0;
  for await (const page of paginateListKeys({ client: kms }, {})) {
    for (const k of page.Keys ?? []) {
      const keyId = k.KeyId ?? "";
      const { KeyMetadata: md } = await kms.send(new DescribeKeyCommand({ KeyId: keyId }));
      if (!md || md.KeyManager !== "CUSTOMER" || md.KeyState === "PendingDeletion") continue; // AWS managed keys are free

      let lastUsed: Date | undefined;
      let evidence = "";
      try {
        const u = await kms.send(new GetKeyLastUsageCommand({ KeyId: keyId }));
        if (u.KeyLastUsage?.Timestamp) {
          lastUsed = u.KeyLastUsage.Timestamp;
          evidence = `${u.KeyLastUsage.Operation ?? ""} (KMS)`;
        } else if (u.KeyCreationDate && u.TrackingStartDate && u.KeyCreationDate < u.TrackingStartDate) {
          // No use since tracking began, but the key is older than tracking: check CloudTrail.
          const ev = await lastTrailEvent(md.Arn ?? keyId);
          if (ev) [lastUsed, evidence] = [ev.time, `${ev.name} (CloudTrail)`];
          else evidence = `no use since ${u.TrackingStartDate.toISOString().slice(0, 10)}`;
        } else {
          evidence = "never used since creation";
        }
      } catch (err) {
        evidence = `can't read usage: ${err instanceof Error ? err.name : String(err)}`;
      }

      const unused = !evidence.startsWith("can't") && (!lastUsed || lastUsed.getTime() < cutoff);
      if (unused && md.KeyState === "Enabled") unusedCost += KEY_PER_MONTH;
      rows.push({
        Key: keyId,
        Aliases: (aliases.get(keyId) ?? []).join(", "),
        State: md.KeyState ?? "",
        Spec: md.KeySpec ?? "",
        Created: md.CreationDate?.toISOString().slice(0, 10) ?? "",
        "Last used": lastUsed ? lastUsed.toISOString().slice(0, 10) : "-",
        Evidence: evidence,
        Verdict: evidence.startsWith("can't") ? "CHECK" : unused ? "UNUSED" : "in use",
      });
    }
  }

  console.table(rows);
  console.log(`Enabled keys with no use in ${days} days: at least $${unusedCost.toFixed(2)}/month.`);
  console.log("Report only. Disable a key and watch CloudTrail for DisabledException before scheduling deletion.");
}

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

npm install @aws-sdk/client-kms @aws-sdk/client-cloudtrail
npm install --save-dev tsx typescript

# Keys with no cryptographic use in the last 90 days
AWS_PROFILE=security-audit AWS_REGION=us-east-1 npx tsx find-unused-kms-keys.ts

# A stricter 30-day window
AWS_PROFILE=security-audit AWS_REGION=eu-central-1 npx tsx find-unused-kms-keys.ts --days 30

┌─────────┬────────────────────────────────────────┬───────────────────────┬────────────┬─────────────────────┬──────────────┬──────────────┬───────────────────────────────────────────┬──────────┐
│ (index) │ Key                                    │ Aliases               │ State      │ Spec                │ Created      │ Last used    │ Evidence                                  │ Verdict  │
├─────────┼────────────────────────────────────────┼───────────────────────┼────────────┼─────────────────────┼──────────────┼──────────────┼───────────────────────────────────────────┼──────────┤
│ 0       │ '1234abcd-12ab-34cd-56ef-1234567890ab' │ 'alias/app-data'      │ 'Enabled'  │ 'SYMMETRIC_DEFAULT' │ '2023-03-14' │ '2026-09-26' │ 'Decrypt (KMS)'                           │ 'in use' │
│ 1       │ '2345bcde-23bc-45de-67fa-2345678901bc' │ 'alias/old-etl'       │ 'Enabled'  │ 'SYMMETRIC_DEFAULT' │ '2022-11-02' │ '-'          │ 'no use since 2026-03-11'                 │ 'UNUSED' │
│ 2       │ '3456cdef-34cd-56ef-78ab-3456789012cd' │ ''                    │ 'Disabled' │ 'RSA_2048'          │ '2025-06-20' │ '-'          │ 'never used since creation'               │ 'UNUSED' │
│ 3       │ '4567defa-45de-67fa-89bc-4567890123de' │ 'alias/partner-share' │ 'Enabled'  │ 'SYMMETRIC_DEFAULT' │ '2024-01-09' │ '-'          │ "can't read usage: AccessDeniedException" │ 'CHECK'  │
└─────────┴────────────────────────────────────────┴───────────────────────┴────────────┴─────────────────────┴──────────────┴──────────────┴───────────────────────────────────────────┴──────────┘
Enabled keys with no use in 90 days: at least $1.00/month.
Report only. Disable a key and watch CloudTrail for DisabledException before scheduling deletion.