Node.js SDK for user monitoring


Sqreen protects your application users against major threats. These include account takeover, password bruteforce, suspicious activities coming from TOR or an unusual VPN.

Sqreen supports passport-local and passport-http authentication for automatic user context. If you use passport and select automatic mode in your application settings, you don't need to make any further changes.

Advanced User Context allows you to set up user monitoring in your application with flexibility and powerful additional features. To access this, integrate the Sqreen SDK in your application.

User monitoring SDK

The Sqreen SDK integration relies on three methods: signup_track, auth_track and identify.

Here is a full implementation example:

const Sqreen = require('sqreen');

const create_user = function(username, password, callback) {
    CreateUser(username, password, function (user) {
        Sqreen.signup_track({ username: user.username });
        return callback(user);
    });
}

const auth_user = function (username, password, callback) {
    AuthenticateUser(username, password, function (loginSuccess, user) {
        Sqreen.auth_track(loginSuccess, { username: user.username });
        return callback(loginSuccess, user);
    });
}

app.use((req, res, next) => {
    Session.login(req, (user) => {
        Sqreen.identify(req, { username: user.username });
        next();
    });
})

Login tracking

Sqreen.auth_track is the SDK method to call on user login activity.

const Sqreen = require('sqreen');

Sqreen.auth_track(success, user_identifiers);

The auth_track function accepts two positional arguments:

auth_track(success, user_identifiers);
  1. The first argument is a boolean indicating if the login attempt was successful or not.

  2. The second argument is an object with your user identification information. Sqreen's interface uses it to help you identify which users are at risk, or which are attacking your application. The hash keys and values must be strings.

Sqreen integration at signup and login

You should not call Sqreen.auth_track every time you check a user session in your application.

Signup tracking

Sqreen.signup_track is the SDK method to call when creating a new user account.

const Sqreen = require('sqreen');

Sqreen.signup_track(user_identifiers);

The signup_track function accepts a single argument:

signup_track(user_identifiers):

user_identifiers is an object representing your identification information. Sqreen's interface uses it to help you identify which users are at risk, or which are attacking your application. The hash keys and values must be strings.

Session tracking

Sqreen.identify is the SDK method to map a user to the current HTTP request.

Block users with security automation

You must implement the identify method to block users with Security Automation

When the request is not identified using this method, Sqreen falls back to login tracking information to map a user. It's a best effort approach based on the recent activity of users on the request's IPs.

The identify function accepts three positional arguments:

identify(req, user_identifiers, traits)
  1. The first argument is the current HTTP request object (see Node.js documentation on the http.IncomingMessage class).

  2. The second argument is an object, representing your user identification information. Sqreen's interface uses it to help you identify which users are at risk, or which are attacking your application.

  3. The third argument is an optional object of traits about the user. The hash keys and values must be strings.

User traits

At the moment, we don't display or process the traits. In a future release, we'll display them to help attack investigations and allow you to build custom workflows. Interested in this feature? Contact us.

Block users (security automation)

When using the Security Automation built-in "block user" security response, you must implement the identify and auth_track methods to block users at login or during their session. Otherwise, Sqreen is not able to map a user context to requests performed on your application.

After calling these methods, you need to call the userIsBanned(req) method to make Sqreen block the authenticated suspicious user.

If Sqreen blocks the current identified user, this method will return true and will close the current HTTP request.

const Sqreen = require('sqreen');

// ...
// in a controller:
Sqreen.identify({ username: req.username });
if (Sqreen.userIsBanned(req)) {
    return; // nothing happens anymore and `next` is not called
}
// ... more code

Learn more about login and session tracking.

User identification

For users with a single identification value, such as an email address or nickname:

Sqreen.auth_track(true, { email: user.email });
// Or, if the autentication failed
Sqreen.auth_track(false, { email: user.email });

User monitoring and PII

Avoid sending sensitive data and PII (personally identifying information) to us. Visit this blogpost to learn some best practices around user tracking.

For users with a composite primary key (more than one value), send all the values to identify the user accurately in Sqreen's user interface.

For example, if you are are operating a whitelabel platform and it identifies your users by their email and the shop ID, you can send these identifiers like this:

Sqreen.auth_track(true, { email: user.email, platform_id: user.platform_id });

This also applies to the signup_track and identify functions.

Please note that the three calls rely on the same identity format in order for Sqreen to map the activities to a single user.

The Sqreen SDK only accepts user identifiers

Do not send any other information (like the auth failure reason). Sqreen will consider them as part of the user identifier, and will not be able to merge successful and failed authentications.

Primary key

Sqreen tries to determine a primary key amongst the keys you provided. Sqreen uses the following keywords to determine the user's primary identification key: email, mail, e-mail, username, login.

If Sqreen cannot find any of those keys, it uses the first key in alphabetical order.

If Sqreen finds more than one key, it uses the first in the sequence mentioned above.

Usage with Express

When using Express, you can use the methods in the Sqreen SDK through dedicated middleware:

const Sqreen = require('sqreen');

// Register the Sqreen Express middleware in the app
app.use(Sqreen.middleware)

Then in any middleware, the req object exposes the following methods under the sqreen key:

  • req.sqreen.identify(user_identifiers, traits)

  • req.sqreen.userIsBanned()

  • req.sqreen.signup_track(user_identifiers)

  • req.sqreen.auth_track(success, user_identifiers)

  • req.sqreen.track(event_name, [options])