TheHive4py 1.8.0 is finally released. During the last 5 months, the team was busy working on TheHive and Cortex but today, it’s time to unveil the biggest milestone of TheHive’s official python API client.

1.8.0 contains 31 Github issues including 17 contributions for which, we would like to thank all the community members who helped shaping the release.

TheHive4py is getting a bit hard to maintain because of the backward compatibility constraints introduced by TheHive 3 and 4 versions. TheHive 4 also introduces new features that are not available in TheHive 3, and this makes it challenging to serve both versions with the same code base.

TheHive 4 has also its dedicated and optimised APIs (read APIs v1), and those are not used by TheHive4py, which is still relying on APIs v0 of TheHive 4.

Anyways.

What’s new?

1.8.0 release introduced a significant number of new methods and changes:

• attachment download support for files (by id), observables and task log attachments
• alert merge into case
• alert delete
• case task delete
• case task log search
• task log search
• support to alert similarity in fetch
• case observable search method
• case observable fetch method
• case observable delete method
• support to in memory files when calling APIs evolving attachments
• MISP export
• support to PAP in alerts
• add Tlp, Pap, Severity, CaseStatus, TaskStatus enumerations

in addition to some TheHive 4 related features:

• Add a version parameter to TheHiveApi class’s constructor
• Add support to ignoreSimilarity attribute
• Add support to alert.externalLink attribute

Please read the full release notes for more details.

Below, we will highlight the major features other than the self explanatory newly added methods.

New version parameter

This change is important and required for developers using TheHive4py to play with a TheHive 4 instance. the `version` parameter has been introduced to allow fine tune access to features available on TheHive 4 and not in TheHive 3, like for `alert.extrnalLink` field.

The version is set by default to Version.THEHIVE_3.value, which means version 3.

from thehive4py.models import Version

# Init an API client for TheHive 4
api = TheHiveApi(THEHIVE_URL, API_KEY, version=Version.THEHIVE_4.value)

Add support to ignoreSimilarity field

This capability has been introduced by TheHive 4.0.1 release. It allows setting an `ignoreSimilarity` flag at the case and alert observable level. When set to True it tells TheHive to ignore the observable from any similarity computing.

So, if you need to create an alert with an observable you would like to skip when running the similarity algorithm, then, you need to set ignoreSimilarity to True

Here is an example that creates and alert with an observable to be ignored for similarity:

import uuid
from thehive4py.api import TheHiveApi
from thehive4py.models import Tlp, Pap, Alert, AlertArtifact

sourceRef = str(uuid.uuid4())[0:6]

# Prepare the Alert object
alert = Alert(title='Sample alert - ID {}'.format(sourceRef), 
  tlp=Tlp.AMBER.value, 
  pap=Pap.AMBER.value, 
  tags=['TheHive4Py'],
  description='Sample alert for the blog post',
  source='dev',
  type='script',
  sourceRef=sourceRef,
  externaleLink='https://some-web-site/alert/{}'.format(sourceRef),
  artifacts=[
    AlertArtifact(
      dataType='domain', 
      data='dl.some-web-site.com', 
      tlp=Tlp.WHITE.value, 
      ioc=True,
      sighted=False,
      ignoreSimilarity=True
    )
  ])

# Init an API client instance
api = TheHiveApi(THEHIVE_URL, THEHIVE_API_KEY, version=4)

# Create the alert
response = api.create_alert(alert)

Note that the same option is available for Case observables during creation and update:

# Set an observable as ignorable

api.update_case_observable(
   observable_id, 
   {"ignoreSimilarity": True}, 
   fields=['ignoreSimilarity']
 )

Support in-memory files

Old versions of TheHiv4py required existing files when dealing with attachments. For example, to create a file case observable, the corresponding file has to be already stored on the file system before calling the `create_case_observable` method.

This release allows using files from memory and not relying on file paths. So you use, for example, an API to download a file and you want to store that file as observable, you can use the new feature of TheHive4py, as below:

from thehive4py.models import Tlp, Pap, Alert, CaseObservable

# Say you have a method to get a screenshot
file = get_screenshot()

# Prepare the observable
observable = CaseObservable(
    dataType='file',
    data=(file, 'screenshot-{}.png'.format(int(time.time())*1000)),
    tlp=Tlp.WHITE.value,
    pap=Pap.GREEN.value,
    tags=['category:screenshot']
)

# Create the observable
response = api.create_case_observable(case_id, observable)

# Close the file object
file.close()

Note: closing the file object is still required. We will handle closing the files during the upcoming releases.

Attachment download features

The new methods introduced by 1.8.0 release and related to attachment download, light some interesting TheHive APIs up.

Did you know TheHive has APIs to download existing file from the datastore? Do you know how does TheHive store files?

Well, when a file is uploaded to TheHive as case observable, alert observable or case log attachments, the file is stored in the DataStore and is given an ID that can be used in two APIs:

• `/api/datastore/{attachment_id}`: downloads the file content
• `/api/datastorezip/{attachment_id}`: downloads the file content as zip password protected file, and the password is the one defined in application.conf (defaults to `malware`)

In this release, we introduced methods to make these APIs available on TheHive4py.

Download an attachment by its ID

This method is useful if you know the attachment ID (could be an alert file observable for exemple, in TheHive 4)

# Download an attachment by a known id
response = api.download_attachment(
  attachment_id, 
  filename='screenshot.png',
  archive=False
)

# Save the attachment to disk
f = open('./{}'.format('screenshot.png'), 'wb')
f.write(response.content)
f.close()

Download an attachment of a task log

This method allows downloading the attachment of a given task log object, identified by its ID

response = api.download_task_log_attachment(log_id, archive=False)

f = open('./{}'.format('screenshot.png'), 'wb')
f.write(response.content)
f.close()

If the task log doesn’t have an attachment, this methods throws an exception.

Download a file attachment of a file observable

This methods allows downloading a file observable, and forces protecting it as password protected zip archive

response = api.download_observable_attachment(observable_id)

f = open('./{}'.format('observable.png.zip'), 'wb')
f.write(response.content)
f.close()

If the observable is not a file, this methods throws an exception.

Documentation

As you might know, with the 1.7.0 release we released a documentation website for TheHive4py where all the methods are documented. Donc hesitate to refer to it for more details: https://thehive-project.github.io/TheHive4py

Updating/Installing

To update your existing package to version 1.8.0:

$ sudo pip install thehive4py --upgrade

Got a question?

If you encounter any difficulty, please join our  user forum, contact us on Discord, or send us an email at support@thehive-project.org. As usual, we’ll be more than happy to help!