Python 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 Django user authentication to automatically establish user context. If your Python app uses Django 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¶

From the Sqreen Dashboard, access Settings > Global and scroll to User monitoring.
Change the mode from Automatic (built-in) to Advanced (SDK).
Add three methods to the code of your application. First, add signup_track (see details):
```
import sqreen
sqreen.signup_track(username=username)
```

Add auth_track (see details):

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

Add identify (see details):

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

Here is a full implementation example:

import sqreen

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

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

@app.route('/balance')
@auth.login_required
def balance():
    sqreen.identify(dict(username=auth.user.name))
    return "Your balance is {}".format(db.balance(auth.user))

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data, Personally Identifying Information (PII), or Personal Health Information (PHI) 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 one or more named arguments:

def signup_track(**user_identifiers):

user_identifiers 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 dict'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 a positional argument and one or more named arguments:

def 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 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 dict's keys and values must be strings.

Do not call too much

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

identify¶

sqreen.identify is the SDK method to use to attach a user to the current HTTP request that Sqreen processed. The Sqreen microagent embedded in your app uses this method to provide user context. This user context is useful when you are reviewing malicious requests that Sqreen flagged. Note, this method does not attach a user to a request and send data to Sqreen for every request a user makes, just the requests that Sqreen flagged as malicious.

The identify function accepts two positional arguments:

def identify(user_identifiers, traits)

user_identifiers is a dict 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 dict's keys and values must be strings.

traits is an optional dict that represents traits about the user. The dict'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:

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

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

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

Composite primary key example:

sqreen.auth_track(True, username=user.name, platform_id=platform.id)

sqreen.identify({'username': user.name, 'platform_id': platform.id})

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data, Personally Identifying Information (PII), or Personal Health Information (PHI) 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.

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

Next steps¶

Learn how to create and track custom events in your application.
Set up a Security Automation Playbook to automate your app's response to threats.