Track custom events

This guide will guide you into tracking custom events using the Sqreen SDK and eventually automate security scenarios. Visit the security automation section to learn more.

Events are stored locally in a queue until the next heartbeat. Every minute, events tracked are flushed to our servers. When your app exits, events are flushed.

To complete this guide, you should have installed our library in your application. Follow the installation steps described here.

Tracking events

The track SDK method is used to record your custom events.

Recording an event is as simple as naming it:

const Sqreen = require('sqreen');
Sqreen.track(event.name)

Of course, this is a basic version and our SDK supports additional optional parameters, such as properties:

const Sqreen = require('sqreen');
Sqreen.track(event.name, {properties: {foo: 'bar'}})

Later on, when creating automation playbooks using this event, you'll be able to use those dimensions to group events and apply conditions and detections.

Default dimensions

Out of the box, Sqreen library collects some dimensions based on the HTTP request:

  • Client IP.
  • User agent.
  • Path requested.
  • Request HTTP verb.
  • HTTP parameters.

By default all of these dimensions are scrubbed from sensitive data. See PII scrubbing

Track method definition

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

  • event_name is a string. This is the name of the event you're tracking.
  • options enables you to provide additional parameters. This is an object with the following fields:
    • properties: an object with arbitrary parameters to record custom event dimensions. This parameter is optional. You can provide up to 16 properties per event.
    • user_identifiers: user account who performed the event. This should be the same object provided to Sqreen.identify, Sqreen.auth_track or Sqreen.signup_track method when used. This parameter is optional.
    • timestamp: a Date object if you want to manually set the event’s timestamp. By default, the current server time will be used. This parameter is optional

User tracking

When the event tracked must be associated with a user account, you can decide to either pass it to every track call or rely on the identify method to set it in the context of the current HTTP request.

When Sqreen.track is provided with a user_identifiers value, the identify value will be overridden for the context of this event.

Block users

Implementing identify method is required to block users.

Integration with Express

Sqreen provides a middleware to simplify the integration with Express. Here's a sample code:

const Sqreen = require(‘sqreen’);

// Register the Sqreen Express middleware in the app
app.use(Sqreen.middleware)

app.get('/path/:parameter', (req, res, next) => {
    req.sqreen.track(‘foobar’, { 
        properties: {
            prop1: 'value1',
            prop2: 'value2'
        }
    });
    // rest of the code goes here
});

Monitor events

Congrats! You've setup the Sqreen SDK successfully and tracked your first custom events.

Now, go to your dashboard and visit the Event Explorer in order to validate that events are properly recorded by Sqreen.

Next, depending on your traffic and the frequency of the tracked event, you may want to wait few hours or days in order to collect enough events to craft a security automation playbook leveraging your custom event.

event explorer

Create a security automation playbook

Once you're ready to automate security responses based on a custom event activity, go to your dashboard and visit the Automation Plugins section to start building an automation plugin.

Track events from the past

When getting started on Sqreen, it can be handy to import past events in order to start with an existing dataset and automate scenarios right away.

The options object accepts an optional parameter timestamp, expecting a date object. Setting this parameter will override 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
})

Error handling

Things can some time go wrong, for various reasons. This section features the most frequent issues when using our SDK.

Events recording

In case the Sqreen agent doesn't manage to flush events collected in the past minute to our servers, it'll keep retrying. After sometimes, the events will be dropped to prevent Sqreen memory overhead to grow and impact your application's performance.