Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
The Node.js net.BlockList class
Reference for net.BlockList and net.SocketAddress in Node.js: add addresses, ranges and subnets, check them, and use a list with servers and sockets.
net.BlockList stores IP addresses, ranges and subnets, and answers one question: "is this address on the list?". The name suggests a deny list, but it is only a container with a check() method, so you can equally use it as an allow list. The same class can be passed to net.createServer() (as blockList) or to net.connect() to refuse matching peers.
Entries can be single addresses, inclusive ranges (start to end) or CIDR-style subnets (a prefix and a length). IPv4 and IPv6 are both supported, and an IPv4 address also matches its IPv4-mapped IPv6 form.
import net from 'node:net'; const list = new net.BlockList(); list.addSubnet('10.0.0.0', 8, 'ipv4'); list.check('10.2.3.4'); // true
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
new net.BlockList() blockList.addAddress(address: string | net.SocketAddress, family?: 'ipv4' | 'ipv6'): void blockList.addRange(start: string | net.SocketAddress, end: string | net.SocketAddress, family?): void blockList.addSubnet(net: string | net.SocketAddress, prefix: number, family?): void blockList.check(address: string | net.SocketAddress, family?: 'ipv4' | 'ipv6'): boolean blockList.rules: string[] net.BlockList.isBlockList(value: unknown): boolean
| Name | Description |
|---|---|
address, start, end, net |
An IP string or a net.SocketAddress. |
prefix |
Number of leading bits that must match: 0 to 32 for IPv4, 0 to 128 for IPv6. |
family |
'ipv4' (default) or 'ipv6'. Must match the kind of address you pass. |
Returns: check() returns true if any rule matches. The rules array holds readable descriptions such as Subnet: IPv4 192.168.0.0/16, newest first.
Edge cases: an invalid address or prefix throws ERR_INVALID_ARG_VALUE or ERR_OUT_OF_RANGE. With a wrong family for the string ('::1' as ipv4), the call throws or check() returns false. blockList.toJSON() and BlockList.fromJSON() exist in newer versions to serialize rules.
Usage notes
- Checks are cheap but linear. Each
check()walks all rules; very large lists (thousands of ranges) deserve a smarter structure. - Pass the family for IPv6.
check('::1')with the default'ipv4'family does not do what you expect; always pass'ipv6'for IPv6 text. - Server-side drops. A peer matching
blockListis closed immediately and no'connection'event is fired. The client still sees a completed handshake followed by a close, and the server emits no'drop'(that event is only formaxConnections). - Not a firewall. The connection is still accepted by the operating system first. Use a real firewall for protection against floods.
- Allow lists. Build a list of allowed ranges and use
!list.check(address)to reject everything else. - Mapped addresses. A rule for
1.2.3.4also matches::ffff:1.2.3.4. - Mutable. You can add rules while the server runs; changes apply to later connections.