TheHive Scripting: Task Imports

Morning fellow forensicators!

While I could and should (and will?) put up an entire post just about TheHive itself, I’m skipping right to some scripting that I recently had to put together. But, to give a proper, albeit brief shoutout:

If you have not heard of TheHive yet, I’m going to highly recommend you zoom over here: https://thehive-project.org/.

TheHive is one of the best platforms I’ve ever seen/used for incident management. It’s definitely what some of us have been craving for years in Incident Response. Furthermore, it’s Python library (https://github.com/TheHive-Project/TheHive4py) makes for easy scripting as well. That’s what I’ll cover in this post.

Over the past 24 hours, I’ve been needing to do a massive task list import into TheHive. Like.. a lot. It can seem daunting when being done manually, but automated, it’s much simpler. Let’s break this down into pieces:

Setting up TheHive API

The first part is pretty straightforward — we need to get ready to establish API connectivity to TheHive. Here’s some sample code:

# TheHive4Py Imports
from thehive4py.api import TheHiveApi
from thehive4py.models import CaseTask

# Server variables
hiveServer = '<thehive server>'
hiveKey = '<api_key>'

# Establish API
api = TheHiveApi(hiveServer, hiveKey)

A look at each of these:

  1. From thehive4py.api, we need to import TheHiveApi. This is what allows you to establish connectivity to the server. We also imported CaseTask — you’ll need this shortly.
  2. While this part is entirely optional, I typically will save API connection details as variables. This allows me to move the API call wherever I need to in the script (or replicate it), and not have to change parameters more than once.
  3. Once these have been defined, simply called TheHiveApi to get ready for API calls.

Grabbing Case ID

The next step (which I intend to build out better in the next version) is to grab the relevant case id. We need this so the API knows which case to add the task to. Admittedly, I grabbed this ad-hoc using a Python CLI, not from the script. But, here’s how you’d grab that with the api established above:

cases = api.find_cases
for case in cases:
  print(cases)

My case list is currently small, so I was able to easily grab the ID that I needed. I’ll touch on this in another post.

Building out the Task Model

Once this has been setup, the next step is to build out the CaseTask model. Now, this is only scratching the surface of what you can do with the API, but it’s what I needed to do — so that’s what I’ll focus on.

The CaseTask model can accept the following data (a snippet from https://github.com/TheHive-Project/TheHive4py/blob/master/thehive4py/models.py):

While all of the above can be accepted, I’ve found that when mass-importing tasks I don’t want to assign owners, flags, or status at this point. Someone’s task list will either get destroyed OR priorities will be incorrectly assigned. To build out the model, our script begins to look a bit like this:

  1. I’ve simplified this (and hidden some revealing details) a bit, but the data I want to import is stored within a JSON file. We begin by opening up the file and parsing line by line.
  2. Each line contains relevant data, only some of which I want inside my Task. So, parse accordingly (I’m missing this section in the script, but think of it as “do a thing with your data”.
  3. Import the data into the CaseTask model.
  4. Lastly, create the case task using the api.create_case_task model. You’ll need the Case ID we found up above, as well as the correct Task model.

And off you go!

Bringing It All Together

Let’s bring all this together in a single unified script: