Nifty Procrastination Machine

    This package has been deprecated

    Author message:

    Moved to @outofsync/express-ip-blacklist


    1.1.0 • Public • Published



    Version Downloads Build Status Codacy Badge Codacy Coverage Badge Dependencies

    express-ip-blacklist is a cache-based, IP blacklist for use with expressJS. It caches a store of IP addresses used to make bad requests and then temporarily blocks requests from those sources once a threshold of bad requests has been exceeded. In this way it is possible to limit access of bad actors to any system.

    By default, the blacklist uses 250 attempts in a refreshing, 60-minute window. This means that if 250 bad requests are made, then 59 minutes and 59 seconds elapse, and then a 251st bad request is made, that the expiration of the blacklist will start at the moment of the 251st bad request.

    If there are any unexpected errors during the cache retrieval process, then the black list process fails silently and the request is handled as normal.

    By default, any blacklisted ip will be sent an empty 403 response with HTTP Header Retry-After set to the number of seconds that must be waited.


    npm install @mediaxpost/express-ip-blacklist


    const IPBlacklist = require('@mediaxpost/express-ip-blacklist');
    ipBlacklist = new IPBlacklist('blacklist');
    // Later in expressJS
    // Later still in the 404 handler or any other controller

    API Reference

    constructor(cacheNamespace [, config] [, cache] [, log])

    Create a new IP Blacklist client with the passed cacheNamespace, config, cache, and log. A cacheNamespace is required to scope the IP Blacklist from other values which may be in use within the cache.

    checkBlacklist(req, res, next)

    An express handler to check the current request against the blacklist and which should be attached early in the Express stack.


    increment(req, res [, next])

    Increments the current cache using the lookups and IP. This should be called whenever a "bad request" is handled with code.

    It may be called inline with an HTTPRequest and HTTPResponse parameter. For example:

      handleBlacklist(req, res, next) {
        ipBlacklist.increment(req, res);

    Or, it may be used directly as an Express handler:



    Configuration Object

    The configuration parameter expects and object that contains the following (with defaults provided below):

      lookup: [],
      count: 250, // 250 request
      expire: 3600000 // every 60 minute window (in mSec)
      whitelist: () => {
        return false;
      onBlacklist: null,
      noip: false
    parameter type description
    lookup Function(req) ⟾ Array or Array A function which accepts a HTTPRequest parameter and returns an array, or an array. The array is used to provide additional scoping criteria to the blacklist. For example, if you wanted Blacklist based on an API Key and IP Address pair, you would create a function that return an array with the API Key from the request object. The IP Address is always included in the scope criteria unless noip is set to true.
    count Integer The number of bad request attempts allowed by the IP (and lookup criteria) before blacklisting occurs.
    expire Integer Number of milliseconds for the refreshing blacklist time period. When an additional attempt is made during the blacklist period, the timer is reset and client must wait the entire duration again.
    whitelist Function(req) ⟾ Boolean or Array A function which accepts a HTTPRequest parameter and returns a boolean value or an Array of IP Addresses. When a function is set, it should return a boolean value to indicate whether the request is whitelisted. When an array is set, then the current IP address of the request is compared against all values in the array and is whitelisted if the array includes the current IP. Note: The x-forwarded-for Header is used instead of the physical IP address when it is included in the request.
    onBlacklist Function(req, res, next) or null A function accepting a HTTPRequest, a HTTPResponse, and a closure(next) parameter. When a request test true for being blacklisted, then this function is called blacklisting occurs. If the function is unset, then the IP Blacklist sends an HTTPResponse with a 403 Status Code, an empty body, and the Retry-After HTTP Header with the number of seconds that the client must wait before trying again.
    noip Boolean Indicates that the IP Address from the HTTP Request should not be automatically added to the lookup scope. Without additional lookup criteria, this will cause all bad requests to check against the blacklist.

    Cache Object

    The Cache object can be a active and promisified Redis connect, or an active Memory Cache connection, or an active Object Key Cache. If no value is set, then IP Blacklist will create an internal Object Key Cache and use it.

    Logging Object

    The Logging object is an instance of any logging library, such as Winston or Bunyan, which support the .error(...), .info(...), .debug(...), and .log(...) methods. If this is not provided, then any debug or error messages are sent to /dev/null through the use of LogStub.


    npm i @mediaxpost/express-ip-blacklist

    DownloadsWeekly Downloads






    Unpacked Size

    26.6 kB

    Total Files


    Last publish


    • chronosis