Getting Started with TheHive Automation

Getting Started with TheHive Automation


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 a Tines, a security automation platform, and TheHive together? 

Tracking incidents allow companies to assess and communicate risk; a security case management system like TheHive allows allows you track time to response, resolution, number of cases, 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 Security Automation platform that helps you automate entire incident response processes involving taking actions across multiple tools using any API, internal or external, allowing you to respond quicker 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 our the alert endpoint of your TheHive instance, with a title, description, source, sourceref and 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 take 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:



{
"url": "{% global_resource the hive url %}/api/alert",
"content_type": "json",
"method": "post",
"payload": {
"title": "New Email Reported from {{.read_email.from}}",
"description": "### Summary {% line_break %} {% line_break %} **From:** {{.read_email.from}} {% line_break %} {% line_break %}**To:** {{.read_email.to}} {% line_break %} {% line_break %} **Subject:** {{.read_email.subject}} {% line_break %} {% line_break %} **Date:** {{.read_email.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 %}",
"type": "external",
"source": "Tines",
"sourceRef": "phishing-{{\"now\" | date: '%s' }}"
},
"headers": {
"Authorization": "Bearer {% credential the hive api key %}"
}
}


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 a future we’ll examine how to process some of these emails to automatically create a case in TheHive with 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.*

Do less. A lot more.

Subscribe to our newsletter and get world class automation ideas straight to your inbox.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.