Track custom events

When you installed and integrated the SDK for user monitoring, you added three methods to the code of your app to begin tracking user activity:

  • signup_track to track user account creation
  • auth_track to track user logins
  • identify to track user sessions

Beyond those three, you can use the track SDK method to define and record custom events in your app. You can use these custom events to automate your app's response to threats in a Security Automation Playbook.

Define your custom event

Define a custom event in the sqreen.json file in your application. 

const Sqreen = require('sqreen');
Sqreen.track(event_name, [options])

The SDK supports optional parameters, such as properties. Later, when you use your custom event in a Security Automation Playbook, you can use these parameters to group events and apply conditions and detections.

event_name: This is the identifier of the event you wish to track. It is a string.

options: This is an object that enables you to define event parameters. It has the following fields:

  • properties: (optional) An object with arbitrary parameters to record custom event dimensions. Out of the box, the microagent collects several properties based on the HTTP request:

    • client IP address
    • user agent
    • path requested
    • request HTTP verb
    • HTTP parameters

  • user_identifiers: (optional) An object that represents a user's information. The identifier must be the same as the user_identifiers you used in the methods Sqreen.identify, auth_track or signup_track. Refer to "Consistently identify users" section of the SDK documentation for details. If your custom event includes user_identifiers, then the custom event parameter overrides the identify value for the context of the event.

  • timestamp: (optional) A date object that sets the event's timestamp. By default, this object uses the current server time.

  • collect_body: A boolean. If true, the SDK collects the value in req.body and links it to the event. By default, the track method does not collect the requests' HTTP body.

  • request: A request object that Sqreen automatically populates with the current request.

Use your custom event

  1. If you want to associate your custom event with a user account, you can either pass it to every track call, or rely on the identify method to set the custom event in the context of the current HTTP request.

  2. Navigate to your Sqreen Dashboard > Events Explorer to check that Sqreen is recording your custom event as expected. Depending on the traffic to your application and the custom event's frequency of occurrence, you may want to wait a few hours or days to collect enough data to be useful.

  3. When Sqreen has recorded a reasonable amount of events, navigate to the Sqreen Dashboard > Playbooks to start building an automation playbook. Refer to Security Automation Playbooks documentation for more details

Track events from the past

As you begin using your new custom event(s), it may be useful to import past events into Sqreen. This allows you start working with an existing dataset so you can examine output and begin to craft a Security Automation Playbook.

If your custom event includes the optional timestamp parameter, that parameter overrides the current server time

const Sqreen = require('sqreen');

const event_date = new Date(2018, 3, 15, 14, 42, 0)
Sqreen.track(event.name, {
    properties: {foo: 'bar'},
    timestamp: event_date
})

Next steps