TheHive4py 1.4.0 Released

Version 1.4.0 of the Python API client for TheHive is now available. It is compatible with the freshly released Cerana (TheHive 3.0.0).

We’d like to thank Nick Pratley, a frequent contributor, Bill Murrin, Alexander Gödeke and “srilumpa” for their code additions and documentation.

To update your existing package:

$ sudo pip install thehive4py --upgrade

If you are just getting started with TheHive4py, you can forgo the --upgrade at the end of the command above.

New Features

  • #5: Add a method to update a case, contributed by Nick Pratley
  • #34: Add a get_task_logs method in order to obtain all the task logs associated with a given taskId. Contributed by Bill Murrin
  • #37: A new, very cool case helper class by Nick Pratley
  • #39: Add support for custom fields to the case model
  • #40: Ability to run a Cortex analyzer through the API by Alexander Gödeke
  • #45: Simplify case creation when using a template by providing just its name
  • #49: Add a query builder capability to support TheHive’s DSL query syntax

Paris? Are you There?

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

Featured

Introducing Cerana

Update: 2 days after publishing this blog post, we’ve released Cerana 0.1 (TheHive 3.0.1) which fixes a number of issues. We encourage you to use 3.0.1 instead of 3.0.0.

The friendly honeybees at TheHive’s code kitchen were pretty busy lately even though winter came and temperatures have been close to zero Celsius in Paris, France. As we wrote a couple of weeks ago on this very blog, we are happy to announce Cerana to the world, available immediately.

Cerana or TheHive 3.0.0 is the latest (and obviously greatest) release of a now highly popular open source, free Security Incident Response Platform (or SIRP for short). Its flagship feature in comparison to previous releases is Dynamic Dashboards.

Dynamic Dashboards

Dynamic Dashboards replace the Statistics module in Cerana to allow you to explore the data available in Elasticsearch, which TheHive uses for storage, in many ways. For example, you can have a usage breakdown of Cortex analyzers, the number of open cases per assignee, the number of alerts per source (MISP, email notifications, DigitalShadows, Zerofox, Splunk, …), the number of observables that have been flagged as IOCs in a given time period, how many attributes were imported from MISP instances, top 10 tags of imported MISP attributes or incident categories.

case3.png
Dynamic Dashboards

Dynamic Dashboards can be created by an analyst and kept private or shared with the other team members. Dashboards can also be exported and imported into another instance. This would facilitate community participation in the establishment of valuable data exploration graphs to drive DFIR activity and seek continuous improvement.

When you’ll migrate to Cerana, you won’t have to build dashboards from scratch. We recreated more or less those which were available under the Statistics view and included them in the Cerana build.

Cortex and MISP Health Status

Cerana will also allow you to monitor the health status of all the Cortex and MISP instances that it is connected to. In the bottom right corner of TheHive’s Web UI, the Cortex and MISP logos appear when you have configured the integration with those products as in previous releases. However, the logos will have a small outer circle which color will change depending on whether Cortex and/or MISP instances are reachable or not.

status
Cortex & MISP Health

If TheHive can’t reach N out of M Cortex/MISP instances, the outer circle will be orange. If it can’t reach all M instances, the circle will red. If everything is fine, the circle will be green. The exact status of each Cortex/MISP instance can be seen in the About page. And when you try to run analyzers on a Cortex which cannot be reached, TheHive will tell you so as well.

about
Cortex & MISP: Version & Status

Sighted IOCs

In previous releases of TheHive, observables can be flagged as IOCs. However, this doesn’t necessarily mean you’ve seen them in your network. Think for example of a suspicious attachment which you’ve submitted to Cuckoo or Joe Sandbox through Cortex. The analyzer returns some C2 addresses to which the sample tries to connect to. You’d be right to add those C2 addresses to your case and flag them as IOCs. Then you search for them in your proxy logs and you find connection attempts to one out of four. In previous versions, you’d add a seen label but this would be inconsistent among analysts. One may use found instead. Another will add a description and no labels.

To avoid such situations and give you a simple way to declare an IOC as seen, Cerana adds a sighted toggle which you can switch on/off. We will leverage this toggle in future versions to indicate sightings when sharing back cases to MISP.

Other Features and Improvements

Cerana contains numerous other features and improvements such as:

  • Case template import, export
  • The ability to assign default values to metrics and custom fields to case templates
  •  The ability to assign by default tasks to their rightful owners in case templates
  • Show already known observables when previewing MISP events in the Alerts page
  • Add autonomous systems to the list of default datatypes
  • Single-sign on using X.509 certificates (in BETA currently)

We will update the documentation for Cerana in the upcoming weeks. So stay tuned.

Download & Get Down to Work

If you have an existing installation of TheHive, please follow the migration guide.

If you are performing a fresh installation, read the installation guide corresponding to your needs and enjoy. Please note that you can install TheHive using an RPM or DEB package, use Docker, install it from a binary or build it from sources.

Support

Something does not work as expected? You have troubles installing or upgrading? No worries, please join our user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We are here to help.

Introducing Cortex4py

Following popular demand, the chefs at TheHive Project‘s code kitchen are happy to announce the immediate availability of Cortex4py.

What Is It?

Cortex4py is a Python API client for Cortex, a powerful observable analysis engine where observables such as IP and email addresses, URLs, domain names, files or hashes can be analyzed one by one using a Web interface or en masse through the API.

Cortex4py allows analysts to automate these operations and submit observables in bulk mode through the Cortex REST API from alternative SIRP platforms (TheHive has native support for one or multiple Cortex instances) and custom scripts.

 

Use It

To install the client, use PIP:

$ sudo pip install cortex4py

 

How Much Does it Cost?

Cortex4py is released under an AGPL license as all the other products we publish to help the IR community fight the good fight. So apart from the effort it’ll cost you to install and use, the price of our software is nada, zero, rien. But if you are willing to contribute one way or another, do not hesitate to drop us an email at support@thehive-project.org or contact us via Twitter.

Support

Something does not work as expected? You have troubles installing or upgrading? No worries, please join our  user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We are here to help.

All Fresh CortexUtils, New Cortex Analyzers

Ahead of the imminent release of Mellifera 12 (TheHive 2.12.0), a new, major (as in MAJOR) version of your (soon to be?) favorite Security Incident Response Platform, we’ve made rather significant changes to Cortex analyzers and released a new version of the CortexUtils Python library.

TL;DR

If you are in a hurry:

$ sudo pip install cortexutils --upgrade
$ cd where/your/analyzers/are
$ git pull master

Adjust the Cortex configuration for the new MISP 2.0 analyzer and for Hippocampe as shown below if you are using these analyzers then import the corresponding report templates into TheHive:

  • download the updated package
  • log in TheHive using an administrator account
  • go to Admin > Report templates menu
  • click on Import templates button and select the downloaded package

CortexUtils 1.2.0

CortexUtils has been updated to include a new function called build_taxonomy() which is required for analyzers relying on the Python library we released to make their development development easier.

Mini-Reports in The Observable Tabs

Starting from Mellifera 12 (TheHive 2.12.0), mini-reports will be displayed in the observable tab in each case as soon as an analysis has been completed. Now analyzers compute their short/mini reports and put them in the summary section of their JSON output, ready for consumption. TheHive 2.12.0 and up will no longer create them on-the-fly.

Taxonomy

The mini-reports of all the analyzers have been updated to comply with a taxonomy that is similar to the one we were already using for VirusTotal:  VT:Score="14/56”.  A “maliciousness” level was already included in TheHive’s analyzer templates and we used a specific color to display each level. This level is now produced directly by the analyzers:

  • info / blue: the analyzer produced an information, and the short report is shown in blue color in TheHive.
  • safe / green : the analyzer did not find anything suspicious or the analyzed observable is safe (according to the analyzer). TheHive displays the short report in green color.
  • suspicious / orange : the analyzer found that the observable is either suspicious or warrants further investigation. The short report is orange colored in TheHive.
  • malicious / red : the analyzer found that the observable is malicious. The short report is displayed by TheHive in red color as show below:

sc-short-VT.png

The short report is built with the summary() function of an analyzer. The build_taxonomy() of cortexutils mentioned earlier should help building it.

MISP 2.0

The MISP analyzer has been updated to version 2.0 and includes new functionality submitted by our long-term contributor Nils Kuhnert from CERT-Bund (thanks a heap!). Unlike the previous version, v 2.0 will let you search for an observable in multiple MISP servers at the same time.

The analyzer accepts a truckload of datatypes as input. To make it work, install the pymisp Python library. It should already have been installed if you are just updating your current analyzers. You will also have to change Cortex configuration file (application.conf) for this new version:

MISP {
 url=["https://mymispserver_1", "https://mymispserver_2"]
 key=["mykey_1", "mykey_2" ]
 certpath=["", ""]
 name=["MISP_SERVER_NAME_1", "MISP_SERVER_NAME_2"]
}

Important note: You have to adjust your existing configuration to match the one shown above. The certpath variable can be left blank if you are not using a self-signed certificate.

When called from TheHive, the following output is produced:

sc-short-MISP.png

sc-MISP-long.png
TheHive: MISP 2.0 Analyzer – Short and Long Report Samples

The short report will show the number of unique events found in all MISP servers while the long report will show information of each matching event in each MISP server.

CERTatPassiveDNS

The CERTatPassiveDNS analyzer is a new submission by Nils (thanks again). It lets you check the CERT.at PassiveDNS service for a given domain or hostname. It takes domains and FQDN as input.

Access to the CERT.at service is allowed to trusted partners only. If you think you qualify, please contact CERT.at. You do not need to add specific information into the Cortex configuration file to benefit from this analyzer as it calls the whois system command to perform the pDNS requests.

When called from TheHive, the following output is produced:

sc-certatpdns-short.png

 

sc-long-CERTatPassiveDNS_1_0.png
TheHive: CERTatPassiveDNS Analyzer – Short and Long Report Samples

 

Miscellaneous

The latest version of the Cortex-analyzers repository also include the following bug fixes and improvements:

Running Into Trouble?

Shall you encounter any difficulty, please join our  user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We will be more than happy to help!

Correction: July 6, 2017 
An earlier version of this post mispelled Nils Kuhnert’s last name.

TheHive: June-Dec 17 Roadmap

A new version of TheHive will be released by the end of June. We will take this opportunity to review our release naming and numbering from the ground up.

Months ago, we started giving ‘major’ versions (2.10, 2.11, …) the name of honey bee varieties. 2.10 was called Buckfast. 2.11, the current version, is called Mellifera. And we were supposed to give 2.12 yet another name. However, and after the few hiccups we’ve encountered with our QA as of late, we have decided to change things around in order to make sure new releases are as stable and well-maintained as you should expect them to be.

Starting from the next release (2.12), we will abide by the following numbering scheme:

  • Major versions == X (2, 3, …)
  • Minor versions = X.Y (2.12, 2.13, 3.1, …)
  • Hotfix/maintenance versions = X.Y.Z (2.12.1, 2.13.2, 3.1.1, …)

Only major versions will have corresponding honey bee names. So long as we stay with v2, we’ll keep calling all the minor versions Mellifera N (2.12.0 = Mellifera 12). Version 3 will be called Cerana.

Mellifera 12 – June 29, 2017 (planned date)

Mellifera 12 (v 2.12) will succeed to Mellifera 2 (the current version) to comply with the new naming scheme. It will allow you to see how similar new alerts are to existing cases so you can decide whether you import them into an existing case, create a new one or ignore them altogether. Mellifera 12 will show you the status of all the related cases (#229) to the one you are working on. Finally, you’ll have the ability to change the default case template before importing an alert.

M12 will also support custom fields (#12), a feature that has been requested by numerous users. This version will also add mini-reports to the Observables tab. That way, once a Cortex analysis has been completed, analysts will be able to view part or all the resulting short report in that tab instead of having to navigate to the page of each observable to read the short report.

Mellifera 13 – September 14, 2017

TheHive 2.13 should be the last Mellifera version. It will complete TheHive’s integration with MISP by adding the ability to export all observables or a subset of them to a MISP instance. Please note that TheHive allowed you from the start to import events from multiple MISP instances but since sharing is caring, we wanted to add the ability to export to this very popular threat sharing platform from your Security Incident Response Platform (SIRP). We do not want to rush it though.

Cerana – October 12, 2017

Cerana or TheHive 3.0.0 will bring a complete UI overhaul to make it even easier to work on cases, perform analysis and get your job done, after the interface refreshments Mellifera brought. It will lay the ground for some nifty features we have in mind.

Cerana 1 – November 15, 2017

TheHive 3.1.0 will include dynamic dashboards: the ability to work with the statistics and metrics the way you want and generate customized dashboards to help you drive your activities.

Keep an eye on TheHive’s milestones on GitHub. There are other features and enhancements that we might add as we progress and we will reflect them on that page.

Correction: June 12, 2017
An earlier version mentioned GitHub issue #36 as pertaining to custom fields while it is a request for globally-defined tags that an analyst can choose from.

 

 

 

Mellifera 1: Bugfixes, Enhancements and Documentation

Last week, we have released Mellifera (TheHive 2.11.0), a major version of your favorite (or soon to be favorite) Security Incident Response Platform. Sadly, some annoying bugs have slipped past our QA (n’est-ce pas Thomas ?).

We are happy to announce the availability of Mellifera 1 (TheHive 2.11.1) which corrects those bugs and adds a few enhancements detailed below.

Issues Corrected

  • #204: update case templates created with previous versions of TheHive.
  • #205: remove duplicate tags associated to an observable present in two cases upon a case merging operation.
  • #206: apply case templates when an alert is converted into a case.

Enhancements

We also took the opportunity of this hotfix to add the following enhancements:

  • #180: merge duplicate tasks during a case merge operation. Starting from this release, if you have waiting tasks (i.e. not assigned) with the same name in cases you’d like to merge, the new merged case will have only one task instead of two.
  • #211: show the number of available analyzer reports for each observable. If an observable has not been analyzed yet, say so.

Documentation

Please note that we have moved all the documentation of TheHive in a new repository. If you are not using TheHive4py 1.2.0 (or future versions), you can send alerts to Mellifera using the API as documented.

Download & Get Down to Work

If you have an existing TheHive installation, please follow the new migration guide.

If you are performing a fresh installation, read the installation guide corresponding to your needs and enjoy. Please note that you can install TheHive using an RPM or DEB package, deploy it using an Ansible script, use Docker, install it from a binary or build it from sources.

Support

Something does not work as expected? You have troubles installing or upgrading? No worries, please join our  user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We are here to help.