Track custom events

This guide will help you track 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.

The Go documentation corresponding to the following documentation can be found at https://godoc.org/github.com/sqreen/go-agent/sdk.

Installation

The Go agent currently does not automatically detect your web framework. You are therefore required to install the middleware functions for the web framework you use to be able to use the SDK methods described below.

Tracking events

Method TrackEvent() allows to record a custom security-related event. It is as simple as:

sqreen := sdk.FromContext(ctx)
sqreen.TrackEvent("my.event")

Optional parameters can be provided to the event, such as properties:

props := sdk.EventPropertyMap{"key": "value"}
sqreen := sdk.FromContext(ctx)
sqreen.TrackEvent("my.event").WithProperties(props)

Later on, when creating automation playbooks using this event, you will be able to use those additional parameters to group events and apply conditions and detections.

Default properties

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

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

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

Method definition

The TrackEvent() method is defined as:

func (ctx *HTTPRequestRecord) TrackEvent(event string) *HTTPRequestEvent

It creates a new event, named event, whose additional options can be set using the returned value's methods, such as WithProperties() or WithTimestamp().

Event options allows you to provide additional parameters:

func (e *HTTPRequestEvent) WithProperties(p EventPropertyMap) *HTTPRequestEvent
func (e *HTTPRequestEvent) WithTimestamp(t time.Time) *HTTPRequestEvent
func (e *HTTPRequestEvent) WithUserIdentifiers(id EventUserIdentifiersMap) *HTTPRequestEvent

  • WithProperties(): allows to pass an object with arbitrary parameters to record custom event dimensions.

  • WithUserIdentifiers(): allows to identify the user account which performed the event. This should be the same object provided to ForUser() method when used.

  • WithTimestamp(): allows to pass a time if you want to manually set the event’s timestamp. By default, the current server time will be used.

User tracking

When the event tracked must be associated with a user account, you can decide to either pass it to every TrackEvent() using WithUserIdentifiers() or rely on the ForUser() method to globally set it to the following method calls.

When TrackEvent() is provided with user identifiers, the identify value is overridden for the context of this event.

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

Monitor events

Congratulations! You've set up the Sqreen SDK successfully and tracked your first custom events.

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

Next, depending on your traffic and the frequency of the tracked events, you may want to wait a few hours or days to collect enough events to craft a playbook.

event explorer

Create a security automation playbook

Once you are ready to automate a scenario, go to your dashboard and visit the [Playbooks section](https://my.sqreen.io/application/goto/security-automation/playbooks to start building an automation playbook.