@imaginarium/cerberum v0.7.0

Cerberum

Doorkeeper middleware with custom filters and DNSBL lookup.

for Imaginarium Project

WIP: master branch can be reset at any time and will be cleaned for version 1.0.0

Middleware

Installation

npm install --save @imaginarium/cerberum

ou

yarn add @imaginarium/cerberum

Usage

const cerberum = require('@imaginarium/cerberum')
const app = require('express')()

app.use(cerberum(req, res, next))

// …

Server

Cerberum can be used wish a central server who do perform filtering, dns lookup and store black/white lists. It's usefull in Docker Swarm when many services are using Cerberum as middleware.

remote option of the configuration file must be set at true or <hostname> on each server. It will fallback to inner middleware filters, lookup function and lists if the server is unreachable.

Build Docker Image

git clone master https://framagit.org/imaginarium/cerberum
cd cerberum
bash bin/autobuild

Configuration

Configurations options are stored in var/cerberum and share/cerberum directories in your project root dir. At first, files into share/cerberum have been intended to be shared between services (ex: via Volumes in a Docker Swarm) and files into var/cerberum aren't, but it's no more recommanded. Use the Server/Client method unstead.

Defaults files will be created if they don't exists.

dnsbl.json, jail.json and clearance.json are stored in share/cerberum so they can be shared between microservices, Cerberum will always reload them on each request.

config.json

Options and fiters are stored in var/cerberum/config.json in your project root dir.

Structure is not strictly defined and may evolve until v1.0.0

{
  "rejectndestroy": false,
  "rejectedCode": 429,
  "remote": false,
  "remoteCache": 15, // cache requests in minutes when using remote
  "durations": {
    "filters": 6, // default jail duration for filters
    "dnsbl": 168, // default jail duration for DNSBL
    "clearance": 24 // default clearance duration
  },
  "needHostname": Boolean,
  "noEmptyHostname": Boolean,
  "filters": {
    "url": {
      "<categorie>": {
        "active": Boolean,
        "duration": Number, // optional
        "rules": [
          {
            "regex": "^\/azenv.php",
            "active": Boolean,
            "duration": Number // optional
          },
          // …
        ]
      },
      // …
    },
    "agent": [
      {
        "regex": "proxyradar\\.com",
        "active": Boolean,
        "duration": Number
      },
      // …
    ]
  }
}

dnsbl.json

List of DNSBL to query are stored in share/cerberum/dnsbl.json at the root of your project. Each DNSBL are stored in an Object with 2 keys :

• dns : <url>
• codes : <Number>, …

Mainly, DNSBL return 127.0.0.2 when IP is listed on. Sometimes, you can use DNSBL who serve multiples lists on the same request and return different IP for each list. 127.0.0.x where x is a code. If an IP is listed with a code not set here, Cerberum will just return a warn in stdout.

jail.json & clearance.json

They are basicaly Array of Objects :

• ip : IP concerned by jail/clearance
• release : date of the end of jail/clearance
• description (optional) : short human readable description
• data (optional) : undocumented

GNU GPL 3.0

Cerberum Copyright (C) 2019 Clovis Gauzy

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.