Node.js SDK for user monitoring

Sqreen monitors user behavior for signs of Account Takeover (ATO) and targeted attacks. To do so, the microagent uses both automatic, built-in tools and advanced, integrated functionality.

Automatic: The Sqreen Microagent supports passport-local and passport-http authentication to automatically establish user context. If your Node.js app uses passport and you select Automatic mode in your application settings in the Sqreen Dashboard, you do not need to make any further changes to monitor user behavior.

Advanced: (Optional) Install and integrate the Sqreen SDK so that the microagent tracks user activity in your app beyond the built-in capabilities.

Learn more about User protection in general.

Install and integrate the SDK

  1. From the Sqreen Dashboard, access Settings > Global and scroll to User monitoring.
  2. Change the mode from Automatic (built-in) to Advanced (SDK).
  3. Add three methods to the code of your application. First, add signup_track (see details):
    const Sqreen = require('sqreen');
    
    Sqreen.signup_track(user_identifiers);
    
  4. Add auth_track (see details):
    const Sqreen = require('sqreen');
    
    Sqreen.auth_track(success, user_identifiers);
    
  5. Add identify (see details):
    app.use((req, res, next) => {
        Session.login(req, (user) => {
            Sqreen.identify(req, { username: user.username });
            next();
        });
    })
    

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();
    });
})

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data or Personally Identifying Information (PII) to the Sqreen Platform. Instead, use Universally Unique Identifiers (UUID) or hashes. Read this blog post to learn about best practices for user monitoring and PII.

signup_track

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

The signup_track function accepts a single argument:

signup_track(user_identifiers):

user_identifiers is a hash that represents a user's information. The Sqreen Dashboard uses it to help you identify which users are at risk, or which are attacking your application. The hash's keys and values must be strings.

auth_track

Sqreen.auth_track is the SDK method to call when a user logs in to your app.

The auth_track function accepts two positional arguments:

auth_track(success, user_identifiers);

success is a boolean indicating whether a user's login attempt was successful or not (true or false).

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

Do not call too much

Do not call Sqreen.auth_track every time you check a user session in your application. Use it track when a user logs in.

identify

Sqreen.identify is the SDK method to use to map a user to the current HTTP request. It tracks user sessions.

The identify function accepts three positional arguments:

identify(req, user_identifiers, traits)

req is the current HTTP request object (refer to Node.js documentation on the http.IncomingMessage class).

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

traits is an optional object that represents traits about the user. The hash's keys and values must be strings. Sqreen does not yet display or process traits, though there are plans to do so in the future.

If you do not configure Sqreen to identify the request using this method, Sqreen relies on login tracking data to map a user's activities. Using login tracking data is not as good as using identify as it is based only on the recent activity of users on the request's IP addresses.

Consistently identify users

In all three methods (signup_track, auth_track, identify), you can identify users by:

  • a single identification value, such as an email address or nickname
  • a composite primary key, such as an email address and platform id

All three methods must use the same identity format for Sqreen to map activities to a single user. Further, the Sqreen SDK only accepts user identifiers. Do not send any other information, such as the auth failure reason. Extra information prevents Sqreen from correctly mapping activities to a single user.

Single identification value example:

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

Composite primary key example:

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

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data or Personally Identifying Information (PII) to the Sqreen Platform. Instead, use Universally Unique Identifiers (UUID) or hashes. Read this blog post to learn about best practices for user monitoring and PII.

Block users

After you integrate the SDK for user monitoring in your app, you can extend Sqreen's protection capabilities even further to block suspicious users. To do so, use a Security Automation Playbook, a tool that enables you to customize and automate your app’s response to threats.

  1. When using a playbook's built-in "Block User" security response, you must implement the identify and auth_track methods as above. If you do not implement these methods, Sqreen cannot map a user context to requests they perform on your application.

  2. After implementing these methods, call the userIsBanned(req) method to make Sqreen block the authenticated suspicious user at login or during their session. When Sqreen blocks the current identified user, this method returns true and Sqreen closes the current HTTP request.

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

Use the SDK with Express

If you use Express, you can use the methods in the Sqreen SDK through dedicated middleware.

  1. Register the Sqreen Express middleware in the app.
    const Sqreen = require('sqreen');
    
    // Register the Sqreen Express middleware in the app
    app.use(Sqreen.middleware)
    
  2. Then in any middleware, use the req object to expose 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]) (this is a custom event)

Next steps