Home

Awesome

cidr-tools

Tools to work with IPv4 and IPv6 CIDR

Usage

import {mergeCidr, excludeCidr, expandCidr, overlapCidr, containsCidr, normalizeCidr, parseCidr} from "cidr-tools";

mergeCidr(["1.0.0.0/24", "1.0.1.0/24"]);
//=> ["1.0.0.0/23"]

excludeCidr(["::1/127"], "::1/128");
//=> ["::/128"]

Array.from(expandCidr(["2001:db8::/126"]));
//=> ["2001:db8::", "2001:db8::1", "2001:db8::2", "2001:db8::3"]

overlapCidr("1.0.0.0/24", "1.0.0.128/25");
//=> true

containsCidr(["1.0.0.0/24", "2.0.0.0/24"], "1.0.0.1");
//=> true

normalizeCidr("::ffff/64");
//=> "::/64"

parseCidr("::/64");
// => {cidr: "::/64", version: 6, prefix: "64", start: 0n, end: 18446744073709551615n}

API

All functions take CIDR addresses or single IP addresses. On single addresses, a prefix of /32 or /128 is assumed. Function that return networks will return a merged and sorted set of networks with IPv4 sorted before IPv6.

It is expected that the passed CIDRs and IPs are validated as the module's own input validation is rudimentary. You are encouraged to use modules like is-cidr and is-ip to validate before passing to this module.

This module requires BigInt support in your environment.

mergeCidr(networks)

Returns an array of merged networks.

excludeCidr(baseNetworks, excludeNetworks)

Returns an array of merged remaining networks of the subtraction of excludeNetworks from baseNetworks.

expandCidr(networks)

Returns a generator for individual IPs contained in the networks.

Be aware that passing large networks that contain millions of IPs can result in memory exhaustion and slow execution time. It's recommended to validate the amount of IPs first, for example, like this:

import {parseCidr} from "cidr-tools";

const {start, end} = parseCidr("1.2.3.4/2");
if (end - start >= 1000000n) {
  throw new Error("Too many IPs");
}

overlapCidr(networksA, networksB)

Returns a boolean that indicates if networksA overlap (intersect) with networksB.

containsCidr(networksA, networksB)

Returns a boolean that indicates whether networksA fully contain all networksB.

normalizeCidr(networks, [opts])

Returns a string or array (depending on input) with a normalized representation. Will not include a prefix on single IPs. Will set network address to the start of the network.

opts: Object

parseCidr(network)

Returns a parsed Object which is used internally by this module. It can be used to test whether the passed network is IPv4 or IPv6 or to work with the BigInts directly.

parsed: Object

Related

© silverwind, distributed under BSD licence.