TheHive 4.0 is out!

Introduction

Several months,no, years ! after the first line of code – the first line was committed in 2016–, we are very excited and proud to announce the release of TheHive 4.0.

This means more than a major version for us. This was – and still is — like a completely new project, a new generation, a lot more challenging than before. We had to make the application climb a major step to introduce new key features, some we added in this version, others we have in mind for the future.

Objectives

The development of the second generation of TheHive, aka. version 4, was driven by three main objectives:

  • Add support to multi-tenancy: allow 1 instance of TheHive to serve many teams and organisations
  • Add support to Role Based Access Control to define fine grained user profiles
  • Rethink the data model and structure to support the goals listed above (Moving from Elasticsearch as main persistence layer, to a data model designed as a graph).

Challenges

TheHive Project is thoroughly adopted by SOC, CERTs and CSIRT teams, who decided to go with TheHive Project since the first releases. It is worth noting that until today, TheHive has had a total of 52 releases since 2016.

Those teams helped the project by contributing to our QA, questions, feature requests etc… and our way of thinking drove us to not let them down, and we decided to produce a backward compatible software.

The way we have been working until now aims to make our community move smoothly from TheHIve 3 to TheHive 4.

Backward compatibility

This is the most difficult challenge we have had, but we have hard heads and soft hearts.

TheHive 4 is expected to be backward compatible, thanks to APIs v0. Yes, we provide versioned APIs having the same endpoints as TheHive 3, and producing the same results. Search APIs also support the same query language, except some corner cases like searching using the “_string” operator (which is tightly coupled to Elasticsearch query language, but we have working alternatives).

Performance concerns

Supporting backward compatibility might force you to accept complex designs. And TheHive 4 RC3 was a clear example of that limitation.

Many kind users who tested TheHive 4 RC3, raised performance issues, slow UI problems etc… And it was completely expected. We thank them for making such a pressure on us, we used it to boost the refactoring of the UI, which was using backward compatible APIs (unoptimized for the new data model and representation), specially to read data (listing cases or observables for example).

We can discuss the technical details of this hard point later, but it mainly relates to navigating through graph-based data using a document based query system, which is not optimised.

For example, if you want to search for list of observable of a given case, the ideal way of doing that on a graph-base model is to:

  • Get the case by its ID, which is indexed (very fast operation)
  • Navigate through case relation, to find its links of type observable

But the backward compatible query language works differently: It scans all the graphs to search for observables that have a case parent with a given ID, which has a slower performance in a graph-based database.

Multi-tenancy and RBAC

TheHive 4 comes with a special multi-tenancy support. It allows the following strategies:

  • Use a siloed multi-tenancy: you can define many organisations, without allowing them to share data
  • Use a collaborative multi-tenancy: you can define a set of organizations and allow them to collaborate on specific cases/tasks/observables, using custom defined user profiles (RBAC)

This feature is very powerful but has a cost: an expected performance overhead. For example, when scanning the graph of data to search for a list of cases, TheHive must return the cases of your organisation and the case you can have access to because of the sharing rule.

New foundations

TheHive 3 was based on a framework called Elastic4play, written by Thomas to abstract all the routines required by a web application written with play 2 and using Elasticsearch.

TheHive 4 has its own core framework: Scalligraph, built to handle the following features.

Scalligraph will be the foundation of the next major version of Cortex.

What’s new in 4.0 

TheHive 4.0 release has a significant amount of changes. We will quickly explain the most important, and you can refer to the change logs if you need to have more details.

UI Performance

This was the most important task of this release. As we mentioned above, we were using backward compatible APIs in RC3 release, and migrated 80% of the UI to use the APIs v1 which are optimised for the new graph-based and multi-tenant data model.

OAuth2 Support

This topic gave birth to many github issues, some of them related to TheHive’s UI not correctly redirecting authenticated users. OAuth2 support has been tested with many providers like: Okta, Keycloak, FusionAuth, Microsoft Azure, Office 365 and Google Gsuite.

Starting from this version, there is an API endpoint that handle all the authentication and redirections: /api/ssoLogin

Here is a configuration sample for MS Office 365

{
  name: oauth2
  clientId: "CLIENT_ID"
  clientSecret: "CLIENT_SECRET"
  redirectUri: "http://THEHIVE_URL/api/ssoLogin"
  responseType: code
  grantType: "authorization_code"
  authorizationUrl: "https://login.microsoftonline.com/TENANT/oauth2/v2.0/authorize"
  authorizationHeader: "Bearer "
  tokenUrl: "https://login.microsoftonline.com/TENANT/oauth2/v2.0/token"
  userUrl: "https://graph.microsoft.com/v1.0/me"
  scope: ["User.Read"]
  userIdField: "mail" 
}

You can find more details about the OAuth2 support in the authentication config documentation

Improved Analyzer and Responder selection

Analyzer selection when calling bulk observable analysis has been improved to show the possible analyzers per observable type.

Analyzers selection during observable bulk analysis

For responders, the user experience has been improved as well, especially for instances with a big number of responders. The simple dropdown menu available to select responders has been replaced by a dialog allowing list filtering and scrolling:

New Responder selection dialog

Add bulk operations to case listing

Before this release, simple case updates required visiting the cases one by one and editing them. We added in this release a bulk edit feature, depending on user’s permissions on the selected cases

Bulk edit dialog, used here from case list

The same bulk editing component has been used to improve the same operations on observable list page.

Other noteworthy changes

We need to mention that the following changes have been included in TheHive 4.0 release:

  • Add pagination and filtering to users administration
  • Add back the UI configuration by organisation. The only available option is related to enabling/disabling the use of Empty Case.
  • Show sharing summary in task and observable lists
  • Improve alert preview dialog
  • Add alert externalLink feature allowing the display of external links for any alert, not only MISP alerts.

Known limitations

Even after 49 closed Github Issues, there are still major topics to be addressed by the upcoming releases:

  • Add back support to case merge which is not satisfying today. The challenge is to find the best to merge cases and make sure that it works in a profile-based multi-tenant design.
  • Add full text search support. In older versions, TheHive benefited from the full text search capabilities of Elasticsearch. With the new database and persistence system, full text support requires adding a dedicated indexing layer.

Installing and testing TheHive 4.0

After months of testing versions, this official release means that we consider it ready for production purposes. If you’re new with TheHive, we recommend going with TheHive 4.0.

Several installation guides have already been published, suitable with the chosen operating system and installation type, and new are coming.

For testing and training purposes, a virtual machine with a simple configuration of TheHive 4.0 and Cortex 3.0.1, is also published and available starting from now. Please refer to the documentation for download and usage instructions.

Want to upgrade from TheHive 3.x ?

All changes brought to TheHive make the upgrade more challenging than installing the new package and watch the progress bar. To support you with the upgrade, a migration tool comes along with the application to shift your current version of TheHive to TheHive 4.0.

A dedicated guide has been published to help users with this significant task. We recommend using a new server aside from your production server to ensure everything works fine with the migration.

Future of TheHive 3.x

This major outcome doesn’t mean TheHive 3 end of life is reached. As previously announced, we plan to support this version for some time, our next milestone being to support Elasticsearch 7.x with a first Release Candidate.

How to report issues

Please open an issue on GitHub using the template made for TheHive4 if you’d like to report a bug on this version. We will monitor those closely and respond accordingly.

TheHive4py got a second wind, version 1.7.0 released

“TheHive4py”, this sounds like a word you didn’t hear about during the last 12 months. Well, our focus on this library was put on hold. We will tell you the reason, but much better, we will solve the problem.

A brief review

TheHive4py was quickly initiated after the first releases of TheHive to help developers interact with TheHive APIs using python. We started creating methods and functions for main functionalities and to be honest, it was a sort of a quick-and-dirty solution.

TheHive4py has some limitation:

  • The API client is a flat class with dozens of methods
  • The API clients’ methods return the native `requests.Reponse` class instead of a structured data
  • Exception handling could be improved
  • Code could be made more reusable

As developers, we are aware of these limitations and are eager to provide a better library, and that’s what we started making with TheHive4py rewrite. We wanted to provide you with a library you can use this way:

# Fetch cases
open_cases = api.cases.find_all({'status': 'Open'}, range='0-5')
log('Open cases', list(map(lambda i: i.json(), open_cases)))

# Fetch a case by `id` or `number` (caseId)
sample_case = open_cases[0]
log('case details by id', api.cases.get_by_id(sample_case.id).json())
log('case details by number', api.cases.get_by_number(sample_case.caseId).json())

# Fetch alerts
new_alerts = api.alerts.find_all({'status': 'New'}, range='0-2')
log('New alerts', list(map(lambda i: i.json(), new_alerts)))

# Fetch observables
domain_observables = api.observables.find_all({'dataType': 'domain'}, range='0-2')
log('New alerts', list(map(lambda i: i.json(), domain_observables)))

# Fetch tasks
waiting_tasks = api.tasks.find_all({'status': 'Waiting'}, range='0-2')
log('Waiting tasks', list(map(lambda i: i.json(), waiting_tasks)))

waiting_tasks = api.tasks.get_waiting(range='0-2')
log('Waiting tasks', list(map(lambda i: i.json(), waiting_tasks)))

jdoe_tasks = api.tasks.get_by_user('jdoe', {}, range='0-3')
log('Tasks of jdoe', list(map(lambda i: i.json(), jdoe_tasks)))

case_tasks = api.tasks.of_case(sample_case.id, query={'status': 'Waiting'})
log('Case tasks', list(map(lambda i: i.json(), case_tasks)))

The library’s rewrite was supposed to produce a 2.0.0 version of TheHive4py but we had a major issue: backward compatibility.

Well, in theory, backward compatibility can be handled through a clear communication to:

  • tell the users how to make sure to update their dependencies to TheHive4py < 2.0.0
  • provide a migration plan
  • maintain both versions during a certain time
  • maintain documentation for old and new versions

To be honest, this was hard to achieve, because of the famous lack of time, but things a going to change.

What’s the plan?

We didn’t want to make a plan without asking the community about how they interact with TheHive APIs. So we did two twitter polls that ended up with the following results:

Twitter poll about TheHive API usage methods

The second poll asked our users about pros and cons of TheHive4py:

Twitter poll about TheHive4py pros and cons

The poll results are clear: we need to put more efforts on TheHive4py.

Here we go, firstly, let’s release version 1.7.0

TheHive4py 1.7.0 milestone has been initiated almost one year ago, and we are happy to announce its availability today.

What’s new about it?

The most important change is allowing TheHive4py to interact with TheHive 4 in addition to introducing some missing features, and bug fixes. Here is a short listing of main changes:

Add support to multi tenancy

Allow a developer to specify the organisation against which an API call is done:

api = TheHiveApi('http://my_thehive:9000', 'my_api_key', organisation='cert')

Add custom field support for new types:

TheHive 4 introduces custom fields of type integer and float, this feature allows specifying custom fields with types supported by TheHive 4. These types are not supported by TheHive 3.

CustomFieldHelper
   .add_integer('number_hits', 10)
   .add_float('cvss', 5.6)
   .build()

The code snippet above produces the following content:

{
  "number_hits": {
    "order": 0,
    "integer": 100
  },
  "cvss": {
    "order": 1,
    "integer": 5.6
  }
}

Add support to like and wildcard query operators

TheHive query DSL supports like and wildcard operators, but TheHive4py didn’t had an option to use those operators. In this version the following query methods have been added:

  • Like (field, value): Field’s value must contain value, that must contain `*` in the beginning or at the end
  • StratsWith (field, value): Field’s value must start with value
  • EndsWith (field, value): Field’s value must end with value
  • ContainsString (field, value): Field’s value must contain value
from thehive4py.query import Eq, Like, And, StartsWith

# find cases where title contains 'Dridex'
api.find_cases(query=Like('title', 'Dridex*'))

# find alerts where status is 'New' and title starts with 'Emotet'
api.find_alert(query=And(Eq('status', 'New'), StartsWith('title', 'Emotet')))

Add ioc and sighted attributes to case and alert artifacts

This allows specifying these attributes during Alert or Case observables creation

Add update_case_observable method

Can be used to patch an existing observable, by setting a tag or marking as IOC.

Add PAP to Case and CaseTemplate models

PAP flag has been added in TheHive recently and TheHive4py was not able to set the PAP value of a Case or CaseTemplate

Add custom fields creation method

Added a `create_custom_field` method that check custom field name uniqueness before creating it.

Note: This method is for now, compatible with TheHive 3 only because it relies on the DBList API that is no longer available on TheHive 4.

Add case template creation method

Added a `create_case_template` method allowing developers to create new Case Templates.

The full change log is available at the release page

What about documentation

Once again we are glad to announce the initial version of a documentation website, dedicated to TheHive4py, including documentation of all the features the library provides, and code samples of the most useful features.

We aim to maintain and improve this documentation over time, so please, don’t hesitate to either contribute or ask for more content.

Screenshot of the documentation website

TheHive4py 2.0

We will put the rewrite of TheHive4py on hold for now and will communicate about it again when we are ready. In the meantime, we will continue maintaining TheHive4py 1.x.

Update: TheHive4py 1.7.1 Patch

During the release 1.7.0, we have noticed that the build process and deployment went wrong, so we have created a 1.7.0.post1 release.

The community also raised a regression that has been fixed in 1.7.1 release. You can read the change log for more details.

Updating/Installing

To update your existing package to version 1.7.0:

$ sudo pip install thehive4py --upgrade

Got a question?

If 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!

TheHive 4.0-RC3, a new kid on the block

Three weeks ago, on May 6th, we announced the availability of TheHive 4.0 RC-2 release and the active community made the usual hard work of testing the release to find bugs and ask for enhancements.

Special thanks to Christopher, alias crackytsi who has already created 122 Github issues, 11 of them are just for 4.0-RC-3 milestone.

We are thrilled to present our third release candidate before the final release of TheHive 4. As the RC-2, this milestone brings new features and fixes a nice set of issues.

This blog post will focus on the following new features:

  • Multi-orgs users
  • Switch organisation
  • OAuth2
  • Migration tool performance
  • Case sharing overview

If you are curious about all the issues that have been addressed, you can read the full changelog

Multi-orgs users

This feature doesn’t introduce UI changes, but it allows a superadmin or an org-admin to add an existing user to an organisation.

Users in TheHive 4 are identified by their email addresses, so when an administrator adds a new user, with an email address that already exists, TheHive 4 links that existing user to the organisation being updated.

This ends up with a single User record on the database, linked to multiple organisations. Thanks to the new graph data model. This means the given user has:

  • the same credentials
  • the same api key, if enabled
  • the same 2FA settings, if enables
  • the same status (locked or not)

With that being said, the user can have a different profile for on the organisation (s)he belongs to.

What happens when a user is logged in?

As we mentioned earlier, a user belonging to several organisations, has the same authentication settings, and after the login, his/her workspace is opened with the context of the first organisation (s)he has been created on.

For example, if John was firstly created on the *SocLevel2* organisation, and was later attached to *CTI* organisation, then after signing in, the user is redirected to the workspace of *SocLevel2* organisation.

Future improvements

We will consider allowing the user to define a default organisation to be displayed juste after the login. We are examining the possibility to allow the user to define a default organisation to be displayed just after the login process. Hopefully, we will be able to add this feature in TheHive 4.0.0 release.

Switch organisation

This feature empowers the multi-tenancy capabilities brought to you by TheHive 4. Following what has been showcased above, how can a user, who belongs to more than one organisation, switch between his/her tenants?

The UI introduces a simple feature, available to “multi-org” users only, as a button on the right hand side of the page’s header, aka. the navigation bar.

The switch organisation action button

This button is just hidden for users who belong to a single organisation.

Once clicked, that button show a dialog that displays the following details:

  • user’s organisations
  • user’s profile on each organisation
  • the current organisation

Clicking on an item of this list, refreshes the page by loading the context of the selected organisation, and the UI behaves like if the user was logged in a a member of that selected organisation.

Very useful.

Switch organisation dialog

OAuth2

We had a considerable amount of users asking for SSO and OAuth support in TheHive. We tried to make it more robust in TheHive 4, and let it rely on a redirectUri provided by the backend (/api/ssoLogin) instead of the old redirectUri that some OAuth providers don’t support (index.html/#!/ssoLogin).

In TheHive 4.0 RC-2, OAuth 2 partially worked, and failed to redirect the user to the home page after the authentication success. Yes, sorry for that.

We spent some time testing the new implementation. We will devote some blog posts to it, but firstly, here is a working example relying on Keycloak

auth {
  providers: [
    {name: session}               # required !
    {name: basic, realm: thehive}
    {name: local}
    {name: key}    
    {
      ##############
      # Keycloak
      ##############
      name: oauth2
      clientId: "CLIENT_ID"
      clientSecret: "CLIENT_SECRET" # or empty
      redirectUri: "http://THEHIVE/api/ssoLogin"
      responseType: "code"
      grantType: "authorization_code"
      authorizationUrl: "http://KEYCLOAK/auth/realms/TENANT/protocol/openid-connect/auth"
      authorizationHeader: "Bearer"
      tokenUrl: "http://KEYCLOAK/auth/realms/TENANT/protocol/openid-connect/token"
      userUrl: "http://KEYCLOAK/auth/realms/TENANT/protocol/openid-connect/userinfo"
      scope: ["openid", "email"]
      userIdField: "email"
    }
  ]
}

After a question asked on Twitter, we tried to test our OAuth implementation with the providers mentioned in the answers, and we have successfully tested:

Migration tool performance

The migration tool we implemented in TheHive 4.0 RC-2 suffered from important performance issues as a result of our desire for a clean design.

In fact, enabling database locks during a parallelised and asynchronous processing of the migration operations produce a migration tool with poor performance.

We changed the strategy, by disabling locks and programmatically handling duplicates if they happen. This ended by a significant improvement of performance

We hope you can test it and provide us with your feedback.

Case sharing overview

Case sharing is the most important feature that the multi-tenancy support adds to TheHive. Allowing users to quickly spot if a case is owned or is coming from a share (made by another organisation) improves the user’s experience.

The other handy information is: the number of organisations having access to a certain case

Case list with sharing indicators

This screenshot shows all the case sharing related UI element:

  • The blue line, indicates that the case is coming from another organisation
  • The green line, indicates that the case is owned by the current organisation
  • The red line, highlights the column that show the number of organisation having access to the corresponding case

How to report issues

Please open an issue on GitHub using the template made for TheHive4 if you’d like to report a bug on this version. We will monitor those closely and respond accordingly.

New TheHive 3.4 Patch Releases

Last month (that should be… April… we are kinda losing track of time during the confinement), we made silently 2 patch releases for TheHive 3.4, our current stable version even if we have our hands full of soap and bleach as we are working on the eagerly awaited TheHive 4.0.0 final release: 3.4.1, shortly followed by 3.4.2. Your lovely bees are truly committed at keeping TheHive 3 branch buzzing well after 4.0.0 is out.

As usual, we’d like to start by thank the community for bringing the issues they discover to our attention. This is definitely one of the best contributions that we can get from you!

A simple way to help any open source project

3.4.1 Release

Released on April 25, 2020, 3.4.1 mainly fixed some docker-related issues as well as problems with OAuth2 and MISP integration, in addition to a few bugs, as described in the changelog.

Implemented Enhancements

  • Docker: TheHive fails to connect to Elasticsearch (NoNodeAvailableException) #854
  • Improved support for OpenID connect and OAuth2 #1110
  • TheHive’s Docker entrypoint logs the Play secret key at startup (… looking elsewhere hoping not to attract too much attention on this one) #1177
  • Configure TheHive’s first run using Docker Compose #1199
  • TheHive’s docker containers should be orchestration-ready #1204
  • MISP synchronisation: any attribute having the to_ids flag will be imported as ioc by TheHive. In the same way, when you export a case to MISP, observables which have the ioc flag on will become MISP attributes for which to_ids is true #1273

Closed Issues

  • Include Dockerfile in root of project #1222
  • Docker user daemon with id 1 causes permission issues with local #1227

Fixed Bugs

  • Fix MISP sync issues related to Docker #866
  • Owner is case-sensitive on API calls and should be lowercased #928
  • Bug: Observable without data breaks display of observables #1080
  • Docker-Compose Elasticsearch incompatibility #1140
  • Analyzers that take more than 10 minutes run into timeout #1156
  • TheHive 3.4.0 migration log errors ([error] m.Migration – Failed to create dashboard) #1202
  • Computed metrics are not compatible with the painless scripting language #1210
  • OAuth2 Bearer header should be of the format “Authorization Bearer” ? #1228
  • Health API endpoint returns warning when everything is OK #1233
  • Job submission sometimes fails when there are multiple Cortex servers #1272

3.4.2 Release

3.4.1 introduced a regression which was spotted few hours after it has been made public. 3.4.2 fixes t the problem.

It also adds a quick improvement allowing users to have access to error messages returned by Cortex Responder calls.

Display of a failed responder jobs, in case details page

Implemented Enhancements

  • Providing output details for Responders #962

Fixed Bugs

  • File observables in alert are not created in case #1292
  • Analyzer’s artifacts tags and message are not kept when importing observables #1285

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 as usual!

TheHive4py 1.6.0 Released

TheHive4py library, the Python API client of your favorite FOSS SIRP, TheHive, is being used more and more, for integration and automation. From a developer perspective, the current version is a simple flat class offering a set of methods to call some TheHive features and APIs.

A few months ago, we have started a big refactoring of the library to make it more consistent, testable, structured and maintainable. However this refactoring has introduced breaking changes (the refactoring branch has now been merged into develop branch).

refactor.png
NO FEAR, we won’t let you down

Important note: We are still working on making 2.0.0 ready for use, but in the meantime, we continue accepting the community contributions related to 1.x.

What’s new?

We will keep maintaining the 1.x (< 2.0.0) versions until end of 2019. Thus, we have moved the 1.x code base into its own git branch on Github and have made available a 1.6.0 release that includes the following features:

Updating/Installing

To update your existing package to version 1.6.0:

$ sudo pip install thehive4py --upgrade

Got a question?

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!