Umbress

Umbress is a fast and easy-to-use DDoS protection and mitigation Express.js middleware. It has several techniques of detection and mitigation like crawlers authenticity checks, malicious IP addresses access mitigation (based on AbuseIPDB data), advanced client-side JavaScript challenging, GeoIP manager, etc.

Features

• Recaptcha
• Rate-limiter
• GeoIP manager
• Malicious IP checker
• Crawlers authenticity checker
• Whitelists and blacklists for single IPs or subnets
• Client-side JavaScript-challenging (like CloudFlare's UAM)

Requirements

• Node.js 10+
• Express 4+
• Redis 4+

Benchmarks

Since this software is designed to work in highly loaded systems, it should provide high availability and not affect the overall performance of the application in which it works. Mitigating threats and protecting your application from DDoS attacks requires some amount of computing resources, which this software may take from your application in order to defend it. The following table provides information about how much ExpressJS-based application performance can degrade with various modules enabled. Benchmark ran on i5-8250U, 8GB RAM and NVMe drive. Numbers provided below are the avarage values calculated from 10 independent iterations. Each iteration ran using Apache Bench using the next command:

ab -n 10000 -c 200 'http://localhost:3000/{endpoint}'

*	Requests	Time per request	Performance degradation
Blank Express App	6328.68 req/s	31.46ms	-
Ratelimiter	4627.07 req/s	43.97ms	26.89%
Automated Checks	3468.94 req/s	59.37ms	45.19%
Recaptcha	3540.40 req/s	57.60ms	44.06%

Roughly speaking, performance degradation percentages are the price you are paying to mitigate and protect you from DDoS attacks.

_{Note that this results may vary depending on your OS, CPU, RAM, etc.}

Install

$ npm install umbress --save

Usage

❗ Important: Umbress relies on another middleware in some combinations of configuration so when you set advancedClientChallenging.enabled = true, recaptcha.enabled = true, checkSuspiciousAddresses.action = 'check' | 'recaptcha', geoipRule.action = 'check' | 'recaptcha' and geoipRule.otherwise = 'check' | 'recaptcha' it is mandatory to add the next lines of code before using Umbress:

// ExpressJS above 4.16.0
app.use(express.urlencoded({ extended: true }))

// ExpressJS below 4.16.0
import bodyParser from 'body-parser'
app.use(bodyParser.urlencoded({ extended: false }))

Case #1: Simple rate-limiter

Recommended to use only if you have no choice but to expose ExpressJS application without proxying all the traffic through Nginx, i.e.

import express from 'express'
import umbress from 'umbress'

const app = express()

app.use(
  umbress({
    rateLimiter: {
      enabled: true
    }
  })
)

Default policy is no more than 60 requests per minute; 30 seconds ban otherwise, but can be configured in any other way. Ratelimiter is semantic-friendly - it will throw 429 Too Many Requests and provide visitor with Retry-After header.

Case #2: White and black lists

You can block access for some IP's (blacklist) or allow it to only specified ones (whitelist).

Note: whitelist and blacklist can't be used at the same time. If you enabled both then only whitelist will be applied and blacklist will be ignored.

import express from 'express'
import umbress from 'umbress'

const app = express()

app.use(
  umbress({
    whitelist: ['2a03:2880::/32', '12.34.65.0/24', '8.8.8.8']
  })
)

Case #3 Automated browser checking

Every user (except search engine's bots and crawlers) will be promted with automated client-side browser checks. This process is fully automatic and works just like CloudFlare's UAM. Visitors will be seeing pre-defined message, but you can easilly modify it by yourself.

Attention Nginx users! If your ExpressJS app is behind Nginx then additional configuration is mandatory in order for this part of module to work. Add next lines to your location directive:

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Hostname $host;

Now the code example:

import express from 'express'
import umbress from 'umbress'

const app = express()

app.use(express.urlencoded({ extended: true }))

app.use(
  umbress({
    advancedClientChallenging: {
      enabled: true,
      cookieTtl: 30
    }
  })
)

When users visiting your website for the first time, they will receive a unique cookie and will be seeing this page. 5 seconds is needed to perform some computational tasks that only JavaScript-enabled visitors can solve. After 4-5 seconds the visitor will be redirected to the page by POSTing to it and receive the second cookie. Then visitor will be redirected to the requested URL immediatelly. Cookies TTL is 30 days, after it's expiration visitor will have to complete this challenge again.

Case #4: Most complex and secure way

To proceed with this configuration you need to sign up for AbuseIPDB

Umbress is tied up with AbuseIPDB database of IP addresses. When someone is hitting your website for the first time, Umbress will send a request to AbuseIPDB to check if IP address is malicious and being an origin of bad traffic. If so, the bad IP will be banned for a user-specified time. By default it is 3600 seconds or 1 hour. But if you enabled automated checking before then it's possible not to block user undoubtedly but ask him to pass an automated check to ensure he is using a real browser (this is the recommended way since IPv4 addresses are exhausting and many users are getting their access to the web through the NAT and bad neighbour activity can result in getting everyone in certain NAT blocked which is not what you probably want)

import express from 'express'
import umbress from 'umbress'

const app = express()

app.use(express.urlencoded({ extended: true }))

app.use(
  umbress({
    checkSuspiciousAddresses: {
      enabled: true,
      token: process.env.ABUSEIPDB_TOKEN,
      action: 'check',
      cookieTtl: 1
    }
  })
)

Case #5: Under heavy JS-based attack

When someone wants your web application to go down really bad, they might use headless browsers to solve the client-side task, receive the cookies and use them to bypass automated checking. Under such circumstances you have no choice but to apply geographically-based blocking. For example, your website works in CIS area, but mostly attack originated from China:

import express from 'express'
import umbress from 'umbress'

const app = express()

app.use(
  umbress({
    geoipRule: {
      type: 'whitelist',
      codes: ['RU', 'UA', 'BY', 'KZ'],
      action: 'pass',
      otherwise: 'block'
    }
  })
)

Blacklisting is available as well:

import express from 'express'
import umbress from 'umbress'

const app = express()

app.use(
  umbress({
    geoipRule: {
      type: 'blacklist',
      codes: ['CN'],
      action: 'block',
      otherwise: 'pass'
    }
  })
)

License

Copyright 2020 JamesJGoodwin. Licensed MIT.