To help you get started quickly with Tines, every tenant contains a small demo story called \"Simple story\" which shows how agents 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, based on the users job title, we will take a specific action.

How the Story Works

There are six types of agents in Tines: Email Agent, Event Transformation Agent, HTTP Request Agent, IMAP Agent, Trigger Agent and Webhook Agent. Each agent is designed to be used in specific situations. For example, the Email agent can be used to send emails to one or more recipients. The agent types are described in detail in the Agents section.

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

The simple story contains seven agents and uses four of the six agent types:

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

The seven agents are configured to emit events between one another. We can view a graphical representation of this “event flow” by click “View Diagram” from the story page.

View diagram button
View diagram button

This will display the following:

Simple story agent event flow
Simple story agent event flow

From the diagram we can see the order that events will run-down the story, that is, the order in which they will be passed from agent to agent. The “Receive events” Webhook agent will be the source of events for this story. We can view its configuration by clicking on the agent from either the diagram or story page.

Receive Events Agent

By clicking on the “Details” tab of the “Receive events” agent, we can see how its configured.

For now, we won’t worry too much about how this agent is configured, but if we view the “Summary” tab, we can see the Webhook agent is waiting to receive events at a specific URL similar to the following: https://<tenant-name>.tines.io/users/<user-id>/web_requests/<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 agent, “Type is infection”.

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

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 emitted” on the agent’s “Details” tab. The event should look like the below:

Event from Receive events Agent
Event from Receive events Agent

Type is Infection Agent

A Trigger Agent 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 agent will emit an event to its receiving agents. The aim of simple story is to take action 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” agent under the “type” field:

Event from Receive events Agent - type field
Event from Receive events Agent - type field

As such, for every event it receives, this Trigger agent 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 agents.

Type is infection - agent configuration
Type is infection - agent configuration

From the above screenshot, we can see the following rule defined in the options block: json { "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’ Agent below, we can see that the event contains:

  1. The original event it received (emitted by the ‘Receive events’ Agent)
  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 agent’s options block.

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

Event from Type is infection Agent
Event from Type is infection Agent

Explode Users Agent

Regularly, events will contain an Array of objects which we will want to action 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 Agent 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 Transform Agent 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 agent configuration
Explode users agent configuration

As there are three elements in the users array, we would expect this agent 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 agent’s action. In this case, the agent’s action was to add each element of the array to an object called user.

Explode users agent events
Explode users agent events

User is Engineer, User is student and User is ceo agents

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

Three trigger agents
Three trigger agents

Similar to the Type is infection agent, these Trigger agents 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 Agent

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

The HTTP Request Agent has several configuration options that are described in detail in the HTTP Request Agent 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.
Sed a post request Agent
Send a post request Agent

From the above configuration we can see that the agent 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 Agent 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 agent’s emitted events.

Sed a post request Agent event
Send a post request Agent 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, agents have access to the result of all previous agents’ actions.
  2. When an agent emits an event it will contain the result of its action and the event it received.
  3. Agents are configured using an options block, a JSON object which specifies the action it should perform at run-time.