cheq-express-middlewares

CHEQ middlewares for Express.Js

Features

• Installation
• Real time interception
  • Required configuration
    • API key
    • Tag hash
    • API endpoint
  • Optional configuration
    • Mode
    • Threat type codes
    • Redirect URL
    • Callback function
    • Ja3
    • Resource type
    • IP header
    • URI Exclusion
    • Timeout
    • Custom event name
  • Usage example

Installation

$ npm install @cheq.ai/cheq-middlewares

Real time interception

Real-Time Interception (RTI) supports API calls to provide detection of invalid traffic (IVT) to your site, in absolute real-time. RTI will intercept IVT to prevent invalid visitors from harming your conversion efforts.

Configuration

Required configuration

API key

Available on the Paradome platform under “Management -> RTI”

const options = {
    ...
    apiKey: '11abc111-aa11-11aa-1111-11a11a11111'
    ...
}

Tag hash

Appears in your CHEQ tag.

const options = {
    ...
    tagHash: 'c99651e7936e27743ce51c728492aac9'
    ...
}

API endpoint

The nearest API endpoint to your server. Must be the same region as your tag domain.Select the appropriate endpoint:

• US: https://rti-us-east-1.cheqzone.com
• EU: https://rti-eu-west-1.cheqzone.com

const options = {
    ...
    apiEndpoint: 'https://rti-eu-west1.cheqzone.com'
    ...
}

Optional configuration

Mode

• monitoring - Will not perform any action

• blocking - Will block Invalid traffic or redirect them to a different url (defind in Redirect URL).

The default value will be monitoring.

const options = {
    ...
    mode: 'monitoring'
    ...
}

sessionSyncMode

Server (RTI) and Client (cheq-tag) are able to recognize the same session visit to the website by either of these 3 methods:

• banRti - Will construct the rti-request with USER_AGENT field (IP is mandatory so it is included on all 3 methods).

• rtiCookie - Will construct the rti-request with CHEQ_COOKIE (rti cookie) field. This is fetched from the site visit former RTI request.

• requestId - Will construct the rti-request with REQUEST_ID field. This is fetched from the response of the client cheq-tag.

• none - Will construct the rti-request with all above fields.

The default value will be none.

const options = {
    ...
    sessionSyncMode: 'none'
    ...
}

Threat type codes

Threat types are devided to two groups:

1. Block/Redirect - traffic detected as threat types in this group would be blocked or redirected to a different page (defind in Redirect URL. Default threat type codes for this group: 2,3,6,7,10,11,16,18.

2. Captcha - threat type codes in this group would be reffered to Callback function. Default threat type codes for this group: 4,5,13,14,15,17. Threat type must be unique for each list.

const options = {
  ...
    threatTypesCodes: {
        blockRedirect: [2, 3, 6, 7, 10, 11, 16, 18],
        captcha: [4, 5, 13, 14, 15, 17]
    }
  ...
};

Redirect URL

A URL you would like to redirect invalid users to.

If it is empty the response will be status code 403 and the user will be blocked.

const options = {
    ...
     redirectUrl: 'https://invalid-user.com'
    ...
}

Callback function

A custom callback option, for instance to redirect to captcha page. If it is empty, will use express next function.

const options = {
    ...
     callback: function(req, res, next) {
        //do somthing or call next()
        }
    ...
}

Ja3

Recommended - A function that extracts ja3 fingerprint from the request. SSL/TLS client fingerprints

const options = {
    ...
     getJa3: function getJa3(req) {
        return req.query.ja3
     }
    ...
}

Resource type

A function to get the response content-type header.

This is recommended to improve detection.

const options = {
  ...
  getResourceType: function(req) {
    if(req.method === 'POST') {
        return 'application/json';
    } else if(req.url === '/') {
        return 'text/html';
    }
   
  }
  ...
};

IP header

Specify a trusted IP header to be used as client IP

const options = {
  ...
  trustedIPHeader: 'client-ip'
  ...
};

URI Exclusion

An array of regular expressions or path that will be excluded

const options = {
  ...
  URIExclusion: ['/about', '/careers']
  ...
};

Timeout

Optional timeout in milliseconds, if absent value will be set to 100 milliseconds.

const options = {
    ...
     timeout: 1000 // one second
    ...
}

Custom event name

In case a custom event name is used, this function extracts the name of the custom event.

const options = {
    ...
     getChannel: function getChannel(req) {
        return req.query.channel
     }
    ...
}

Usage example RTI

const express = require('express');
const app = express();
const PORT = process.env.PORT || 5000;
const { rti, eventsTypes } = require('@cheq.ai/cheq-express-middlewares');
const rtiOptions = {...};
const middleware = rti(rtiOptions);

app.get('/subscribe', middleware(eventsTypes.SUBSCRIBE), function (req, res) {
  res.send('Hello World');
})
app.get('/page_load', middleware(eventsTypes.PAGE_LOAD), function (req, res) {
  res.send('Hello World');
})

app.listen(PORT);

Usage example SLP

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;
const { slp, eventsTypes } = require('@cheq.ai/cheq-express-middlewares');
const slpOptions = {...};
const slpMiddleware = slp(slpOptions);

app.post('/form-submit', slpMiddleware(eventsTypes.FORM_SUBMISSION), (req, res) => {
  const slpRes = res.locals.slpRes

  res.json(slpRes);
});

app.listen(PORT);

const slpOptions = {
  apiKey: process.env.API_KEY,
  tagHash: process.env.TAG_HASH,
  apiEndpoint: SERVICE_ENDPOINT,
  mode: "fast",
  timeout: null,
};