Ruby 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 Devise authentication to automatically establish user context. If your Ruby app uses Devise 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 your application. First, add signup_track (see details): 
    require 'sqreen'
Sqreen.signup_track(email: user.email)
  4. Add auth_track (see details): 
    require 'sqreen'
Sqreen.auth_track(is_login_successful, email: user.email)
  5. Add identify (see details): 
    require 'sqreen'
Sqreen.identify(email: current_user.email)

Here is a full implementation example:

require 'sqreen'

class SessionsController < ApplicationController
  def create
    user = login(params[:email], params[:password])
    Sqreen.auth_track(!user.nil?, email: params[:email])
    # ....
  end
end

class UsersController < ApplicationController
  def create
    user_params = params.require(:user)
    user = User.create!(user_params)
    Sqreen.signup_track(email: user_params[:email])
    # ....
  end
end

class ApplicationController
  before_action :tag_request

  private

  def tag_request
    if current_user
      Sqreen.identify(email: current_user.email)
    end
  end
end

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 a single argument:

def 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:

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 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 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 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 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)

Composite primary key example: 

Sqreen.auth_track(true, email: user.email, 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 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.

Next steps