To help you get started quickly with Tines, every tenant contains a small demo story, called 'Simple story', showing how actions and events interact to automate workflows.

Story Description

In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant. The alert will contain the type of alert (infection, DDOS, credential stuffing, etc.) and details on any users affected. If the alert is related to an infection, we will take a specific action based on the user’s job title.

How the Story Works

There are seven types of actions in Tines: Email Action, Event Transformation Action, HTTP Request Action, IMAP Action, Trigger Action, Webhook Action, and the Send to Story Action. Each action is designed to be used in specific situations. For example, the Email action can be used to send emails to one or more recipients. The action types are described in detail in the Actions section.

Every action type can receive and/or emit events to/from all other action types.

The simple story contains seven actions and uses four of the seven action types:

Action name Action type
Receive events Webhook action
ID is 1000 Trigger action
Explode people Event Transformation action
Person is engineer Trigger action
Person is student Trigger action
Person is ceo Trigger action
Send a post request HTTP Request action

The seven actions are configured to emit events between one another. We can view a graphical representation of this “event flow” by clicking the story name from the list of stories on the story page.

View story
View story

This will display the following:

Simple story action event flow
Simple story action event flow

From the diagram we can see the order in which events will be passed from action to action as they flow through the story. The “Receive events” Webhook action will be the initial source of events for this story. We can view its configuration by clicking on the action from either the diagram or story page.

Receive Events Action

By clicking on the “Receive events” action, we can see how it’s configured in the right hand side panel.

For now, we won’t worry too much about how this action is configured, but if we view the “Summary” tab, we can see the Webhook action is waiting to receive events at a specific URL similar to the following: https://<tenant-domain>/webhook/<action-identifier>/<secret-token>

When data is sent to this URL via a HTTP POST request, Tines will create a corresponding event and emit it to the receiving Trigger action, “Type is infection”.

Using the following cURL command, we can generate an event for this action (replace <webhook-url> with the URL from your “Receive events” action).

curl <webhook-url> -X POST -H "Content-Type: application/json" -d '{"event_name":"My first event","type":"infection","users":[{"name":"alice","age":25,"country":"US","job":"Engineer"},{"name":"bob","age":20,"country":"UK","job":"Student"},{"name":"carol","age":61,"country":"Ireland","job":"CEO"}]}'

View the corresponding event by clicking “Events” on the action’s panel. The event should look like the following:

Event from Receive events action
Event from Receive events action

Type is Infection Action

A Trigger action allows us to define logic statements that are applied to received events. When these logic statements match the contents of the received event, the Trigger action will emit an event to its receiving actions. The aim of the simple story is to respond when an alert relates to an infection. We can see that the type of alert is contained in the event emitted by the “Receive events” action under the “type” field:

Event from Receive events action - type field
Event from Receive events action - type field

As such, for every event it receives, this Trigger action should examine the “type” field and, if it contains “infection”, emit an event. We can achieve this by defining a regular expression rule. If the regex does not match, no event will be emitted to receiving actions.

Type is infection - action configuration
Type is infection - action configuration

From the above screenshot, we can see the following rule defined in the options block:

{
  "type": "regex",
  "value": "infection",
  "path": "{{ .receive_events.type }}"
}

Of particular importance is the path field. Here we are telling Tines to apply the regular expression (“infection”) to the field type inside the receive_events object.

Looking at the event emitted by the ‘Type is infection’ action below, we can see that the event contains:

  1. The original event it received (emitted by the ‘Receive events’ action)
  2. The result of the action it performed when it ran. In this case that is just a simple status message informing us the event it received matched a rule we had defined in the action’s options block.

This event will be received by the “Explode users” action:

Event from Type is infection action
Event from Type is infection action

Explode Users Action

Regularly, events will contain an Array of objects which we will want to handle individually. For example, an event may contain an array of IOCs that we want to sweep for one at a time. In the sample event we generated previously, there was an array called users (shown below). In the simple story, we only care if the user’s job is CEO, as such we need to examine every user in the users array individually. We can achieve this using an Event Transformation action in “Explode” mode.

"users": [
  {
    "name": "alice",
    "age": 25,
    "country": "US",
    "job": "Engineer"
  },
  {
    "name": "bob",
    "age": 20,
    "country": "UK",
    "job": "Student"
  },
  {
    "name": "carol",
    "age": 61,
    "country": "Ireland",
    "job": "CEO"
  }
]

Configuring the Event Transformation action as below will result in Tines emitting individual events for each element in the users array. Once again we define the array Tines should explode by defining its JSONPath wrapped in two sets of curly braces, in this case {{.receive_events.users}}. The to option tells Tines what to call the object created by the exploded element.

Explode users action configuration
Explode users action configuration

As there are three elements in the users array, we would expect this action to emit three events. These three events are shown below. Again the emitted events consist of the received event in full and the results of the current action. In this case, the action added each element of the array to an object called user.

Explode users action events
Explode users action events

User is Engineer, User is Student and User is CEO actions

In Tines, actions can receive from, and emit to multiple other actions. To demonstrate this, the simple story contains three trigger actions configured to receive events from the Explode users action.

Three trigger actions
Three trigger actions

Similar to the Type is infection action, these Trigger actions use regex rules to emit events when the incoming event contains a user whose job is either “ceo”, “student” or “engineer”.

Send a Post Request Action

In the simple story we want to respond when the affected user’s job is “CEO”. To demonstrate this, we will use a HTTP Request action to send a POST upon receipt of an event from the ‘User is ceo’ action.

The HTTP Request action has several configuration options that are described in detail in the HTTP Request Action section. For the simple story, we only need to concern ourselves with the url and payload options.

  • url: Here we specify where Tines should send the HTTP request. In this example we’ll make use of the Postman Echo service which is a free service to help us test API calls.
  • payload: Here we provide a list of key/value pairs to include in the body of the request. As before, we will use wrapped JSONPaths to retrieve information from incoming events.
Send a post request action
Send a post request action

From the above configuration we can see that the action is configured to take the affected user’s information (name, age, country and job) from the incoming event and POST it to the Postman Echo service. The HTTP Request action will take the response it receives and emit it as part of a new event. We can see what this looks like by viewing the action’s emitted events.

Send a post request action event
Send a post request action event

Although the Postman Echo service simply responds with copies of the data we sent it, it demonstrates how easy Tines can interact with 3rd-party REST APIs.

Conclusion

In this article we introduced a number of key concepts:

  1. In every story, actions have access to the result of all previous actions.
  2. When an action emits an event, that event will contain the result of that action and the event that action received.
  3. An action is configured using an options block, which is a JSON object specifying what it should do when run.