Check EC2 Patch Compliance With Systems Manager

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadPatchCompliance",
      "Effect": "Allow",
      "Action": [
        "ssm:DescribeInstanceInformation",
        "ssm:DescribeInstancePatchStates",
        "ssm:DescribePatchBaselines",
        "ssm:ListComplianceSummaries"
      ],
      "Resource": "*"
    }
  ]
}

// ssm-patch-compliance-report.ts
// Builds a patch compliance report for every Systems Manager managed node: missing, failed and
// pending-reboot patches, the baseline used, when the node was last scanned, and nodes never scanned.
// Report only: it never runs AWS-RunPatchBaseline or installs anything.
// Usage:
//   npx tsx ssm-patch-compliance-report.ts [--regions us-east-1,eu-west-1] [--max-age-days 7] [--all]
import {
  SSMClient,
  paginateDescribeInstanceInformation,
  paginateDescribeInstancePatchStates,
  paginateDescribePatchBaselines,
  paginateListComplianceSummaries,
  type InstanceInformation,
  type InstancePatchState,
} from "@aws-sdk/client-ssm";

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 regions = (flag("--regions") ?? process.env.AWS_REGION ?? "us-east-1")
  .split(",")
  .map((s) => s.trim())
  .filter(Boolean);
const maxAgeDays = Number(flag("--max-age-days") ?? "7");
const showAll = args.includes("--all"); // include compliant nodes in the table

interface Row {
  Region: string;
  Node: string;
  Platform: string;
  Ping: string;
  PatchGroup: string;
  Baseline: string;
  Missing: number;
  Failed: number;
  PendingReboot: number;
  Critical: number;
  Security: number;
  LastOp: string;
  LastRun: string;
  Verdict: string;
}

function judge(info: InstanceInformation, st: InstancePatchState | undefined): string {
  if (!st) return "NEVER SCANNED";
  const problems: string[] = [];
  if ((st.FailedCount ?? 0) > 0) problems.push("FAILED");
  if ((st.MissingCount ?? 0) > 0 || (st.InstalledRejectedCount ?? 0) > 0) problems.push("NON-COMPLIANT");
  if ((st.InstalledPendingRebootCount ?? 0) > 0) problems.push("REBOOT");
  const ageDays = st.OperationEndTime ? (Date.now() - st.OperationEndTime.getTime()) / 86_400_000 : Infinity;
  if (ageDays > maxAgeDays) problems.push("STALE");
  if (info.PingStatus !== "Online") problems.push("OFFLINE");
  return problems.length ? problems.join(" ") : "OK";
}

async function scanRegion(region: string): Promise<Row[]> {
  const ssm = new SSMClient({ region });

  const nodes: InstanceInformation[] = [];
  for await (const page of paginateDescribeInstanceInformation({ client: ssm }, {})) {
    nodes.push(...(page.InstanceInformationList ?? []));
  }

  const baselineName = new Map<string, string>();
  for await (const page of paginateDescribePatchBaselines({ client: ssm }, {})) {
    for (const b of page.BaselineIdentities ?? []) {
      if (b.BaselineId) baselineName.set(b.BaselineId, b.BaselineName ?? b.BaselineId);
    }
  }

  // DescribeInstancePatchStates takes at most 50 node IDs per request.
  const states = new Map<string, InstancePatchState>();
  const ids = nodes.map((n) => n.InstanceId ?? "").filter(Boolean);
  for (let i = 0; i < ids.length; i += 50) {
    const input = { InstanceIds: ids.slice(i, i + 50) };
    for await (const page of paginateDescribeInstancePatchStates({ client: ssm }, input)) {
      for (const s of page.InstancePatchStates ?? []) {
        if (s.InstanceId) states.set(s.InstanceId, s);
      }
    }
  }

  // The account-level count Systems Manager Compliance shows for the Patch type.
  for await (const page of paginateListComplianceSummaries(
    { client: ssm },
    { Filters: [{ Key: "ComplianceType", Values: ["Patch"], Type: "EQUAL" }] },
  )) {
    for (const s of page.ComplianceSummaryItems ?? []) {
      console.log(
        `${region} ${s.ComplianceType}: ${s.CompliantSummary?.CompliantCount ?? 0} compliant, ` +
          `${s.NonCompliantSummary?.NonCompliantCount ?? 0} non-compliant`,
      );
    }
  }

  return nodes.map((n) => {
    const st = states.get(n.InstanceId ?? "");
    return {
      Region: region,
      Node: n.ComputerName ? `${n.InstanceId} (${n.ComputerName.slice(0, 20)})` : n.InstanceId ?? "?",
      Platform: `${n.PlatformName ?? n.PlatformType ?? "?"} ${n.PlatformVersion ?? ""}`.trim().slice(0, 28),
      Ping: n.PingStatus ?? "?",
      PatchGroup: st?.PatchGroup ?? "",
      Baseline: st ? baselineName.get(st.BaselineId ?? "") ?? st.BaselineId ?? "" : "",
      Missing: st?.MissingCount ?? 0,
      Failed: st?.FailedCount ?? 0,
      PendingReboot: st?.InstalledPendingRebootCount ?? 0,
      Critical: st?.CriticalNonCompliantCount ?? 0,
      Security: st?.SecurityNonCompliantCount ?? 0,
      LastOp: st?.Operation ?? "",
      LastRun: st?.OperationEndTime ? st.OperationEndTime.toISOString().slice(0, 10) : "",
      Verdict: judge(n, st),
    };
  });
}

async function main(): Promise<void> {
  const rows: Row[] = [];
  for (const region of regions) {
    try {
      rows.push(...(await scanRegion(region)));
    } catch (err) {
      console.error(`${region}: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`);
    }
  }
  rows.sort((a, b) => Number(a.Verdict === "OK") - Number(b.Verdict === "OK") || b.Critical - a.Critical || b.Missing - a.Missing);
  const shown = showAll ? rows : rows.filter((r) => r.Verdict !== "OK");
  if (shown.length) console.table(shown);
  const bad = rows.filter((r) => r.Verdict !== "OK").length;
  console.log(`${rows.length} managed nodes in ${regions.join(", ")}; ${bad} need attention (stale = no patch operation in ${maxAgeDays} days).`);
  console.log("Report only. Patch through a maintenance window or a Patch Manager patch policy.");
}

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

npm install @aws-sdk/client-ssm
npm install --save-dev tsx typescript @types/node

# Nodes that need attention in two Regions
AWS_PROFILE=readonly npx tsx ssm-patch-compliance-report.ts --regions us-east-1,eu-west-1

# Every node, treating scans older than 14 days as stale
AWS_PROFILE=readonly npx tsx ssm-patch-compliance-report.ts --regions us-east-1 --max-age-days 14 --all

us-east-1 Patch: 50 compliant, 2 non-compliant
┌─────────┬─────────────┬──────────────────────────────────────────────┬────────────────────────────────┬──────────────────┬────────────┬─────────────────────────┬─────────┬────────┬───────────────┬──────────┬──────────┬───────────┬──────────────┬────────────────────────┐
│ (index) │ Region      │ Node                                         │ Platform                       │ Ping             │ PatchGroup │ Baseline                │ Missing │ Failed │ PendingReboot │ Critical │ Security │ LastOp    │ LastRun      │ Verdict                │
├─────────┼─────────────┼──────────────────────────────────────────────┼────────────────────────────────┼──────────────────┼────────────┼─────────────────────────┼─────────┼────────┼───────────────┼──────────┼──────────┼───────────┼──────────────┼────────────────────────┤
│ 0       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60001 (ip-10-0-1-12.ec2.int)' │ 'Amazon Linux 2023'            │ 'Online'         │ 'prod'     │ 'prod-linux-baseline'   │ 7       │ 0      │ 2             │ 3        │ 5        │ 'Scan'    │ '2026-09-28' │ 'NON-COMPLIANT REBOOT' │
│ 1       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60002'                        │ 'Microsoft Windows Server 202' │ 'ConnectionLost' │ 'prod'     │ 'prod-windows-baseline' │ 0       │ 0      │ 0             │ 0        │ 0        │ 'Install' │ '2026-09-09' │ 'STALE OFFLINE'        │
│ 2       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60003'                        │ 'Ubuntu 22.04'                 │ 'Online'         │ ''         │ ''                      │ 0       │ 0      │ 0             │ 0        │ 0        │ ''        │ ''           │ 'NEVER SCANNED'        │
└─────────┴─────────────┴──────────────────────────────────────────────┴────────────────────────────────┴──────────────────┴────────────┴─────────────────────────┴─────────┴────────┴───────────────┴──────────┴──────────┴───────────┴──────────────┴────────────────────────┘
53 managed nodes in us-east-1; 3 need attention (stale = no patch operation in 7 days).
Report only. Patch through a maintenance window or a Patch Manager patch policy.