net: introduce net.BlockList

[jasnell]

This PR introduces the net.BlockList object:

net.BlockList provides an object intended to be used by net APIs to specify rules for disallowing network activity with specific IP addresses. This commit adds the basic mechanism but does not add the
specific uses.

For instance:

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addAddress('::f8f8', 'ipv6');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('123.123.0.0', 16); // subnet 123.123.0.0/16

console.log(blockList.check('123.123.123.123'));   // true!

// IPv6 notation for IPv4 addresses is supported:
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6'));   // true!

While the BlockList can be used on it's own, the intent is for the BlockList object to be passed into existing net APIs. For listen(), the BlockList will be checked as close to the libuv code that accepts the incoming connection as possible. For connect(), it would check as early as possible. These uses have not yet be implemented, however. Those would come in separate PRs.

The QUIC implementation will be the immediate first use of this:

const blockList = new BlockList();
// ... add rules

const sock = net.createQuicSocket({ blockList });
sock.listen();

When listening for new QUIC session requests, any received from blocked IP addresses will be automatically rejected.

The QUIC implementation would also have a setting that would allow misbehaving IP addresses to automatically be added to the configured BlockList (if provided) when a bad behavior threshhold has been reached.

const blockList = new BlockList();
// ... add rules

const sock = net.createQuicSocket({ blockList, autoBlock: true });
sock.listen();

If the QUIC implementation detects, for instance, that a remote IP is misbehaving, after a certain number of detected failures, the remote address would be added automatically to the given blockList if the autoBlock option is true.

The implementation is intentionally not specific to QUIC, however, and may be retrofitted into any of the other net systems.

Some discussion points:

1. This is a block list only. There are no "allow" rules. So, specifically, it would not be possible to say "block everything except this IP". The reason for that choice is Node.js legacy -- the fact that accept everything has always been the default. I'm not intending to change the default behavior, I want to make it easier to respond to bad behavior as it is detected.

2. Once an individual rule has been added, there's no way to remove it individually. There's only a single clear() operation that removes all rules. This is for simplicity in the overall API design and implementation. We can always go back and add the ability to remove individual rules later if necessary.

3. This is implemented at the C++ layer for performance reasons. The overwhelming majority of times this will be used will be with servers, with the check happening as close to libuv as possible. I do not want to incur a JS call cost when performing the check.

4. The internal implementation is not completed. Right now, this only implements the single address rule. Ranges and subnets are not yet implemented.

5. For the initial implementation, I'm focusing on just getting it working. I'm sure there will be better ways of implementing the rules internally and those can be incremented on.

6. There are no JS tests yet, those will come as the implementation continues.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

Lite-CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/4205

[mcollina]

it's not clear how a BlockList is configured on a tcp/udp server.

[jasnell]

@mcollina the specifics on that would come later but.. the general idea is that the block list would either...

1. Be specified as an option when creating the tcp or udp socket, or
2. Be specified as an option when calling listen or bind, or
3. Be created automatically when the tcp or udp socket is created and accessed via a property.

The first two mean that the BlockList does not exist without usercode. The third makes it always available.

[bmeck]

Per topics:

1. This seems good, I think a different configuration mechanism to opt into an accept list approach is reasonable and it would be unreasonable and confusing to change the default without a completely separate mechanism (cli flag, policies, whatever).

2. I think we need to be careful about what gives access to the .clear API. Likely I feel this should be an own property rather than a prototype method (may be an API change if so). In particular I would want to avoid snooping/intercepting via prototype crawling or the ability to intercept already existing BlockLists when code is running. We could state that people using the API must save the safe references like we do in primordials but if the main goal of this includes usability it seems some safe defaults would be good. I feel somewhat less strongly about the additive methods since I don't think adding addresses after startup is as common as at startup, but I do still feel that having the API leak could cause minor issues.

---

Is it possible we might extend other APIs to use a BlockList like when connecting to things using DNS / do we expect growth of use? E.G. if a domain has 2 IPs, blocking 1 would ensure the other is used.

---

It would be nice as a follow on PR to add some kind of way to configure this on the whole process, but I would not want it via a JS API.

[jasnell]

@bmeck:

I think we need to be careful about what gives access to the .clear API.

Currently, the only reason clear() exists is address the possibility that an automatic blocking mechanism could cause legitimate IP addresses to get blocked and we'd need a reset. That's an edge case that could be solved in other ways. I'd be fine with not exposing clear() to JavaScript code at all.

[jasnell]

@bmeck:

Is it possible we might extend other APIs to use a BlockList like when connecting to things using DNS / do we expect growth of use? E.G. if a domain has 2 IPs, blocking 1 would ensure the other is used.

I'd think so yes. Allowing for that kind of flexibility is a key part of the design of this as a standalone component.

It would be nice as a follow on PR to add some kind of way to configure this on the whole process, but I would not want it via a JS API.

Yeah, I've been thinking about that also. What might make sense is allowing BlockList instances to be hierarchical. That would allow us to set a process wide policy while still giving users the flexibility to define their own.

[jasnell]

One key question on this: Is blocking a specific range of IPs important enough to warrant it's own rule vs. blocking a subnet? e.g. 10.0.0.1-10.0.0.10 (blocks only 10 ips) vs. 10.0.0.0/24 (blocks 255).

[bmeck]

@jasnell our internal libs use subnets (even for small sizes of ranges) to my knowledge this is due to CIDR being automatically generated for lots of things. I'm unfamiliar with tools generating that range syntax using -.

[jasnell]

Ok all, the implementation has been updated significantly.

• @bmeck -- I've removed the clear() API. We can address that again later if necessary.
• @addaleax -- the memory tracking has been implemented also

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/32639/

[dougwilson]

Sorry for what maybe a dumb question, but doesn't the lack of an API to remove IPs from the block list make this not very usable for limiting bad behavior in a UDP server (like QUIC)? I don't know what the intention for the QUIC autoBlock feature is, of course, but since it is trivial to spoof the source address in a datagram, a block list that will block indefinitely seems of limited use, as it would simply subject the servers that use it to a denial of service type attack, where the attacker sends datagrams spoofed as if they are coming from their target, with the intention to get the IP blocked.

This of course is not the fault of the block list itself, but how one would use it. Unless the user is careful to only add an IP once it can be verified that the source address of a datagram can be trusted (after the completion of a three way handshake or similar), it seems like an easy method of abuse.

Of course, IP block issues are not limited to just UDP, but even TCP is susceptible, as long as both the attacker and the target are behind the same NAT, so the server sees both parties as having the same IP address.

My point here is not to say this should solve that somehow, but only to say that the lack of an API to remove IPs from the block list seems like a feature that would make a block list unusable, since one could not implement a block list with time-based blocking, for example.

Anyway, I just wanted to throw this out there in case it hasn't been considered yet. I'm not here to say don't land this or anything, etc. Great work!

[jasnell]

@dougwilson ... Yeah, you're absolutely correct about the concern there, and that's why I've gone back and forth. For the QUIC autoBlock idea, an IP would only be added if it has demonstrated definitively bad behavior -- such as repeatedly ignoring retry and stateless reset frames. QUIC does include path validation to detect address spoofing but that's not a mechanism we can fully rely on at this level. So you're absolutely right that it's a risk. Perhaps the compromise here is to allow the low level (C++) api to have the ability to remove individually added IP addresses and for QUIC autoBlock to be time based... More of a penalty box for a limited period of time?

[MylesBorins]

This does not land cleanly on v14.x, @jasnell would you be able to backport?

[jimmywarting]

Hi, i just discovered this. would it be possible to add a ip range using something like
blockList.addRange('192.168.0.0/16') where the 2nd end argument is optional? or can you do it with addAddress? it only says you can add a address that is IPv4 or IPv6 not a range which i guess addRange is meant for

[targos]

Lands cleanly on v14.x if I pull 6d1f0ae first 🎉