I’ve struggled for a long time to find a case management system that I thought fit well within the constructs of how analysts actually perform investigations. Most case management systems are actually just help desk ticketing systems that have been retrofitting to fit a security use case. This is what I see most often when SOCs are using tools like Remedy, RTIR, or OTRS. Last November, a group of researchers from CERT Banque de France (CERT BDF) released a new case management system called TheHive. The authors of the project describe TheHive as an “open source and free security incident response platform designed to make life easier for SOCs, CSIRTs, CERTs, and any information security practitioners dealing with incidents that need to be investigated and acted upon swiftly.” I would simply describe TheHive as a purpose built case management system to facilitate the investigation of security incidents. I’ve enjoyed using the TheHive so much that I actually integrated it into my Investigation Theory course where I teach people how to approach investigations and hunt down bad guys. In this post, I want to discuss a few features of the TheHive and why I enjoy it so much.
Architecture and Installation
TheHive is written in Scala and uses ElasticSearch to store and access data on the back end. The front end uses AngularJS and Bootstrap. A number of REST API endpoints are also provided to allow for integrations and bulk actions.
You’ll see Cortex mentioned in the diagram shown above. Cortex allows users to submit observables and indicators of compromise to popular open source intelligence tools via a series of Python-based analyzers. Ultimately, it is a separate tool with it’s own codebase, but TheHive and Cortex go together like peas and carrots, so you’ll see them mentioned a lot in TheHive documentation. The installation command I’ll provide below will actually install both of them as a single integrated container.
There is a traditional Ubuntu 16.04 installation option described here which is probably most appropriate for production systems: https://github.com/CERT-BDF/TheHive/wiki/Installation-guide.
If you just want to try TheHive or run it locally, you can get it running via containers with Docker. The installation process here couldn’t be simpler:
- Build an Ubuntu 16.04 system and ensure it’s up to date on system and software patches.
- Install Docker
Command: curl -fsSL https://get.docker.com/ | sh
- Download and run TheHive w/ Cortex ():
Command: docker run –publish 8080:9000 –publish 8081:9001 certbdf/thehive-cortex
- Connect to the web interface using a browser: http://IPofServer:8080
- Follow the on screen prompts to create an administrative user account
The core construct of TheHive is the investigation case. I like this because the case is also the core construct of most security investigations, whether you’re reviewing alerts, reverse engineering malware, or working a declared incident. The case construct doesn’t provide a lot of bells and whistles, but that’s okay because I don’t think it has to. A lot of ticketing systems that are built to serve too many masters quickly become too generic to be useful. That isn’t the case here.
I particularly appreciate that you can add tags to cases for quick searching and filtering. You can also track TLP levels, which can help govern and facilitate the sharing of data. This is a nice feature that really shows how TheHive was custom built for investigation tracking. All the data you put into a case is easily searchable from the search bar at the top of the screen. This makes it really easy to determine if activity you’re currently observing was present in any earlier case.
Once you’ve created a case, you can create, assign, and track tasks. A task can really be anything, but I recommend using them to track the actions taken to answer investigative questions. For example, if you’re investigating an exploit kit infection, a common question might be, “What was the system doing prior to when the alert was generated?”. To answer this, you’ll need to review evidence from whatever data source you have that will hold the answer. So, a task could be “Review HTTP Proxy data to determine what the host was doing in the 10 minutes leading up to the alert.”
In addition to answer seeking, tasks are also useful to track containment, eradication, and remediation events. You can create a task for disabling user accounts, quarantining a system, deploying an image to a system, or providing user security awareness counseling.
Tasks, like cases, have the concept of assignment. Therefore, each task can be individually assigned to an analyst for the work to be performed. By default, a task doesn’t have an owner until someone clicks into it, or “takes” it from the Waiting tasks queue in the top menu bar. This effectively creates a task queue that analysts can watch to help facilitate their work load. The queue can be filtered by any number of criteria like a specific tag, a case number, a task name, or a keyword. Tasks that are assigned specifically to you will appear in the My tasks queue in the top menu bar.
As a SOC evolves, it becomes critical to define playbooks that help analysts consistently approach investigations that share common attributes. For example, most the steps you take to initially investigate a series of failed passwords attempts or a phishing e-mail will generally be the same. If you can define those steps, you’ll have a great head start for training new analysts and ensuring most investigations start off on a level footing. TheHive provides a unique case template system that allows you to define common investigations and pre-populate case metadata and tasks.
In the example above, I’ve defined a template for investigations related to exploit kit activity. Now, any time I create a new case I can select this template and all the information you see there will be pre-populated into the case details. The real power here is in the ability to automatically create a series of tasks that should be completed when spawning the case. This essentially lays out the investigative playbook for you. With that, you get the added benefit of automatically populating the Waiting tasks queue so that other analysts can jump into the investigation or start completing containment and eradication tasks. This is, hands down, my favorite feature of the tool.
A key feature of any case management system should be collaboration, and TheHive hits the mark here. Each analyst using TheHive gets their own account which is used to log any actions they take within the tool. Users can own cases and/or tasks. One thing I particularly like is that once you create a case, virtually any action taken with it is recorded to create an audit trail. This audit trail is displayed to the right side of the individual case screens in a Twitter-style feed as seen in several of the images I’ve already shared.
Observables and Analyzers
TheHive allows you to create separate entries for interesting observables within the context of a case. An observable is any interesting data artifact, and TheHive comes with a number of common observable types built in. This includes things like IP addresses, domain names, HTTP URIs, etc. Of course, you can also define your own types which makes this capability quite flexible.
There are multiple benefits to tracking observables. The obvious one is that you can search for them during later investigations to bring in additional context. You can also export them for later import into a blacklist, whitelist, or detection mechanisms. Finally, you can use the built in Cortex integration to automatically submit the observables to any number of OSINT research sites. This is a very simple process, and primarily just requires that you input API keys for each service you’ll be using. Some of the existing integrations include Passive Total, Virus Total, and Domain Tools.
API and Integrations
Because the TheHive was built on a series of open API’s, it’s incredibly flexible in terms of integrating with other tools. The authors have produced really nice API documentation here: https://github.com/CERT-BDF/TheHive/wiki/API%20documentation. You’ll see that the documentation provides multiple examples of request formatting, along with several use cases. This includes the ability to query, create, and manipulate cases, tasks, and observables. This has immediate tangible benefits.
Consider a scenario where you’re running a signature based IDS. Any time a specific set of rules associated with exploit kit activity generates an alert, you could use the API to create a new case using a template like the one I showed earlier that is specifically designed for investigation of exploit kit related activity. Using this approach you haven’t just done a simple automation, you’ve created a workflow based on the playbooks you’ve developed. When you or another analyst go to review new alerts, anything related to exploit kits will already have a series of tasks created and waiting for you to accomplish. This is a time saver for experienced analysts, and a teaching tool for younger analysts who might not know what move to make next.
In addition to the APIs, TheHive can integrate with MISP and you can also write custom analyzers for use with Cortex. Once again, there are a lot of options here.
This post discussed a few of my favorite features of TheHive and how they can be used in practice. There are quite a few other features like reporting and metrics that I didn’t discuss here, so make sure to check those out on your own. A lot of tools that are used in SOCs were born in them. However, this is not an easy thing to do. Every SOC I’ve been in is different, and most of the times the tools that might come out of them won’t be nearly flexible enough to fit into the workflow that exists in another organization. The developers of TheHive have hit the delicate balance of creating a tool that is focused enough to deliver on immediate use cases, while still being broadly focused and flexible enough to be adapted to differing use cases. As stated earlier, it’s for that reason I use TheHive in my Investigation Theory course and why I’ll be recommending it for individuals who want to learn how to be analysts and for organizations that are seeking a simple case management solution that can get the job done.
You can learn more about TheHive at the project’s homepage here: https://thehive-project.org/. If you’d like to learn more about the investigation process and facilitating it with TheHive, be sure to check out the Investigation Theory course.
* Some of the images in this post were created from my home lab, but a few were borrowed from TheHive official documentation linked throughout the article.
Great share, thanks! We’ve been looking for an incident teaching tool like this for some time as our SOC’s maturity has forced us out of our IT ticketing system. Do you know if there is a way within Hive to add additional field? For example we track incident category as well as delivery vector. For consistencies she, I prefer to use predefined lists for this.
I don’t believe you can do this as of now, but I did notice this open feature request for that: https://github.com/CERT-BDF/TheHive/issues/12. Might be worth adding a +1 there if that would be useful to you!
And by incident teaching I mean incident tracking 🙂
It might be worth mentioning that if you installed with these docker directions, you can also get to the cortex UI via http://IPofServer:8081/index.html#/analyzers
Just playing around with this, but I didn’t see where to upload a file to a case (screenshot or other artifact). Am I just not seeing it?