mcp-aws-manager 0.1.0

package/bin/mcp-aws-manager.js

@@ -0,0 +1,1160 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const net = require("node:net");
+
+const DEFAULT_SSH_USERNAMES = ["ec2-user", "ubuntu", "admin", "root"];
+const TOTAL_STEPS = 9;
+
+const PEM_BODY_RE =
+  /-----BEGIN [^-]+-----\s+([A-Za-z0-9+/=\r\n]+)-----END [^-]+-----/m;
+const BASE64_RE = /^[A-Za-z0-9+/=]+$/;
+const HEXISH_RE = /^[0-9a-fA-F:]+$/;
+
+function eprint(message) {
+  process.stderr.write(String(message) + "\n");
+}
+
+function progress(config, step, title) {
+  if (config.noProgress) {
+    return;
+  }
+  eprint(`[${step}/${TOTAL_STEPS}] ${title}`);
+}
+
+function envText(name) {
+  const value = process.env[name];
+  if (value == null) {
+    return null;
+  }
+  const trimmed = String(value).trim();
+  return trimmed || null;
+}
+
+function envBool(name) {
+  const value = envText(name);
+  if (!value) {
+    return false;
+  }
+  return ["1", "true", "yes", "on"].includes(value.toLowerCase());
+}
+
+function parseCsvList(raw) {
+  if (!raw) {
+    return null;
+  }
+  const items = String(raw)
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean);
+  return items.length ? items : null;
+}
+
+function listPemFilesInDirectory(directory) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isFile() && path.extname(entry.name).toLowerCase() === ".pem")
+    .map((entry) => path.join(directory, entry.name))
+    .sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+}
+
+function usageText() {
+  return [
+    "Usage: mcp-aws-manager [options]",
+    "",
+    "Discover AWS EC2 instances with public IPv4 addresses and match them against",
+    "a PEM key fingerprint. Optionally test SSH connectivity.",
+    "",
+    "Options:",
+    "  --pem-path <path[,..]>    Path to PEM private key file(s), comma-separated",
+    "  --profiles <a,b,c>        AWS profile names; default: all local profiles or default chain",
+    "  --regions <a,b,c>         AWS regions; default: DescribeRegions per profile",
+    "  --format <json|csv>       Output format (default: json)",
+    "  --out <path>              Write output to file instead of stdout",
+    "  --key-name <name>         Fallback EC2 KeyPair name for matching",
+    "  --ssh-check               Attempt SSH authentication using PEM key(s) (optional)",
+    "  --ssh-usernames <a,b,c>   SSH usernames to try (default: ec2-user,ubuntu,admin,root)",
+    "  --ssh-timeout <seconds>   SSH timeout (default: 5)",
+    "  --matched-only            Emit only matched instances",
+    "  --progress                Show step progress logs on stderr (default: off)",
+    "  --no-progress             Suppress step progress logs on stderr (default)",
+    "  -h, --help                Show this help",
+    "",
+    "PEM path resolution order:",
+    "  1) --pem-path",
+    "  2) MCP_AWS_PEM_PATH",
+    "  3) all *.pem files in current working directory",
+    "",
+    "Environment variable fallbacks:",
+    "  MCP_AWS_PEM_PATH, MCP_AWS_PROFILES, MCP_AWS_REGIONS, MCP_AWS_FORMAT,",
+    "  MCP_AWS_OUT, MCP_AWS_KEY_NAME, MCP_AWS_SSH_CHECK, MCP_AWS_SSH_USERS,",
+    "  MCP_AWS_SSH_TIMEOUT, MCP_AWS_MATCHED_ONLY, MCP_AWS_NO_PROGRESS",
+    ""
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const options = {
+    pemPath: null,
+    profiles: null,
+    regions: null,
+    format: null,
+    outPath: null,
+    keyName: null,
+    sshCheck: false,
+    sshUsernames: null,
+    sshTimeout: null,
+    matchedOnly: false,
+    noProgress: null,
+    help: false
+  };
+
+  const args = Array.from(argv);
+
+  function setOption(key, value) {
+    switch (key) {
+      case "pem-path":
+        options.pemPath = value;
+        break;
+      case "profiles":
+        options.profiles = value;
+        break;
+      case "regions":
+        options.regions = value;
+        break;
+      case "format":
+        options.format = value;
+        break;
+      case "out":
+        options.outPath = value;
+        break;
+      case "key-name":
+        options.keyName = value;
+        break;
+      case "ssh-usernames":
+        options.sshUsernames = value;
+        break;
+      case "ssh-timeout":
+        options.sshTimeout = value;
+        break;
+      default:
+        throw new Error(`Unknown option --${key}`);
+    }
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--ssh-check") {
+      options.sshCheck = true;
+      continue;
+    }
+    if (arg === "--matched-only") {
+      options.matchedOnly = true;
+      continue;
+    }
+    if (arg === "--no-progress") {
+      options.noProgress = true;
+      continue;
+    }
+    if (arg === "--progress") {
+      options.noProgress = false;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex !== -1) {
+      const key = arg.slice(2, eqIndex);
+      const value = arg.slice(eqIndex + 1);
+      if (!value) {
+        throw new Error(`Missing value for --${key}`);
+      }
+      setOption(key, value);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (!next || next.startsWith("--")) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    setOption(key, next);
+    i += 1;
+  }
+
+  if (options.help) {
+    return { help: true };
+  }
+
+  const argPemPaths = parseCsvList(options.pemPath);
+  const envPemPaths = parseCsvList(envText("MCP_AWS_PEM_PATH"));
+  let pemPaths = argPemPaths || envPemPaths;
+  let pemPathSource = argPemPaths ? "arg" : envPemPaths ? "env" : "cwd-auto";
+  let autoPemCandidates = [];
+
+  if (!pemPaths) {
+    autoPemCandidates = listPemFilesInDirectory(process.cwd());
+    if (!autoPemCandidates.length) {
+      throw new Error(
+        "No PEM path provided. Use --pem-path, set MCP_AWS_PEM_PATH, or place .pem files in the current working directory."
+      );
+    }
+    pemPaths = autoPemCandidates;
+  }
+  const resolvedPemPaths = resolveUniquePemPaths(pemPaths);
+  if (!resolvedPemPaths.length) {
+    throw new Error(
+      "No usable PEM path provided. Use --pem-path, set MCP_AWS_PEM_PATH, or place .pem files in the current working directory."
+    );
+  }
+
+  const format = (options.format || envText("MCP_AWS_FORMAT") || "json").toLowerCase();
+  if (!["json", "csv"].includes(format)) {
+    throw new Error("--format must be one of: json, csv");
+  }
+
+  let sshTimeout = options.sshTimeout;
+  if (sshTimeout == null) {
+    sshTimeout = envText("MCP_AWS_SSH_TIMEOUT") || "5";
+  }
+  const sshTimeoutNumber = Number(sshTimeout);
+  if (!Number.isFinite(sshTimeoutNumber) || sshTimeoutNumber <= 0) {
+    throw new Error("--ssh-timeout must be a positive number");
+  }
+
+  const sshUsernames =
+    parseCsvList(options.sshUsernames) ||
+    parseCsvList(envText("MCP_AWS_SSH_USERS")) ||
+    DEFAULT_SSH_USERNAMES.slice();
+
+  const envNoProgressText = envText("MCP_AWS_NO_PROGRESS");
+  const noProgress =
+    options.noProgress != null
+      ? options.noProgress
+      : envNoProgressText != null
+        ? envBool("MCP_AWS_NO_PROGRESS")
+        : true;
+
+  return {
+    help: false,
+    pemPaths: resolvedPemPaths,
+    pemPath: resolvedPemPaths[0],
+    pemPathSource,
+    autoPemCandidates,
+    profiles:
+      parseCsvList(options.profiles) || parseCsvList(envText("MCP_AWS_PROFILES")),
+    regions: parseCsvList(options.regions) || parseCsvList(envText("MCP_AWS_REGIONS")),
+    format,
+    outPath: options.outPath ? path.resolve(expandHome(options.outPath)) : (envText("MCP_AWS_OUT") ? path.resolve(expandHome(envText("MCP_AWS_OUT"))) : null),
+    keyName: options.keyName || envText("MCP_AWS_KEY_NAME"),
+    sshCheck: Boolean(options.sshCheck || envBool("MCP_AWS_SSH_CHECK")),
+    sshUsernames,
+    sshTimeoutMs: Math.round(sshTimeoutNumber * 1000),
+    matchedOnly: Boolean(options.matchedOnly || envBool("MCP_AWS_MATCHED_ONLY")),
+    noProgress
+  };
+}
+
+function expandHome(value) {
+  if (!value.startsWith("~")) {
+    return value;
+  }
+  const home = os.homedir();
+  if (value === "~") {
+    return home;
+  }
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(home, value.slice(2));
+  }
+  return value;
+}
+
+function uniquePathKey(pemPath) {
+  return process.platform === "win32" ? pemPath.toLowerCase() : pemPath;
+}
+
+function resolveUniquePemPaths(values) {
+  const input = Array.isArray(values) ? values : [];
+  const resolved = [];
+  const seen = new Set();
+  for (const value of input) {
+    const text = String(value || "").trim();
+    if (!text) {
+      continue;
+    }
+    const fullPath = path.resolve(expandHome(text));
+    const key = uniquePathKey(fullPath);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    resolved.push(fullPath);
+  }
+  return resolved;
+}
+
+function validateConfig(config) {
+  const warnings = [];
+
+  if (config.pemPathSource === "cwd-auto") {
+    if (Array.isArray(config.autoPemCandidates) && config.autoPemCandidates.length > 1) {
+      warnings.push(
+        `Auto-selected ${config.autoPemCandidates.length} PEM files from current directory.`
+      );
+    } else if (config.pemPaths.length === 1) {
+      warnings.push(`Auto-selected PEM from current directory: ${config.pemPaths[0]}`);
+    } else {
+      warnings.push(
+        `Auto-selected PEM files from current directory: ${config.pemPaths.join(", ")}`
+      );
+    }
+  }
+
+  if (!Array.isArray(config.pemPaths) || !config.pemPaths.length) {
+    throw new Error("No PEM file paths were resolved.");
+  }
+
+  for (const pemPath of config.pemPaths) {
+    if (!fs.existsSync(pemPath)) {
+      throw new Error(`PEM file not found: ${pemPath}`);
+    }
+    const stat = fs.statSync(pemPath);
+    if (!stat.isFile()) {
+      throw new Error(`PEM path is not a file: ${pemPath}`);
+    }
+    if (path.extname(pemPath).toLowerCase() !== ".pem") {
+      warnings.push(`PEM path does not end with .pem: ${path.basename(pemPath)}`);
+    }
+    if (process.platform !== "win32") {
+      const mode = stat.mode & 0o777;
+      if ((mode & 0o077) !== 0) {
+        warnings.push(
+          `PEM file ${path.basename(pemPath)} is readable by group/others. Consider chmod 600.`
+        );
+      }
+    }
+  }
+
+  if (config.outPath) {
+    fs.mkdirSync(path.dirname(config.outPath), { recursive: true });
+  }
+
+  if (config.sshCheck) {
+    try {
+      require("ssh2");
+    } catch (error) {
+      throw new Error(
+        "--ssh-check requires optional dependency 'ssh2'. Run: npm install ssh2"
+      );
+    }
+  }
+
+  return warnings;
+}
+
+function bufferFromFirstPemDer(pemText) {
+  const match = PEM_BODY_RE.exec(pemText);
+  if (!match) {
+    return null;
+  }
+  const normalized = match[1].replace(/\s+/g, "");
+  try {
+    return Buffer.from(normalized, "base64");
+  } catch {
+    return null;
+  }
+}
+
+function colonHex(hex) {
+  return hex.match(/.{1,2}/g)?.join(":") || hex;
+}
+
+function digestVariants(buffer) {
+  const md5Hex = crypto.createHash("md5").update(buffer).digest("hex");
+  const sha1Hex = crypto.createHash("sha1").update(buffer).digest("hex");
+  const sha256B64 = crypto
+    .createHash("sha256")
+    .update(buffer)
+    .digest("base64")
+    .replace(/=+$/g, "");
+  return [
+    md5Hex,
+    colonHex(md5Hex),
+    sha1Hex,
+    colonHex(sha1Hex),
+    sha256B64,
+    `SHA256:${sha256B64}`
+  ];
+}
+
+function fingerprintMatchKeys(value) {
+  const raw = String(value || "").trim();
+  const keys = new Set();
+  if (!raw) {
+    return keys;
+  }
+
+  keys.add(`raw:${raw}`);
+  keys.add(`raw:${raw.toLowerCase()}`);
+
+  if (raw.toLowerCase().startsWith("sha256:")) {
+    keys.add(`sha256:${raw.slice(raw.indexOf(":") + 1).replace(/=+$/g, "")}`);
+  } else if (BASE64_RE.test(raw) && !HEXISH_RE.test(raw)) {
+    keys.add(`sha256:${raw.replace(/=+$/g, "")}`);
+  }
+
+  if (HEXISH_RE.test(raw)) {
+    const compact = raw.replace(/:/g, "").toLowerCase();
+    if (compact.length % 2 === 0) {
+      keys.add(`hex:${compact}`);
+    }
+  }
+
+  return keys;
+}
+
+function analyzePemKey(pemPath) {
+  const pemText = fs.readFileSync(pemPath, "utf8");
+  const pemRawBuffer = fs.readFileSync(pemPath);
+  const rawDer = bufferFromFirstPemDer(pemText);
+
+  let privateKey;
+  try {
+    privateKey = crypto.createPrivateKey({ key: pemRawBuffer });
+  } catch (error) {
+    throw new Error(`Failed to load PEM private key: ${error.message}`);
+  }
+
+  const publicKey = crypto.createPublicKey(privateKey);
+  const keyType = privateKey.asymmetricKeyType || "unknown";
+
+  const candidates = [];
+  const matchKeys = new Set();
+
+  function addCandidateDigests(buffer) {
+    if (!buffer || !Buffer.isBuffer(buffer)) {
+      return;
+    }
+    for (const candidate of digestVariants(buffer)) {
+      candidates.push(candidate);
+      for (const k of fingerprintMatchKeys(candidate)) {
+        matchKeys.add(k);
+      }
+    }
+  }
+
+  addCandidateDigests(rawDer);
+
+  try {
+    addCandidateDigests(
+      privateKey.export({ format: "der", type: "pkcs8" })
+    );
+  } catch {}
+
+  if (keyType === "rsa") {
+    try {
+      addCandidateDigests(
+        privateKey.export({ format: "der", type: "pkcs1" })
+      );
+    } catch {}
+  }
+  if (keyType === "ec") {
+    try {
+      addCandidateDigests(
+        privateKey.export({ format: "der", type: "sec1" })
+      );
+    } catch {}
+  }
+
+  try {
+    addCandidateDigests(publicKey.export({ format: "der", type: "spki" }));
+  } catch {}
+
+  const uniqueCandidates = [];
+  const seen = new Set();
+  for (const c of candidates) {
+    if (seen.has(c)) {
+      continue;
+    }
+    seen.add(c);
+    uniqueCandidates.push(c);
+  }
+
+  if (!uniqueCandidates.length) {
+    throw new Error("Unable to derive any fingerprints from the PEM key.");
+  }
+
+  const md5Fingerprint =
+    uniqueCandidates.find((v) => v.includes(":") && v.replace(/:/g, "").length === 32) ||
+    null;
+  const sha256Fingerprint =
+    uniqueCandidates.find((v) => v.startsWith("SHA256:")) || null;
+
+  return {
+    pemPath,
+    pemFileName: path.basename(pemPath),
+    keyType,
+    md5Fingerprint,
+    sha256Fingerprint,
+    candidateValues: uniqueCandidates,
+    matchKeys
+  };
+}
+
+function analyzePemKeys(config, warnings) {
+  const analyses = [];
+
+  for (const pemPath of config.pemPaths) {
+    try {
+      analyses.push(analyzePemKey(pemPath));
+    } catch (error) {
+      warnings.push(
+        `PEM analysis skipped for ${path.basename(pemPath)}: ${error.message || String(error)}`
+      );
+    }
+  }
+
+  if (!analyses.length) {
+    throw new Error("No valid PEM keys could be analyzed from the provided paths.");
+  }
+
+  return analyses;
+}
+
+function normalizeName(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
+}
+
+function keyMatchResult(instanceKeyName, keypairFingerprints, pemAnalyses, config) {
+  if (!instanceKeyName) {
+    return { status: "unknown", matchedPemFiles: [], matchedBy: "none" };
+  }
+
+  const awsFp = keypairFingerprints.get(instanceKeyName);
+  if (awsFp) {
+    const awsKeys = fingerprintMatchKeys(awsFp);
+    const matchedPemFiles = [];
+    for (const pemAnalysis of pemAnalyses) {
+      for (const key of awsKeys) {
+        if (pemAnalysis.matchKeys.has(key)) {
+          matchedPemFiles.push(pemAnalysis.pemFileName);
+          break;
+        }
+      }
+    }
+    return {
+      status: matchedPemFiles.length > 0,
+      matchedPemFiles,
+      matchedBy: "fingerprint"
+    };
+  }
+
+  if (config.keyName && instanceKeyName === config.keyName) {
+    return { status: true, matchedPemFiles: [], matchedBy: "key-name" };
+  }
+
+  const normalizedInstanceKeyName = normalizeName(instanceKeyName);
+  if (normalizedInstanceKeyName) {
+    const matchedPemFiles = pemAnalyses
+      .filter(
+        (pemAnalysis) =>
+          normalizedInstanceKeyName ===
+          normalizeName(path.parse(pemAnalysis.pemFileName).name)
+      )
+      .map((pemAnalysis) => pemAnalysis.pemFileName);
+    if (matchedPemFiles.length) {
+      return { status: true, matchedPemFiles, matchedBy: "pem-name" };
+    }
+  }
+
+  return { status: "unknown", matchedPemFiles: [], matchedBy: "none" };
+}
+
+function parseIniSectionNames(text) {
+  const names = new Set();
+  if (!text) {
+    return names;
+  }
+  const lines = text.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith(";") || trimmed.startsWith("#")) {
+      continue;
+    }
+    const match = /^\[([^\]]+)\]$/.exec(trimmed);
+    if (!match) {
+      continue;
+    }
+    names.add(match[1].trim());
+  }
+  return names;
+}
+
+function listLocalAwsProfiles() {
+  const awsDir = path.join(os.homedir(), ".aws");
+  const found = new Set();
+
+  const credentialsPath = path.join(awsDir, "credentials");
+  const configPath = path.join(awsDir, "config");
+
+  if (fs.existsSync(credentialsPath)) {
+    for (const name of parseIniSectionNames(fs.readFileSync(credentialsPath, "utf8"))) {
+      if (name) {
+        found.add(name);
+      }
+    }
+  }
+
+  if (fs.existsSync(configPath)) {
+    for (const name of parseIniSectionNames(fs.readFileSync(configPath, "utf8"))) {
+      if (name === "default") {
+        found.add("default");
+        continue;
+      }
+      if (name.startsWith("profile ")) {
+        found.add(name.slice("profile ".length).trim());
+      }
+    }
+  }
+
+  return Array.from(found).filter(Boolean).sort();
+}
+
+let awsModulesCache = null;
+function loadAwsModules() {
+  if (awsModulesCache) {
+    return awsModulesCache;
+  }
+  try {
+    const ec2 = require("@aws-sdk/client-ec2");
+    const sts = require("@aws-sdk/client-sts");
+    const credentialProviders = require("@aws-sdk/credential-providers");
+    awsModulesCache = { ec2, sts, credentialProviders };
+    return awsModulesCache;
+  } catch (error) {
+    throw new Error(
+      "Missing AWS SDK dependencies. Run: npm install"
+    );
+  }
+}
+
+function baseRegion() {
+  return (
+    envText("AWS_REGION") ||
+    envText("AWS_DEFAULT_REGION") ||
+    "us-east-1"
+  );
+}
+
+function awsClientConfig(profileName, region) {
+  const { credentialProviders } = loadAwsModules();
+  const config = { region };
+  if (profileName) {
+    config.credentials = credentialProviders.fromIni({ profile: profileName });
+  }
+  return config;
+}
+
+function listRequestedProfiles(config) {
+  if (config.profiles && config.profiles.length) {
+    return config.profiles.slice();
+  }
+  const localProfiles = listLocalAwsProfiles();
+  return localProfiles.length ? localProfiles : [null];
+}
+
+async function discoverRegionsForProfile(profileName, profileLabel, warnings) {
+  const { ec2 } = loadAwsModules();
+  const client = new ec2.EC2Client(awsClientConfig(profileName, baseRegion()));
+  try {
+    const response = await client.send(
+      new ec2.DescribeRegionsCommand({ AllRegions: false })
+    );
+    const regions = (response.Regions || [])
+      .map((r) => r.RegionName)
+      .filter(Boolean);
+    if (regions.length) {
+      return Array.from(new Set(regions)).sort();
+    }
+  } catch (error) {
+    warnings.push(
+      `[${profileLabel}] DescribeRegions failed (${error.name || "Error"}); using fallback region ${baseRegion()}`
+    );
+  } finally {
+    client.destroy();
+  }
+  return [baseRegion()];
+}
+
+async function buildDiscoveryPlan(config, warnings) {
+  const { sts } = loadAwsModules();
+  const plans = [];
+
+  for (const profileName of listRequestedProfiles(config)) {
+    const profileLabel = profileName || "default";
+    const stsClient = new sts.STSClient(awsClientConfig(profileName, baseRegion()));
+    try {
+      const identity = await stsClient.send(new sts.GetCallerIdentityCommand({}));
+      const accountId = identity.Account || "unknown";
+      const regions =
+        config.regions && config.regions.length
+          ? config.regions.slice()
+          : await discoverRegionsForProfile(profileName, profileLabel, warnings);
+
+      if (!regions.length) {
+        warnings.push(`[${profileLabel}] No regions resolved; profile skipped.`);
+        continue;
+      }
+
+      plans.push({
+        profileName,
+        profileLabel,
+        accountId,
+        regions
+      });
+    } catch (error) {
+      warnings.push(
+        `[${profileLabel}] Credential/IAM validation failed and profile was skipped: ${error.name || "Error"}: ${error.message}`
+      );
+    } finally {
+      stsClient.destroy();
+    }
+  }
+
+  if (!plans.length) {
+    throw new Error("No usable AWS profiles were found after validation.");
+  }
+
+  return plans;
+}
+
+async function describeKeypairFingerprints(client) {
+  const { ec2 } = loadAwsModules();
+  const result = new Map();
+  let nextToken = undefined;
+
+  do {
+    const resp = await client.send(
+      new ec2.DescribeKeyPairsCommand({ NextToken: nextToken })
+    );
+    for (const item of resp.KeyPairs || []) {
+      if (item.KeyName && item.KeyFingerprint) {
+        result.set(item.KeyName, item.KeyFingerprint);
+      }
+    }
+    nextToken = resp.NextToken;
+  } while (nextToken);
+
+  return result;
+}
+
+function getTagValue(tags, key) {
+  if (!Array.isArray(tags)) {
+    return null;
+  }
+  for (const tag of tags) {
+    if (tag && tag.Key === key) {
+      return tag.Value || null;
+    }
+  }
+  return null;
+}
+
+async function collectEc2Inventory(config, plans, pemAnalyses, warnings) {
+  const { ec2 } = loadAwsModules();
+  const records = [];
+  const stats = { profiles: 0, regions: 0, regionErrors: 0 };
+
+  for (const plan of plans) {
+    stats.profiles += 1;
+
+    for (const region of plan.regions) {
+      stats.regions += 1;
+      const client = new ec2.EC2Client(awsClientConfig(plan.profileName, region));
+      try {
+        const keypairFingerprints = await describeKeypairFingerprints(client);
+        let nextToken = undefined;
+
+        do {
+          const resp = await client.send(
+            new ec2.DescribeInstancesCommand({ NextToken: nextToken })
+          );
+
+          for (const reservation of resp.Reservations || []) {
+            for (const instance of reservation.Instances || []) {
+              if (!instance.PublicIpAddress) {
+                continue;
+              }
+
+              const keyName = instance.KeyName || null;
+              const matchResult = keyMatchResult(
+                keyName,
+                keypairFingerprints,
+                pemAnalyses,
+                config
+              );
+              records.push({
+                profile: plan.profileLabel,
+                accountId: plan.accountId,
+                region,
+                instanceId: instance.InstanceId || null,
+                name: getTagValue(instance.Tags, "Name"),
+                state: instance.State && instance.State.Name ? instance.State.Name : null,
+                publicIp: instance.PublicIpAddress,
+                publicDns: instance.PublicDnsName || null,
+                keyName,
+                keyFingerprintMatch: matchResult.status,
+                matchedPemFiles: matchResult.matchedPemFiles,
+                matchedBy: matchResult.matchedBy,
+                securityGroups: (instance.SecurityGroups || []).map((sg) => ({
+                  id: sg.GroupId || null,
+                  name: sg.GroupName || null
+                })),
+                launchTime: instance.LaunchTime
+                  ? new Date(instance.LaunchTime).toISOString()
+                  : null,
+                sshReachable: null,
+                sshTriedUser: null,
+                sshTriedPem: null
+              });
+            }
+          }
+
+          nextToken = resp.NextToken;
+        } while (nextToken);
+      } catch (error) {
+        stats.regionErrors += 1;
+        warnings.push(
+          `[${plan.profileLabel}/${region}] EC2 collection failed: ${error.name || "Error"}: ${error.message}`
+        );
+      } finally {
+        client.destroy();
+      }
+    }
+  }
+
+  return { records, stats };
+}
+
+async function trySshOnce(host, username, privateKey, timeoutMs) {
+  const { Client } = require("ssh2");
+  return await new Promise((resolve, reject) => {
+    const conn = new Client();
+    let done = false;
+    const timer = setTimeout(() => {
+      if (done) {
+        return;
+      }
+      done = true;
+      try {
+        conn.end();
+      } catch {}
+      reject(new Error("SSH timeout"));
+    }, timeoutMs);
+
+    function finish(err, ok) {
+      if (done) {
+        return;
+      }
+      done = true;
+      clearTimeout(timer);
+      try {
+        conn.end();
+      } catch {}
+      if (err) {
+        reject(err);
+      } else {
+        resolve(ok);
+      }
+    }
+
+    conn
+      .on("ready", () => finish(null, true))
+      .on("error", (err) => finish(err, false))
+      .on("end", () => {
+        if (!done) {
+          finish(new Error("SSH connection ended before ready"), false);
+        }
+      })
+      .connect({
+        host,
+        port: 22,
+        username,
+        privateKey,
+        readyTimeout: timeoutMs
+      });
+  });
+}
+
+async function sshCheckRecords(config, records, pemAnalyses, warnings) {
+  if (!config.sshCheck) {
+    return;
+  }
+
+  const privateKeys = [];
+  for (const pemAnalysis of pemAnalyses) {
+    try {
+      privateKeys.push({
+        pemPath: pemAnalysis.pemPath,
+        pemFileName: pemAnalysis.pemFileName,
+        privateKey: fs.readFileSync(pemAnalysis.pemPath)
+      });
+    } catch (error) {
+      warnings.push(
+        `SSH key load failed for ${pemAnalysis.pemFileName}: ${error.message || String(error)}`
+      );
+    }
+  }
+
+  if (!privateKeys.length) {
+    throw new Error("No PEM keys could be loaded for SSH checks.");
+  }
+
+  for (const record of records) {
+    const host = record.publicIp;
+    if (!host) {
+      continue;
+    }
+
+    let reachable = false;
+    let triedUser = null;
+    let triedPem = null;
+    let stopForHost = false;
+
+    for (const username of config.sshUsernames) {
+      for (const key of privateKeys) {
+        triedUser = username;
+        triedPem = key.pemFileName;
+        try {
+          await trySshOnce(host, username, key.privateKey, config.sshTimeoutMs);
+          reachable = true;
+          break;
+        } catch (error) {
+          const msg = error && error.message ? error.message : String(error);
+          const lower = msg.toLowerCase();
+          if (
+            lower.includes("all configured authentication methods failed") ||
+            lower.includes("authentication")
+          ) {
+            continue;
+          }
+          warnings.push(
+            `[SSH ${record.instanceId || "unknown"} ${host} ${key.pemFileName}] ${msg}`
+          );
+          stopForHost = true;
+          break;
+        }
+      }
+      if (reachable || stopForHost) {
+        break;
+      }
+    }
+
+    record.sshReachable = reachable;
+    record.sshTriedUser = triedUser;
+    record.sshTriedPem = triedPem;
+  }
+}
+
+function aggregateResults(config, records) {
+  let output = records.slice();
+  if (config.matchedOnly) {
+    output = output.filter((r) => r.keyFingerprintMatch === true);
+  }
+  output.sort((a, b) =>
+    [
+      a.profile || "",
+      a.accountId || "",
+      a.region || "",
+      a.instanceId || ""
+    ]
+      .join("|")
+      .localeCompare(
+        [b.profile || "", b.accountId || "", b.region || "", b.instanceId || ""].join("|")
+      )
+  );
+  return output;
+}
+
+function csvEscape(value) {
+  if (value == null) {
+    return "";
+  }
+  const text = String(value);
+  if (/[",\r\n]/.test(text)) {
+    return `"${text.replace(/"/g, "\"\"")}"`;
+  }
+  return text;
+}
+
+function toCsvRow(record) {
+  return {
+    profile: record.profile,
+    accountId: record.accountId,
+    region: record.region,
+    instanceId: record.instanceId,
+    name: record.name,
+    state: record.state,
+    publicIp: record.publicIp,
+    publicDns: record.publicDns,
+    keyName: record.keyName,
+    keyFingerprintMatch: record.keyFingerprintMatch,
+    matchedPemFiles: Array.isArray(record.matchedPemFiles)
+      ? record.matchedPemFiles.join(";")
+      : "",
+    matchedBy: record.matchedBy,
+    securityGroups: (record.securityGroups || [])
+      .map((sg) => `${sg.id || ""}:${sg.name || ""}`.replace(/:$/, ""))
+      .join(";"),
+    launchTime: record.launchTime,
+    sshReachable: record.sshReachable,
+    sshTriedUser: record.sshTriedUser,
+    sshTriedPem: record.sshTriedPem
+  };
+}
+
+function renderOutput(config, outputRecords) {
+  if (config.format === "json") {
+    return JSON.stringify(outputRecords, null, 2);
+  }
+
+  const fields = [
+    "profile",
+    "accountId",
+    "region",
+    "instanceId",
+    "name",
+    "state",
+    "publicIp",
+    "publicDns",
+    "keyName",
+    "keyFingerprintMatch",
+    "matchedPemFiles",
+    "matchedBy",
+    "securityGroups",
+    "launchTime",
+    "sshReachable",
+    "sshTriedUser",
+    "sshTriedPem"
+  ];
+  const lines = [fields.join(",")];
+  for (const record of outputRecords) {
+    const row = toCsvRow(record);
+    lines.push(fields.map((f) => csvEscape(row[f])).join(","));
+  }
+  return lines.join("\n");
+}
+
+function writeOrPrint(config, content) {
+  if (config.outPath) {
+    fs.writeFileSync(config.outPath, content, "utf8");
+    eprint(`Wrote ${config.format.toUpperCase()} output to ${config.outPath}`);
+    return;
+  }
+  process.stdout.write(content);
+  if (!content.endsWith("\n")) {
+    process.stdout.write("\n");
+  }
+}
+
+async function runWorkflow(config) {
+  const warnings = [];
+
+  progress(config, 1, "orchestrator: parse CLI/env parameters");
+  eprint(
+    `Inputs: profiles=${config.profiles ? config.profiles.join(",") : "auto"}, regions=${config.regions ? config.regions.join(",") : "auto"}, format=${config.format}, ssh_check=${config.sshCheck ? "on" : "off"}`
+  );
+
+  progress(config, 2, "config_validator: validate PEM path(s), dependencies, output path");
+  warnings.push(...validateConfig(config));
+
+  progress(config, 3, "pem_key_analyzer: load PEM key(s) and compute fingerprint candidates");
+  const pemAnalyses = analyzePemKeys(config, warnings);
+  eprint(`PEM analysis: loaded=${pemAnalyses.length}/${config.pemPaths.length} key(s)`);
+  for (const pemAnalysis of pemAnalyses) {
+    eprint(
+      `  - ${pemAnalysis.pemFileName}: type=${pemAnalysis.keyType}, md5=${pemAnalysis.md5Fingerprint || "n/a"}, sha256=${pemAnalysis.sha256Fingerprint || "n/a"}`
+    );
+  }
+
+  progress(config, 4, "aws_discovery_planner: validate credentials and resolve profile/region plan");
+  const plans = await buildDiscoveryPlan(config, warnings);
+  eprint(
+    "Discovery plan: " +
+      plans.map((p) => `${p.profileLabel}(${p.regions.length} regions)`).join(", ")
+  );
+
+  progress(config, 5, "ec2_inventory_collector: collect EC2 public IP inventory and key pairs");
+  const { records, stats } = await collectEc2Inventory(
+    config,
+    plans,
+    pemAnalyses,
+    warnings
+  );
+  eprint(`Collected public-IP instances: ${records.length}`);
+
+  progress(config, 6, "ssh_connectivity_checker: optional SSH checks");
+  await sshCheckRecords(config, records, pemAnalyses, warnings);
+
+  progress(config, 7, "result_aggregator: merge inventory and SSH results");
+  const outputRecords = aggregateResults(config, records);
+
+  progress(config, 8, "cli_output_formatter: render JSON/CSV");
+  const rendered = renderOutput(config, outputRecords);
+  writeOrPrint(config, rendered);
+
+  progress(config, 9, "END: summarize execution");
+  const matched = outputRecords.filter((r) => r.keyFingerprintMatch === true).length;
+  const sshChecked = outputRecords.filter((r) => r.sshReachable !== null).length;
+  const sshReachable = outputRecords.filter((r) => r.sshReachable === true).length;
+  eprint(
+    `Summary: pem_keys=${pemAnalyses.length}, profiles=${stats.profiles}, regions_scanned=${stats.regions}, region_errors=${stats.regionErrors}, output_records=${outputRecords.length}, matched=${matched}, ssh_checked=${sshChecked}, ssh_reachable=${sshReachable}, warnings=${warnings.length}`
+  );
+  for (const warning of warnings) {
+    eprint(`WARNING: ${warning}`);
+  }
+
+  return stats.regionErrors > 0 || warnings.length > 0 ? 2 : 0;
+}
+
+async function main() {
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.help) {
+      process.stdout.write(usageText());
+      process.exitCode = 0;
+      return;
+    }
+    const exitCode = await runWorkflow(parsed);
+    process.exitCode = exitCode;
+  } catch (error) {
+    if (error && error.message) {
+      eprint(`ERROR: ${error.message}`);
+    } else {
+      eprint(`ERROR: ${String(error)}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  void main();
+}