Go SDK for user monitoring

Sqreen monitors user behavior for signs of Account Takeover (ATO) and targeted attacks. To do so, the microagent uses advanced, integrated functionality in the form of an SDK.

Automatic: (Not available) The Sqreen Microagent does not establish user context automatically on Go applications.

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.

Read more about the Go SDK in Github.

Install and integrate the SDK

  1. From the Sqreen Dashboard, access Settings > Global and scroll to User monitoring.
  2. Change the mode from "Off" to "Advanced".
  3. Add user-monitoring events to your application as described below.

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.

TrackSignup

TrackSignup() is the SDK method to call when creating a new user account.

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackSignup()

TrackAuth

TrackAuth(), TrackAuthSuccess() and TrackAuthFailure() is the SDK method to call when a user logs in to your app, and whether the login was successful or failed.

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackAuthSuccess()

Do not call too much

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

Identify

Identify() is the SDK method to use to associate a user to the current HTTP request. This method does not create a user event. It returns a non-nil error when the identified user was blocked by Sqreen. Thus, the caller should immediately return from the function.

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
if err := sqUser.Identify(); err != nil {
  // This user has been blocked and the HTTP request has been aborted.
  // You can cimply stop further serving the request by returning.
  return err
}

Consistently identify users

In all the methods, a user must be uniquely identified by:

  • a single identification value, such as a unique user id.
  • or a composite value, such as a user id and platform id (meaning that the user id in unique in this platform id).

All the methods must be given the same unique user identity so that Sqreen can properly map activities to a single user. Extra information should not be added to the user identifier values so that Sqreen can correctly associate user activities to a single user.

Composite primary key example:

uid := sdk.EventUserIdentifiersMap{
    "user_id": user.ID,
    "platform_id": user.PlatformID,
}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackSignup()

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.

Blocking 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 above so that Sqreen can map a user identifier to the request.

Example:

func handler(w http.ResponseWriter, r *http.Request) {
    // Get the request record.
    sqreen := sdk.FromContext(r.Context())

    // Example of globally identifying a user and checking if the request
    // should be aborted.
    uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
    sqUser := sqreen.ForUser(uid)
    if err := sqUser.Identify(); err != nil {
        // Return to stop further handling the request.
        // At this point, the request was answered according to your blocking
        // settings and the request context has been canceled.
        return
    }
    // Not blocked.
    fmt.Fprintf(w, "OK")
}

We suggest to integrate the user monitoring in an user authentication middleware for your web framework so that you can easily deploy it to all your user-authenticated endpoints.

Example for net/http:

func MyUserMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Get the request record created by Sqreen's middleware function and
        // stored into the request context.
        sqreen := sdk.FromContext(ctx)

        // Example of globally identifying a user and checking if the request
        // should be aborted.
        uid := /* compute your user id based on the request headers or payload */
        sqUser := sqreen.ForUser(uid)
        if err := sqUser.Identify(); err != nil {
            return
        }
        // Not blocked, continue with next handler.
        next.ServeHTTP(w, r)
    }
}

// ...
// Build a handler by chaining middleware and making sure Sqreen's comes first.
handler := sqhttp.Middleware(sqhttp.Middleware(MyUserMiddleware(myHandler)))
// ...

Next steps