Python SDK for user monitoring


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

Sqreen supports Django User authentication out of the box for automatic user context. If you use Django and select the automatic mode in your application settings, you do not need to make any further changes.

Advanced User Context allows you to set up user monitoring in your application with flexibility and powerful extra features. You need to integrate 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:

import sqreen

def signup(username):
    user = create_user(username)
    sqreen.signup_track(username=username)
    return user

def login(username, password):
    user = check_password(username, password)
    if user is not None:
        sqreen.auth_track(True, username=username)
    else:
        sqreen.auth_track(False, username=username)
    return user

@app.route('/balance')
@auth.login_required
def balance():
    sqreen.identify({'username': auth.username()})
    return "Your balance is %s" % db.balance(auth.username())

Signup tracking

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

import sqreen
sqreen.signup_track(username=username)

The signup_track function accepts a single argument:

def signup_track(**user_identifiers):

user_identifiers is a dict representing your identification information. Sqreen's user 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.

Login tracking

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

import sqreen
sqreen.auth_track(is_login_successful, username=username)

The auth_track function accepts two positional arguments:

def 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. The second argument is a {LANGUAGE_TYPE} with your user identification information. Sqreen's user 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 each time you check a user session in your application.

Session tracking

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

{!sdk/block-user-requires-identify-warning.md!}

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 two arguments:

import sqreen
sqreen.identify({'username': username}, {'nickname': nickname})

The identify function accepts two positional arguments:

def identify(user_identifiers, traits)
  1. The first argument is a dict representing the identification information. Sqreen's user interface uses it to help you identify which users are attacking your application. The hash keys and values must be strings.

  2. The second argument is an optional dict of traits about the user. The hash keys and values must be strings.

User traits

At the moment, we do not display nor process the traits. In a future release, we'll display them to help attack investigation 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 identify and auth_track methods to block users at login or during their session. Otherwise, Sqreen will not be able to map a user context to requests performed on your application.

Learn more about login and session tracking.

User identification

If your program identifies users with a single value (email, nickname...), you can proceed that way:

# When the user signs up
sqreen.signup_track(username=user.email)

# When the user login
sqreen.auth_track(True, username=user.email)

# In the context of an HTTP request
sqreen.identify({'username': user.email})

The 3 calls rely on the same identity format for Sqreen to map the activities to a single user.

User monitoring and PII

To learn more about sending sensitive data to us without leaking any Personally Identifying Information (PII), visit this blogpost to learn some best practices around user tracking.

If your program identifies users with a composite primary key (more than one value), send all the values to identify them accurately on 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, username=user.email, platform_id=platform.id)

This also applies to the signup_track and identify functions.

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 primary identification key: email, mail, e-mail, username, login.

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

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