Find the First Free IP Address in a VPC Subnet

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadSubnetsAndInterfaces",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeSubnets",
        "ec2:DescribeNetworkInterfaces"
      ],
      "Resource": "*"
    }
  ]
}

// first-free-ip.ts
// Finds the first IPv4 address in a subnet that isn't reserved by AWS and isn't used by any
// network interface (including IPv4 prefixes delegated to interfaces). Read-only.
// Usage: npx tsx first-free-ip.ts subnet-0abc123 | vpc-0def456
import {
  EC2Client,
  paginateDescribeSubnets,
  paginateDescribeNetworkInterfaces,
  type Subnet,
} from "@aws-sdk/client-ec2";

const target = process.argv[2];
if (!target?.startsWith("subnet-") && !target?.startsWith("vpc-")) {
  throw new Error("Pass a subnet ID (subnet-...) or a VPC ID (vpc-...)");
}
const region = process.env.AWS_REGION ?? "us-east-1";
const ec2 = new EC2Client({ region });

// --- IPv4 CIDR math on unsigned 32-bit integers
function ipToInt(ip: string): number {
  const parts = ip.split(".").map(Number);
  if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
    throw new Error(`Not an IPv4 address: ${ip}`);
  }
  return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
}
const intToIp = (n: number): string => [n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join(".");

function parseCidr(cidr: string): { first: number; last: number; prefix: number } {
  const [ip, bits] = cidr.split("/");
  const prefix = Number(bits);
  if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) throw new Error(`Bad prefix in ${cidr}`);
  // Shifting by 32 is a no-op in JavaScript, so /0 needs its own case.
  const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
  const first = (ipToInt(ip) & mask) >>> 0;
  const size = 2 ** (32 - prefix);
  return { first, last: first + size - 1, prefix };
}

async function subnetsFor(id: string): Promise<Subnet[]> {
  const input = id.startsWith("vpc-")
    ? { Filters: [{ Name: "vpc-id", Values: [id] }] }
    : { SubnetIds: [id] };
  const subnets: Subnet[] = [];
  for await (const page of paginateDescribeSubnets({ client: ec2 }, input)) subnets.push(...(page.Subnets ?? []));
  // IPv6-only subnets have no IPv4 CidrBlock, so there's nothing to allocate.
  return subnets.filter((s) => s.CidrBlock).sort((a, b) => ipToInt(a.CidrBlock!.split("/")[0]) - ipToInt(b.CidrBlock!.split("/")[0]));
}

async function usedAddresses(subnetId: string): Promise<{ used: Set<number>; enis: number }> {
  const used = new Set<number>();
  let enis = 0;
  const filter = { Filters: [{ Name: "subnet-id", Values: [subnetId] }] };
  for await (const page of paginateDescribeNetworkInterfaces({ client: ec2 }, filter)) {
    for (const eni of page.NetworkInterfaces ?? []) {
      enis++;
      for (const a of eni.PrivateIpAddresses ?? []) if (a.PrivateIpAddress) used.add(ipToInt(a.PrivateIpAddress));
      // Prefix delegation hands a whole /28 to one interface.
      for (const p of eni.Ipv4Prefixes ?? []) {
        if (!p.Ipv4Prefix) continue;
        const { first, last } = parseCidr(p.Ipv4Prefix);
        for (let n = first; n <= last; n++) used.add(n);
      }
    }
  }
  return { used, enis };
}

async function main(): Promise<void> {
  const subnets = await subnetsFor(target);
  if (subnets.length === 0) throw new Error(`No subnets found for ${target} in ${region}`);

  for (const subnet of subnets) {
    const { first, last, prefix } = parseCidr(subnet.CidrBlock!);
    // AWS reserves the first four addresses and the last one in every subnet.
    const reserved = [first, first + 1, first + 2, first + 3, last];
    const { used, enis } = await usedAddresses(subnet.SubnetId!);

    let firstFree: number | undefined;
    let free = 0;
    for (let n = first + 4; n <= last - 1; n++) {
      if (used.has(n)) continue;
      free++;
      if (firstFree === undefined) firstFree = n;
    }

    console.log(`${subnet.SubnetId} ${subnet.CidrBlock} (${subnet.AvailabilityZone})`);
    console.log(`  size /${prefix}: ${last - first + 1} addresses, reserved by AWS: ${reserved.map(intToIp).join(", ")}`);
    console.log(`  in use: ${used.size} address(es) on ${enis} network interface(s)`);
    console.log(`  free by this scan: ${free} | AvailableIpAddressCount from EC2: ${subnet.AvailableIpAddressCount}`);
    console.log(`  first free address: ${firstFree === undefined ? "none, the subnet is full" : intToIp(firstFree)}\n`);
  }
}

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

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

# One subnet
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx first-free-ip.ts subnet-0abc1234def567890

# Every subnet in a VPC, sorted by address
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx first-free-ip.ts vpc-0123456789abcdef0

subnet-0abc1234def567890 10.0.1.0/24 (us-east-1a)
  size /24: 256 addresses, reserved by AWS: 10.0.1.0, 10.0.1.1, 10.0.1.2, 10.0.1.3, 10.0.1.255
  in use: 7 address(es) on 6 network interface(s)
  free by this scan: 244 | AvailableIpAddressCount from EC2: 244
  first free address: 10.0.1.6

subnet-0def5678abc901234 10.0.2.0/28 (us-east-1b)
  size /28: 16 addresses, reserved by AWS: 10.0.2.0, 10.0.2.1, 10.0.2.2, 10.0.2.3, 10.0.2.15
  in use: 11 address(es) on 11 network interface(s)
  free by this scan: 0 | AvailableIpAddressCount from EC2: 0
  first free address: none, the subnet is full