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:
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.
This will display the following:
The Storyboard diagram
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.
ℹ️Info
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:
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:
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.
💡Note
From the above screenshot, we can see that a rule has been defined for this action.
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:
The original event it received (emitted by the 'Receive events' action)
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:
ℹ️Info
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.
💡Note
"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.
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.
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.
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.
💡Note
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.
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.
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:
In every story, actions have access to the result of all previous actions.
When an action emits an event, that event will contain the result of that action and the event that action received.
An action is configured using an options block, which is a JSON object specifying what it should do when run.