Tag: SSO

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.

Unveiling Cortex 2

TheHive Project’s Master Chefs are extremely happy to share, for free their latest recipe with the Cyber Threat Intelligence, Digital Forensics and Incident Response communities: Cortex 2.

As its predecessor, Cortex 2 is published under an AGPL v3 license and it introduces many important features that we brushed upon in a Dec 2017 post.

Screen Shot 2017-12-15 at 17.16.06
Cortex 2 — Architecture

Update: Cortex 2.0.1 was released since this post went live. It corrects a few bugs we uncovered in 2.0.0 as described in the changelog. Please install Cortex 2.0.1 instead of 2.0.0.

Authentication

Cortex 2 supports all the authentication methods that TheHive supports: LDAP, Active Directory, local accounts, API Keys, and X.509 SSO.

To connect your favorite Security Incident Response Platform with Cortex 2, you will need to update TheHive to Cerana 0.7 (TheHive 3.0.7) which was released today as well. This version fixes a regression pertaining to case templates introduced by Cerana 0.6 and is the first version to fully support Cortex 2’s API changes and authentication.

To make TheHive 3.0.7 analyze observables at scale through Cortex 2, you have to create an account on Cortex 2 with the read and analyze roles (see the next section) and generate the associated API Key. Next, feed the key in TheHive’s /etc/thehive/application.conf as described in the documentation et voilà !

TheHive 3.0.7 remains compatible with Cortex 1 and you can connect it to a mixed set of Cortex 1 and/or Cortex 2 instances with no issues.

Organizations, Analyzers and Rate Limiting

Cortex 2 introduces multi-tenancy through organizations and each organization can have its own set of users, with different roles, its own set of analyzers and, if necessary, rate limits that will prevent analysts from burning quotas.

Multi-tenancy has several interesting use cases. For instance, if you are the CSIRT or CERT of a large multinational organization with several regional teams, you can create an organization for each region within your constituency and enable the analyzers that they may need to use. Let’s assume that you bought a VirusTotal subscription that limits you to 5000 requests per month. You can configure the corresponding analyzers to give each region a fair share of that quota and keeping some requests for your own use.

In case you are a commercial CSIRT or an MSSP, you could do the same for your customers by installing only one Cortex 2 instance and creating an organization for each customer.

Screen Shot 2018-03-29 at 16.27.05.png
Configure an analyzer graphically and impose rate limits if necessary

User Roles

By default, Cortex 2 is shipped with the default cortex organization which sole purpose is to create other ones and manage the users within each organization and their associated powers. The cortex organization hosts all users with the superAdmin role and it cannot be used to configure or run analyzers.

As described in the new Quick Start Guide, after installing Cortex 2, updating its database and creating the first user who will have super admin powers, you’ll have to create your first organization and at least one user within that organization with orgAdmin rights.

Screen Shot 2018-03-29 at 16.33.02
Create an organization

You can then log out and log in using the orgAdmin account to create further users within that organization, enable and configure analyzers etc. Please note that no analyzer is enabled by default and you need at least v 1.9.0 of the cortex-analyzers repository. To update your set of analyzers to 1.9.0, please run git pull.

Screen Shot 2018-03-29 at 16.28.47
Manage users within an organization

Besides the superAdmin and orgAdmin roles, Cortex 2 introduces the read role which allows users to access analyzer reports and read them but not execute analyzers. For that, users need the analyze role (which implies the read role). orgAdmin users can also run analyzers. superAdmin users are limited to the default cortex organization. While they can create organizations and manage users within them, they cannot access analyzer configurations such as confidential API keys or job reports.

Screen Shot 2018-03-29 at 16.31.28
Job reports

Report Persistence and Caching

Cortex 2 relies on Elasticsearch 5.x to store many configuration items but also all the analyzer reports that have been generated. Unlike its predecessor, you won’t lose your existing reports should you need to restart the service or the host it is running on.

Cortex 2 also introduces report caching. By default the cache.job parameter is set to 10 minutes in /etc/cortex/application.conf. That means that if an analysis on a given observable with a defined TLP is requested and that a report has been previously generated in the last 10 minutes, Cortex 2 will serve that report instead of running a new analysis. This feature can help prevent soliciting analyzers, particularly those which require a subscription or have quotas, when there is no need to do so. Please note that this parameter is global to all the analyzers and all the organizations that are configured in the Cortex 2 instance. We do have plans to make it more granular in future versions.

Migrating from Cortex 1

If you are migrating from Cortex 1.x, we recommend that you:

  1. Save the configuration of your analyzers (which ones are enabled and what their configuration items are, such as users/passwords or API keys).
  2. Install Cortex 2.
  3. Edit /etc/cortex/application.conf to add the secret key as shown in Step 1 of the Quick Start Guide and point Cortex to the location of the analyzers.
  4. Follow the remaining steps of the Quick Start Guide to enable the analyzers you need and reinject their configuration.

What’s Next?

In the upcoming weeks, we will release a new version of Cortex4py in order to make it compatible with Cortex 2, continue the work we started with our MISP Project friends to support MISP attribute enrichment through Cortex 2 (MISP currently only supports enrichment using Cortex 1), and perform a long-overdue overhaul of our documentation.

Feeling Generous? Donate!

As you know, we are a FOSS project and donations are always welcome to make our products even better for the community.

All donations go to Creative Source, the non-profit organization we have created, and we will use them to improve TheHive, Cortex & Hippocampe but also to develop (even better) integrations with other FOSS solutions such as MISP.

So if you are feeling generous, please contact us at support@thehive-project.org.

Creative Source can also provide so-called professional, entreprise-grade support, help integrating the products, train your analysts before they drain or assist you in specific areas such as developing in-house analyzers for Cortex.

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.

Correction: March 30, 2018
Instructions on how to update the cortex-analyzers have been added. Also, Cortex 2.0.1 was released to correct a few bugs in the previous version since this post went live.