Overview

pixl-acl is a simple Access Control List (ACL) system for quickly matching IP addresses against a set of IP ranges. It is built upon the ipaddr.js module (the only dependency, also MIT licensed). IPv4 and IPv6 addresses and ranges are both supported, including single IPs, partial IPs, and CIDR blocks. This is a perfect library for implementing an IP whitelist or blacklist.

Usage

Use npm to install the module:

npm install pixl-acl

Then use require() to load it in your code:

const ACL = require('pixl-acl');

To use the module, instantiate an object, and specify one or more IPv4 or IPv6 addresses or ranges (you can mix/match the two):

let acl = new ACL( "10.0.0.0/8" );
let acl = new ACL([ "10.11.12.13", "fd00::/8" ]);

You can optionally add addresses or ranges after construction using add():

acl.add( "172.16.0.0/12" );
acl.add([ "127.0.0.1", "::1" ]);

Partial IP addresses are also accepted, in which case the CIDR bits are guessed:

acl.add( "10." );        // expands to: 10.0.0.0/8
acl.add( "192.168" );    // expands to: 192.168.0.0/16
acl.add( "2001:db8::" ); // expands to: 2001:db8:0:0:0:0:0:0/32
acl.add( "::1" );        // expands to: 0:0:0:0:0:0:0:1/128

Limited IP ranges are also accepted. Make sure they are separated by a dash (with zero or more spaces), and that they can be represented accurately with one single CIDR block:

acl.add( "8.12.144.0 - 8.12.144.255" );
acl.add( "2600:1f70:4000:300:0:0:0:0 - 2600:1f70:4000:3ff:ffff:ffff:ffff:ffff" );

Complex ranges that require multiple CIDR blocks are not supported.

Matching IP Addresses

To match a single IP address against your ACL, call the check() method:

if (acl.check("10.20.30.40")) {
	// IP is within one of our ranges
}

To match multiple IP addresses at once, presumably from a proxy chain, call either checkAll() (for a whitelist) or checkAny() (for a blacklist). For example, to see if all IPs match a whitelist use checkAll() like this:

if (acl.checkAll([ "1.2.3.4", "192.168.1.2", "::1" ])) {
	// all 3 IPs are in the ACL, allow request through
}

Or alternatively, to see if any IPs are in a blacklist use checkAny() like this:

if (acl.checkAny([ "5.6.7.8", "2001:0db8:85a3:0000:0000:8a2e:0370:7334" ])) {
	// One or more IPs are blacklisted, reject request!
}

You can pass IPv4 and/or IPv6 addresses to all methods, including a mix of the two.

Private Addresses

To create an ACL consisting of all the IPv4 and IPv6 private address ranges, including the localhost loopback addresses (both IPv4 and IPv6 versions), and link-local addresses (both IPv4 and IPv6 versions) you can use the following set of CIDR blocks:

let acl = new ACL([ "::1/128", "127.0.0.1/32", "169.254.0.0/16", "fe80::/10", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fd00::/8" ]);

Handling Proxy Chains

When receiving incoming HTTP requests for a web application, you should consider all the IP addresses in the request, including those added to various headers by proxies and/or load balancers. It is recommended that you scan the following request headers and compile a list of all IPs, including the socket IP address itself.

| Header | Syntax | Description | |--------|--------|-------------| | X-Forwarded-For | Comma-Separated | The de-facto standard header for identifying the originating IP address of a client connecting through an HTTP proxy or load balancer. See X-Forwarded-For. | | Forwarded-For | Comma-Separated | Alias for X-Forwarded-For. | | Forwarded | Custom | New standard header as defined in RFC 7239, with custom syntax. See Forwarded. | X-Forwarded | Custom | Alias for Forwarded. | | X-Client-IP | Single | Non-standard, used by Heroku, etc. | | CF-Connecting-IP | Single | Non-standard, used by CloudFlare. | | True-Client-IP | Single | Non-standard, used by Akamai, CloudFlare, etc. | | X-Real-IP | Single | Non-standard, used by Nginx, FCGI, etc. | | X-Cluster-Client-IP | Single | Non-standard, used by Rackspace, Riverbed, etc. |

License

The MIT License (MIT)

Copyright (c) 2018 - 2023 Joseph Huckaby.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.