Getting started with TheHive automation

Last updated on

Written by Thomas KinsellaCo-founder & COO, Tines

TheHive is a full-featured scalable, open-source, and free security incident response platform. Tines is a peer leader in Security Automation. Several large and small companies, including Auth0, use both Tines and TheHive to automate their Incident Response processes. In this blog, we’ll learn how to use the TheHive API together with Tines to automate the creation of alerts from phishing emails and more.

Why use Tines, the no-code automation platform for security teams, and TheHive together?  

Tracking incidents allow companies to assess and communicate risk; a security case management system like TheHive allows you to track time to response, resolution, number of cases, and detection methods so you can improve the efficacy of your security program. Together with TheHive Cortex, you can enrich and action observables directly. 

Tines is a dedicated no-code automation platform for security teams that helps you automate entire incident response processes involving taking actions across multiple tools using any API, internal or external, allowing you to respond quickly to the alerts that matter most. 

Things you might want to create cases in TheHive for: 

You can also use Tines in combination with TheHive and Cortex to: 

  • Enrich alerts with data stored in a SIEM 

  • Crowdsource and investigate logins via Slack, or Microsoft Teams

  • Gather context from your endpoint tools on all alerts

  • Send follow-up emails to users

  • Remove mails from inboxes, block IOCs and keep your environment safer

TheHive makes it easy to create cases manually, however, without automation this is a time-consuming process that leads to lower employee productivity, satisfaction, and churn. 

Getting Set Up - TheHive 

If you do not have a TheHive platform set up, you can get started here. Alternatively, you can start immediately using the Docker Quick Install Guides or on the AWS Marketplace.

When you have set up the platform visit Settings->Users-> Create or reveal an API Key. Note this API Key down, we’ll use it in a minute!

Getting Set Up - Tines 

If you do not have a Tines account you can sign up for a free Tines Community Edition here. Once you have started, you should create a Credential, ‘the hive’ with your API Key, and a Global Resource ‘the hive URL with your TheHive URL (including ‘HTTPS’ and the port if required). 

You should now create a credential in Tines called ‘the hive API key’ with the API key we configured above.

You may also find it helpful to complete the Tines tutorial to learn more about interpolated data etc. 

We could do this simply in curl like this:

curl -X POST --header "Content-Type: application/json" --data '{  "title": "New Alert",  "description": "Foo Description",    "type": "external",  "source": "VirusTotal foo",  "sourceRef": "alert-ref3"  }' -H 'Authorization:Bearer apikey' http://{{.thehive_domain}}/api/alert

‍Once you have created your Tines tenant and TheHive, it’s time to get started!‍

Creating a Story 

In Tines, create a New Story called ‘TheHive’ (Stories -> New Story). You’ll be presented with a blank Storyboard page.

In Templates, search ‘The Hive Project’ to view a list of available Tines templates. Find ‘Create a Basic Alert’ and drag it to the Storyboard.

In the Action properties panel on the right we can see what this template will do:

Similar to our curl command above, this will send an alert to the alert endpoint of your TheHive instance, with a title, description, source, sourceref, together with headers. Edit the Action with some sample text that you think is appropriate.

Click Run

With the Action selected, click ‘Run’ at the top of the screen. This should run the Action in Tines and create an Alert in TheHive. Viewing your TheHive instance you should see a new alert:

We can see in Tines that the alert has been successfully created by viewing the Event in the Events tab of the action properties panel.

So creating an alert in TheHive from Tines is Easy! Now let’s explore a sample use case.

Creating an alert in TheHive for every email 

In this example, we’ll read an email and alert on every new mail sent to a mailbox.

We can do this through o365, Gmail or IMAP. In this example let’s use an IMAP because it’s the simplest to set up. 

  • Drag an IMAP Action onto the storyboard

  • Rename it ‘Read Email’ and Set the Schedule as ‘Every 5 minutes’

  • Enter an IMAP Server; Username and Password (You can read more about using an app-password for Gmail here)

  • Click ‘Run’ (Note, the first time you click Run an initial status for the mailbox will be run - it will read in however many mails it has. You can see this in ‘Logs’ in the action properties panel)

  • Now, send yourself another email and then Click ‘Run’ again

  • You should now see a ‘1’ in the top right corner of the Action, and in the ‘events’ tab of the action properties panel you can view the event

Congratulations! You’re now reading mails from your email in Tines. Tines will automatically check this mailbox every five minutes and emit a new event every time it detects a new email. 

Connecting your Mailbox to TheHive 

The last step in this will be to create a case in TheHive for every email. 

First, connect the IMAP Action to the HTTP Request Action.

Next, click on ‘Create New Basic Alert’ and Edit the Action properties.

In the Title field type ‘New Email Reported from… ‘ and then {{.}}

You should find when you place your cursor beside the `.` that Tines will suggest the data that could be used in this field. 

In this example, let’s select ‘{{.read_email.from}}’ i.e. the sender of the email

Now, in the body let’s type ‘The email had the subject {{.read_email.subject}}. The body should be…

Everything else can remain the same. You can just copy this config:

"description": "### Summary {% line_break %} {% line_break %} **From:** {{.read_email.from}} {% line_break %} {% line_break %}**To:** {{}} {% line_break %} {% line_break %} **Subject:** {{.read_email.subject}} {% line_break %} {% line_break %} **Date:** {{}} {% line_break %} {% line_break %} **Body:**{% line_break %}{% line_break %}```{% line_break %}{{.read_email.body}}{% line_break %}``` {% line_break %}{% line_break %}### Attachments {% line_break %}{% line_break %}| Name | Size (Bytes) | MD5 Hash | {% line_break %} | --- | --- | --- |{% line_break %} {% for attachment in read_email.attachments %} | {{attachment.filename}} | {{attachment.sizeinbytes}} | `{{attachment.md5}}` | {% line_break %}{% endfor %}{% line_break %}{% line_break %}",

This should create a ticket like the below:

Congratulations! You’ve now automated a process to create cases in TheHive for all mails reported to your abuse inbox!

In the future, we’ll examine how to process some of these emails to automatically create a case in TheHive with an analysis of the attachments and URLs. 

*Please note we recently updated our terminology. Our "agents" are now known as "actions," but some visuals might not reflect this.*

security teams

Get started