TheHive and Cortex Case Management Guide: Run Incident Cases and Observable Enrichment Safely

Incident teams that track cases in shared mailboxes and spreadsheets lose evidence, duplicate enrichment work and cannot show who did what, when. TheHive is a security incident response platform for SOCs, CSIRTs and CERTs, and Cortex is its companion engine for analysing observables and running response actions. This guide explains what each component does, how the licensing changed after StrangeBee took over development, how to deploy and harden the pair, and how to measure whether it is improving response. It is written for SOC leads, incident responders and platform engineers who run or are evaluating TheHive and Cortex. It goes deeper on the tool itself than the SOAR and Security Automation Guide, which covers automation strategy in general.

Key takeaways

• Two products, two licences: Cortex is open source under the AGPL and needs no licence; TheHive 5 and 6 are distributed commercially by StrangeBee, with a free Community licence that must be requested.
• TheHive 3 and 4 are gone: StrangeBee states they have not been maintained or publicly distributed since 2023, and the old GitHub repository was archived on 5 December 2025, so any remaining TheHive 4 instance is unsupported software.
• Cortex keys are privileged machine credentials: TheHive calls Cortex with an API key, and analyzers hold third-party API keys, so treat each as a non-human identity with an owner, scope and rotation date.
• Responders change production: a responder can block an IP at the proxy or email a user, so restrict who can run them and log every run as you would a change.
• Measure the case, not the tool: time to triage alerts, time to close, enrichment coverage and template use show whether the platform is working.

What the tool does

TheHive organises response work around cases. A case holds tasks (actions assigned to analysts to analyse, assess and mitigate), observables (data points such as IP addresses, file hashes, domains and email addresses), attachments and a timeline of activity, with live updates so several analysts can work the same case. Alerts arrive from sources such as SIEMs, email reports and threat intelligence providers, and an analyst creates a case from an alert, adds the alert to an existing case or closes it. Case and task templates with custom fields and metrics standardise how common incident types are worked, and TheHive will not close a case while a required custom field is empty. Cases and observables carry a severity and Traffic Light Protocol (TLP) and Permissible Actions Protocol (PAP) markings that tell analysts how far data may be shared and what actions are allowed on it.

Cortex analyses observables at scale. Analyzers take an observable (IP, domain, URL, email address, file or hash) and return a report, for example a reputation lookup or a sandbox result; most analyzers come in several flavours. Responders perform actions such as emailing a constituent, blocking an IP at a proxy or notifying team members, and TheHive can run them against alerts, cases, tasks and observables. Cortex caches results so the same observable is not re-analysed within a set period (10 minutes by default, adjustable per analyzer), and it can rate-limit analyzers so one job does not consume a whole third-party API quota.

Components and licensing at a glance

New on-premises or cloud installs of TheHive 5.3 and later start with a 14-day Platinum trial; after that, the platform drops to read-only mode until a licence is applied. Upgrading an existing 5.x Community install to 5.3 or later also requires requesting a Community licence, or the interface becomes read-only. Plan the licence request before any upgrade window. StrangeBee counts only unlocked Normal user accounts with at least one licensed permission against the user quota; service accounts and read-only or admin-only accounts do not count, and there are separate quotas for organisations, Cortex servers and MISP servers.

Defender use cases

• SIEM alert triage: forward SIEM detections into TheHive as alerts, deduplicate, and promote only confirmed activity to cases. This keeps the SIEM for detection and TheHive for the work record. See the SIEM Guide.
• Phishing reports: user-reported emails become alerts; Cortex extracts and analyses URLs, attachments and sender domains; responders can notify the reporter or block a domain.
• Threat intelligence round trip: import MISP events as alerts, work them as cases, and push confirmed indicators back to MISP for sharing. Cortex and MISP integrate in both directions: Cortex can call MISP modules and MISP can call Cortex analyzers. See the MISP Threat Sharing Guide.
• Multi-team and MSSP work: organisations in TheHive separate teams or customers, and sharing rules define partner organisations, which elements are shared (observables and tasks) and at what permission level.
• Evidence handling: attachments and password-protected ZIP import let analysts keep malware samples and exports inside the case rather than in email.
• Identity incidents: case templates for leaked API keys, compromised service accounts or OAuth app abuse give responders a consistent task list (revoke, rotate, scope review, log search). See the Identity Incident Response Playbook.

Deployment and safe use

TheHive stores data in Apache Cassandra, indexes it in Elasticsearch (Lucene indexing is no longer supported from 5.1), and stores files on the local filesystem for a standalone server or on NFS or S3-compatible object storage for a cluster. A standalone server runs every component on one host, optionally with Nginx in front for HTTPS termination; a cluster deploys each layer independently, and StrangeBee documents a three-node design.

Supported software versions (from StrangeBee documentation)

Cortex 4.x requires Elasticsearch 8.x, audit log storage needs Elasticsearch 7.17 or later, and StrangeBee does not recommend sharing one Elasticsearch instance between TheHive and Cortex. OpenSearch is supported for recent versions except for audit log storage. Supported operating systems include Ubuntu 20.04, 22.04 and 24.04 LTS, Debian 11 to 13, RHEL 8.5 and 9.3 and Rocky Linux 9.4. For a single host, StrangeBee sizes each of TheHive, Cassandra and Elasticsearch at 3 CPU cores and 4 GB RAM for fewer than 10 concurrent users, rising to 4 to 6 cores and 8 GB for fewer than 50, with 100 to 150 GB of storage. Set JVM heap sizes explicitly and disable swap on the Elasticsearch host or set bootstrap.memory_lock: true.

Phased rollout

1. Decide the edition first: list required features (clustering, number of Cortex and MISP servers, organisations, users) against the licence tiers, and request the Community licence or a quote before installing.
2. Build a test instance: deploy with Docker Compose (StrangeBee's testing profile is 8 GB RAM and 4 vCPUs) and load a sample of last quarter's alerts.
3. Design organisations, profiles and templates: one organisation per team or customer, permission profiles per role, and case templates for your five most common incident types.
4. Connect Cortex with a dedicated key: create a Cortex user in a non-default organisation with the analyze role only, issue its API key to TheHive, and enable a small set of analyzers.
5. Pilot with one shift: run TheHive alongside the existing process for two to four weeks, compare case records, then cut over by alert source.
6. Enable responders last: start with notification responders, then containment ones once approval and logging are proven.
7. Roll back cleanly: keep the previous tracker read-only until the pilot ends, and snapshot Cassandra, Elasticsearch and file storage before every upgrade so a failed upgrade can be restored.

Cortex roles and analyzer execution

Analyzers and responders run either as Docker images (Cortex needs Docker permissions and internet access to hub.docker.com and the StrangeBee catalogues) or as host programs cloned from the Cortex-Analyzers repository. The catalogue URLs and local directories are set with analyzer.urls and responder.urls in /etc/cortex/application.conf, and concurrency with thread-pool-executor.fixed-pool-size from Cortex 4.1. Docker execution isolates each analyzer's dependencies; pin the catalogue or mirror the images internally so a change upstream does not silently alter what runs in your SOC.

Detection and hardening value

The platform holds your most sensitive security data: indicators, victim names, credentials found in investigations and third-party API keys. Harden it like a privileged system.

• Network exposure: publish TheHive only through the HTTPS reverse proxy, keep Cassandra, Elasticsearch and Cortex on a management network, and allow Cortex outbound only to the analyzer services it uses.
• Analyzer data leakage: an analyzer that submits a file or URL to a public service discloses it. Use TLP and PAP markings consistently and restrict analyzers that send data externally to observables marked for sharing; check each analyzer's documentation for what it uploads.
• Machine credentials: the TheHive-to-Cortex key, SIEM and MISP integration accounts and every analyzer's third-party key belong in your NHI inventory, ideally loaded from a secrets manager, rotated on a schedule and on staff departure. See the API Key Management Guide.
• Responder governance: limit responder use to named profiles, require a task or case reference, and review responder runs weekly.
• Audit trail: keep the audit log (Elasticsearch 7.17 or later), forward platform and reverse proxy logs to your SIEM, and alert on new admin users, API key creation, organisation sharing rule changes and bulk exports.
• Datastore security: enable authentication and TLS on Cassandra and Elasticsearch; an open search cluster exposes every case. See the Elasticsearch and OpenSearch Security Guide.

Metrics that show it is working

• Alert triage time: median time from alert creation to case promotion or closure, per source.
• Time to close: median case duration by severity and template.
• Enrichment coverage: percentage of case observables with at least one analyzer report.
• Template adoption: percentage of cases created from a template.
• Credential hygiene: integration and analyzer keys older than the rotation period (target zero).

Framework mapping

Common failure patterns

• Running TheHive 4 after end of distribution: no fixes are coming, and the packages are no longer downloadable for a rebuild.
• Upgrading without a licence: a 5.x Community instance upgraded to 5.3 or later without a requested licence becomes read-only during an incident.
• One superAdmin key for everything: giving TheHive a superAdmin Cortex key means a stolen key can reconfigure every organisation.
• Public analyzers on internal data: uploading a confidential document to a public sandbox can tip off an attacker or breach confidentiality.
• Alert flood: forwarding every SIEM event as an alert turns TheHive into a second, slower SIEM; filter at the source.

Alternatives

Small teams can run a single-host Community instance with a handful of analyzers. Large SOCs and MSSPs should budget for clustering, separate Elasticsearch instances for TheHive and Cortex, and a licence tier that matches their organisation and server counts.

Practitioner checklist

• Confirm no TheHive 3 or 4 instances remain, and plan migration for any that do.
• Match licence tier to required users, organisations, Cortex and MISP servers before upgrading.
• Check Java, Cassandra and Elasticsearch versions against StrangeBee's compatibility table.
• Issue TheHive a Cortex account with the analyze role in a non-default organisation.
• Register every integration and analyzer API key as an NHI with owner and rotation date.
• Review which analyzers send data to external services and restrict them by TLP and PAP.
• Restrict and log responder runs; review them weekly.
• Forward audit and proxy logs to the SIEM and alert on admin and key changes.
• Snapshot all datastores before upgrades and test a restore.

Standards and references

• StrangeBee: TheHive Documentation Overview
• StrangeBee: About TheHive Licenses
• StrangeBee: TheHive Software Requirements
• StrangeBee: Cortex Documentation
• StrangeBee: Cortex Analyzers and Responders Configuration
• TheHive Project: TheHive repository and end of public distribution notice
• NIST: Cybersecurity Framework 2.0
• NIST: SP 800-53 Rev. 5

Related NHI Mgmt Group resources: SOAR and Security Automation Guide · MISP Threat Sharing Guide · Incident Response Guide · Open Source SIEM and Detection Tools Landscape Guide