Dear community, the new year has brought us another opportunity to build new features in your favorite Security Incident Response Platform, TheHive. We wish you a cheerful new year ahead and we thank you for being beside us all these years.
Last week, we released TheHive 4.0.4 and TheHive4py 1.8.1, and here is the official announcement including the details of the new features.
These releases focused on adding more capabilities to play with alert observables and give more flexibility when building alert feeders.
Please find the change logs for more details:
- TheHive: https://github.com/TheHive-Project/TheHive/releases/tag/4.0.4
- TheHive4py: https://github.com/TheHive-Project/TheHive4py/releases/tag/1.8.1
What’s new in TheHive
New Alert observable APIs
The major change in TheHive 4.0.4 is related to alert management. In TheHive 3, alert observables were included in the alert as an array of observable objects, and not as independent objects with links to the alert itself. This data model made alert observables CRUD operations, a bit challenging.
TheHive 4 has a better design for this, and alert observables have their own existence, and can be added/updated and deleted independently from the alert object.
This new design allows adding dedicated API endpoints to:
- Add an observable to an existing alert;
- Update the data of an existing alert observable;
- Delete an observable from an alert.
Those APIs are not used by the user interface for now.
New Alert properties
This release introduced a new property called `importDate`. It represents the date at which an alert has been merged into a new/existing case. This property is then used to:
- Allow filtering the alert list, for example: “List the alerts merged today”
- Display the duration between the alert creation and its merge into a case.
This new property is of course available on the dashboard creation UI as a date field, among others:
imported: true if the alert has been merged- `handlingDurationInSeconds`: number of seconds before importing an alert
- `handlingDurationInMinutes`: number of minutes before importing an alert
- `handlingDurationInHours`: number of hours before importing an alert
- `handlingDurationInDays`: number of days before importing an alert
To showcase the mentioned new properties, here are some screenshots:
What’s new in TheHive4py
The 1.8.1 release of TheHive4py mainly focuses on adding support to the new alert APIs introduced by TheHive 4.0.4. It comes with 3 new functions:
- `create_alert_artifact` to allow developers adding a new artifact to an existing alert
from thehive4py.api import TheHiveApi
from thehive4py.models import Tlp
THEHIVE_URL = 'http://127.0.0.1:9000'
THEHIVE_API_KEY = '**YOUR_API_KEY**'
api = TheHiveApi(THEHIVE_URL, THEHIVE_API_KEY)
# Instanciate a new domain artifact
artifact = AlertArtifact(dataType='domain', data='malicious-domain.tld', ignoreSimilarity=True, ioc=True)
api.create_alert_artifact(ALERT_ID, artifact)
# Instanciate a new file artifact
artifact = AlertArtifact(
dataType='file',
data='malicious-file.exe',
ignoreSimilarity=False,
ioc=True,
sighted=True,
tlp=Tlp.RED.value)
api.create_alert_artifact(alert_id, artifact)- `update-alert-artifact` to allow updating the data of an existing alert artifact:
from thehive4py.api import TheHiveApi
from thehive4py.models import Tlp
THEHIVE_URL = 'http://127.0.0.1:9000'
THEHIVE_API_KEY = '**YOUR_API_KEY**'
api = TheHiveApi(THEHIVE_URL, THEHIVE_API_KEY)
# Create a new domain artifact
artifact = AlertArtifact(dataType='domain', data='malicious-domain.tld', ignoreSimilarity=True, ioc=True)
response = api.create_alert_artifact(ALERT_ID, artifact)
# Update its tlp, sighted and ignoreSimilarity flags
artifact_data = response.json()[0]
artifact_data['tlp'] = Tlp.RED.value
artifact_data['sighted'] = True
artifact_data['ignoreSimilarity'] = False
new_artifact = AlertArtifact(json=artifact_data)
api.update_alert_artifact(artifact_data['id'], new_artifact, fields=['tlp', 'ioc', 'ignoreSimilarity'])- `delete_alert_artifact` to allow removing an existing artifact from an existing alert
from thehive4py.api import TheHiveApi
THEHIVE_URL = 'http://127.0.0.1:9000'
THEHIVE_API_KEY = '**YOUR_API_KEY**'
api = TheHiveApi(THEHIVE_URL, THEHIVE_API_KEY)
# Delete alert artifact
api.delete_alert_artifact(ARTIFACT_ID)Note that these new three methods are only available when using TheHive4py with TheHive 4.0.4+
You can find more details on the official documentation of TheHive4py.
Updating/Installing
To update your existing package to version 1.8.1:
$ sudo pip install thehive4py --upgrade
How to report issues
Please open an issue on GitHub with the dedicated template for TheHive 4 or the dedicated form for TheHive4py. We will monitor them closely and respond accordingly.
Running Into Trouble?
Shall you encounter any difficulty, please join our user forum, contact us on Discord, or send us an email at support@thehive-project.org. We will be more than happy to help!
TheHive Project 