Node.js SDK for user monitoring


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

Sqreen supports passport-local and passport-http authentication, out of the box, to automatically track user activities. If you're using passport with those strategies, you don't need to change anything, granted you've selected the automatic mode in your application settings.

Advanced User Context allows you to set up user monitoring in your application with flexibility and powerful additional features. You will need to integrate Sqreen SDK in your application (< 10 minutes).

User monitoring SDK

The Sqreen SDK integration is very simple. It relies on 3 methods: signup_track, auth_track and identify.

Here's 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 (True or False).

  2. Then, the second argument is an object, representing your user identification informations. They will be used on Sqreen's user interface to help you identify which users are at risk, or which are attacking your application.

Sqreen integration at signup and login

You should not call Sqreen.auth_track each 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, basically at signup.

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 user identification informations. They will be used on Sqreen's user interface to help you identify which users are at risk, or which are attacking your application.

Session tracking

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

Block users with security automation

Implementing identify method is required to block users thanks to Security Automation

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

The identify function accepts three positional arguments:

identify(req, user_identifiers, traits)

  1. The first argument is the current HTTP request object (see https://nodejs.org/dist/latest-v8.x/docs/api/http.html#http_class_http_incomingmessage).

  2. The second argument is an object, representing your user identification information. They will be used on Sqreen's user interface 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 should only be strings.

User traits

At the moment, we do not display nor process the traits. In the near future, we'll display them to faciliate attack investigation and allow you to build custom workflows. Interested in this feature? Contact us.

Block users (Security Automation)

When using Security Automation built-in block user security response, you should implement identify and auth_track methods to block users at login or during their session. Otherwise, Sqreen won't be able to map a user context to requests performed on your application.

After calling these methods, you will need to call userIsBanned(req) method to make Sqreen block to block the authenticated suspicious user detected: If the current identified user is blocked, this method will return true and will close the current HTTP request. Hence no more operations should be made on 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 happens

Learn more about login and session tracking.

User identification

If your users can be identified with a single value (email, nickname...), you can send proceed that way:

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

User monitoring and PII

If you're concerned about sending sensitive data to us and not leaking any Personally Identifying Information (PII), visit this blogpost to learn some best practices around user tracking (Ruby but easy to translate in Node.js).

If your users are identified with a composite primary key (multiple values), all of them should be sent in order to identify them accurately on Sqreen's user interface.

For example, if you are are operating a whitelabel platform and your users are identified 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 apply to the signup_track and identify functions.

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

Sqreen SDK only accepts user identifiers

Don't 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 will try to determine a primary key amongst the keys you provided. The following keywords will be used to determine the user primary identification key: email, mail, e-mail, username, login.

If none of those key are found, we will use the first in alphabetic order.

If multiple keys are found, we'll use the first in the sequence mentioned above.

Usage with Express

When using Express, all the methods in the Sqreen SDK can be used through a dedicated middleware:

const Sqreen = require('sqreen');

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

Then in any following middleware, the following methods will be exposed on the req object 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])