AWS VPN Tunnel Down? Check Site-to-Site VPN Tunnel Status

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadVpnConnectionsAndAlarms",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpnConnections",
        "cloudwatch:DescribeAlarms"
      ],
      "Resource": "*"
    }
  ]
}

// check-site-to-site-vpn-tunnels.ts
// Reports the status of both tunnels of every Site-to-Site VPN connection, flags connections with a
// tunnel down, BGP tunnels with no accepted routes, tunnel options worth a look, and connections with
// no CloudWatch TunnelState alarm. Report only. Exits with code 2 when any connection has both tunnels down.
// Usage:
//   npx tsx check-site-to-site-vpn-tunnels.ts [--regions us-east-1,eu-west-1]
import { CloudWatchClient, paginateDescribeAlarms } from "@aws-sdk/client-cloudwatch";
import { DescribeVpnConnectionsCommand, EC2Client, type VgwTelemetry, type VpnConnection } from "@aws-sdk/client-ec2";

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);

interface Row {
  Region: string;
  VPN: string;
  Routing: string;
  Tunnel1: string;
  Tunnel2: string;
  Alarm: string;
  Findings: string;
}

const day = (d: Date | undefined) => (d ? d.toISOString().slice(0, 16).replace("T", " ") : "?");

function describeTunnel(t: VgwTelemetry | undefined): string {
  if (!t) return "missing";
  const msg = t.StatusMessage ? ` "${t.StatusMessage}"` : "";
  return `${t.Status ?? "?"} since ${day(t.LastStatusChange)}, ${t.AcceptedRouteCount ?? 0} routes${msg}`;
}

// VPN IDs and tunnel IPs that already have a CloudWatch alarm on AWS/VPN TunnelState.
async function alarmedTargets(cw: CloudWatchClient): Promise<Set<string>> {
  const targets = new Set<string>();
  for await (const page of paginateDescribeAlarms({ client: cw }, {})) {
    for (const alarm of page.MetricAlarms ?? []) {
      if (alarm.Namespace !== "AWS/VPN" || alarm.MetricName !== "TunnelState") continue;
      for (const d of alarm.Dimensions ?? []) {
        if ((d.Name === "VpnId" || d.Name === "TunnelIpAddress") && d.Value) targets.add(d.Value);
      }
    }
  }
  return targets;
}

function check(region: string, vpn: VpnConnection, alarms: Set<string>): { row: Row; outage: boolean } {
  const findings: string[] = [];
  const id = vpn.VpnConnectionId ?? "?";
  const name = vpn.Tags?.find((t) => t.Key === "Name")?.Value;
  const staticRoutes = vpn.Options?.StaticRoutesOnly === true;
  const tunnels = vpn.VgwTelemetry ?? [];
  const down = tunnels.filter((t) => t.Status !== "UP");

  if (tunnels.length > 0 && down.length === tunnels.length) {
    findings.push("OUTAGE: every tunnel is DOWN");
  } else if (down.length > 0) {
    findings.push(`no redundancy: ${down.map((t) => t.OutsideIpAddress).join(", ")} DOWN`);
  }
  if (!staticRoutes) {
    for (const t of tunnels) {
      if (t.Status === "UP" && (t.AcceptedRouteCount ?? 0) === 0) findings.push(`${t.OutsideIpAddress} UP with 0 BGP routes`);
    }
  }

  // Tunnel options are matched to telemetry by the AWS-side outside IP address.
  for (const opt of vpn.Options?.TunnelOptions ?? []) {
    const ip = opt.OutsideIpAddress ?? "?";
    if (opt.IkeVersions?.some((v) => v.Value === "ikev1")) findings.push(`${ip} allows IKEv1`);
    if (opt.StartupAction !== "start" && opt.DpdTimeoutAction !== "restart") {
      findings.push(`${ip} waits for your device to re-initiate`);
    }
    if (opt.LogOptions?.CloudWatchLogOptions?.LogEnabled !== true) findings.push(`${ip} tunnel logs off`);
  }

  const hasAlarm = alarms.has(id) || tunnels.some((t) => t.OutsideIpAddress !== undefined && alarms.has(t.OutsideIpAddress));
  if (!hasAlarm) findings.push("no TunnelState alarm");

  const target = vpn.TransitGatewayId ?? vpn.VpnGatewayId ?? vpn.CoreNetworkArn ?? "?";
  return {
    row: {
      Region: region,
      VPN: name ? `${id} (${name}) -> ${target}` : `${id} -> ${target}`,
      Routing: staticRoutes ? "static" : "BGP",
      Tunnel1: describeTunnel(tunnels[0]),
      Tunnel2: describeTunnel(tunnels[1]),
      Alarm: hasAlarm ? "yes" : "no",
      Findings: findings.join("; ") || "ok",
    },
    outage: tunnels.length > 0 && down.length === tunnels.length,
  };
}

async function main(): Promise<void> {
  const rows: Row[] = [];
  let outages = 0;
  for (const region of regions) {
    try {
      const ec2 = new EC2Client({ region });
      const cw = new CloudWatchClient({ region });
      // DescribeVpnConnections isn't paginated; it returns every matching connection in one call.
      const res = await ec2.send(new DescribeVpnConnectionsCommand({ Filters: [{ Name: "state", Values: ["available"] }] }));
      const alarms = await alarmedTargets(cw);
      for (const vpn of res.VpnConnections ?? []) {
        const { row, outage } = check(region, vpn, alarms);
        rows.push(row);
        if (outage) outages++;
      }
    } catch (err) {
      console.error(`${region}: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`);
    }
  }
  console.log(`Site-to-Site VPN connections: ${rows.length}, with every tunnel down: ${outages}`);
  if (rows.length > 0) console.table(rows);
  console.log("Report only. No VPN, tunnel or alarm settings were changed.");
  if (outages > 0) process.exitCode = 2;
}

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

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

# Check every VPN connection in two Regions
AWS_PROFILE=readonly npx tsx check-site-to-site-vpn-tunnels.ts --regions eu-west-2,us-east-1
echo "exit code: $?"

Site-to-Site VPN connections: 2, with every tunnel down: 1
┌─────────┬─────────────┬─────────────────────────────────┬──────────┬─────────────────────────────────────────┬─────────────────────────────────────────┬───────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ (index) │ Region      │ VPN                             │ Routing  │ Tunnel1                                 │ Tunnel2                                 │ Alarm │ Findings                                                                                                                                       │
├─────────┼─────────────┼─────────────────────────────────┼──────────┼─────────────────────────────────────────┼─────────────────────────────────────────┼───────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 0       │ 'eu-west-2' │ 'vpn-0a1 (dc-london) -> vgw-01' │ 'BGP'    │ 'DOWN since 2027-09-06 08:14, 0 routes' │ 'UP since 2027-08-30 22:01, 4 routes'   │ 'yes' │ 'no redundancy: 203.0.113.10 DOWN; 203.0.113.10 allows IKEv1; 203.0.113.10 waits for your device to re-initiate; 203.0.113.10 tunnel logs off' │
│ 1       │ 'eu-west-2' │ 'vpn-0b2 -> tgw-02'             │ 'static' │ 'DOWN since 2027-09-07 01:00, 0 routes' │ 'DOWN since 2027-09-07 01:02, 0 routes' │ 'no'  │ 'OUTAGE: every tunnel is DOWN; no TunnelState alarm'                                                                                           │
└─────────┴─────────────┴─────────────────────────────────┴──────────┴─────────────────────────────────────────┴─────────────────────────────────────────┴───────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Report only. No VPN, tunnel or alarm settings were changed.
exit code: 2

aws cloudwatch put-metric-alarm \
  --alarm-name vpn-0b2-tunnel-down \
  --namespace AWS/VPN --metric-name TunnelState \
  --dimensions Name=VpnId,Value=vpn-0b2 \
  --statistic Minimum --period 300 --evaluation-periods 1 \
  --threshold 0.5 --comparison-operator LessThanOrEqualToThreshold \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:network-alerts