How to Use TheHive: A Beginner's Guide to Security Incident Response
CodexFuse Team · 2026-11-01T20:29:26.157Z · 16 min read min read
Learn how to use TheHive for security incident response: install with Docker Compose, triage alerts into cases, enrich observables with Cortex analyzers, and connect MISP.
Learning how to use TheHive means learning how a security team actually works an incident — and this thehive tutorial teaches exactly that: alerts land, somebody triages them, the worthy ones become cases, evidence gets collected as observables, and the case closes with a trail anyone can audit. This guide walks that whole arc on the current release — TheHive 6 — from a Docker install to your first case, your first observable analysis, and the Cortex connection that makes enrichment automatic.
One clarification before we start: this guide is about TheHive, the security incident response platform built by StrangeBee. It is not about Apache Hive, the Hadoop data-warehouse tool — they share a name and nothing else, and the Hadoop tutorials that pollute this keyword's search results will not help you here.
What Is TheHive, Exactly?
TheHive is a security incident response platform: the shared case file where a SOC team tracks everything between "we got an alert" and "the incident is closed." Detection tools (Wazuh, Suricata, MISP) feed it alerts; analysts promote the important alerts into cases; every IP, domain, and file hash in the case becomes an observable that links related cases together; and analyzers (via Cortex) automatically enrich those observables with threat-intelligence data. In practice, thehive case management boils down to one loop — alert in, triage, case open, evidence collected, case closed — repeated with discipline.
Get TheHive Running in 5 Steps
- Clone the official deploy repo:
git clone https://github.com/StrangeBeeCorp/docker.git— this is the only compose path the vendor documents for on-prem installs. - Pick the production profile:
cd docker/prod1-thehive(standard single-server) and runbash ./scripts/init.shto generate secrets, the Elasticsearch password, and a self-signed certificate. - Start the stack:
docker compose up -dbrings up Cassandra, Elasticsearch, TheHive itself, and an Nginx HTTPS proxy. - Log in and lock the door: open TheHive's address, sign in as
[email protected]/secret, and change that password immediately. - Create your own organization: never work in the default Admin organization — make a real org and start triaging there.
The Mental Model: TheHive Is the Incident Folder, Not the Alarm
The fastest way to misunderstand TheHive is to expect it to detect attacks. It detects nothing. Wazuh is the alarm — it watches endpoints and fires alerts. TheHive is the incident folder those alerts land in — the place where humans decide what is real, investigate it, assign work, and close it out. Hold that line and everything else in the product makes sense.
If you are new to containerized self-hosting, read our Docker beginner guide first — TheHive's official install is a Docker Compose stack, and the mental model of "one compose project = one application" will carry you through the whole setup.
Install TheHive With Docker Compose
The official thehive docker path is the StrangeBeeCorp/docker repository, which ships two production profiles: prod1-thehive for a standard single server and prod2-thehive for a higher-performance single server. The stack has four parts: Cassandra stores the data, Elasticsearch indexes it, TheHive is the application itself, and Nginx terminates HTTPS in front of it.
Prerequisites are Docker Engine v23.0.15 or newer, the Compose plugin v2.20.2 or newer, and jq. The install then looks like this:
git clone https://github.com/StrangeBeeCorp/docker.git
cd docker/prod1-thehive
bash ./scripts/init.sh
docker compose up -dThe init.sh script generates secret.conf, a random Elasticsearch password, your .env file, and a self-signed Nginx certificate. Verify the stack is healthy after the pull finishes:
docker compose ps
docker compose logs thehive --tail 30Two traps to avoid: the old community guides still reference thehiveproject/thehive Docker images and Elasticsearch 5-era compose files — those are TheHive 3/4-era artifacts and do not apply to TheHive 5 or 6. And pin the image tag you actually want: strangebee/thehive:6.0 tracks the latest 6.0.x, while the floating 5 tag tracks the latest 5.x.
First Login: Change the Default Password Immediately
TheHive's on-prem first login is [email protected] with the password secret. The vendor's own docs flag this as a critical security risk: leaving default credentials in place is an invitation, so the first click after "Let me in" should be a password change.
A fresh install auto-activates a 14-day Platinum trial (up to 2 organizations and 5 users). When the trial ends, TheHive drops into read-only mode until you activate a license — the free Community license (2 users, non-commercial use) is the homelab path. Plan for that cliff before your trial expires; a read-only case manager in the middle of an investigation is nobody's idea of fun.
Create Your Organization: Cases Live Inside Orgs
Everything in TheHive — cases, alerts, tasks, users — lives inside an organization. Think of orgs as tenants: a division, a business unit, or your homelab. The default Admin organization exists so administrators can manage global configuration (users, orgs, entities); it is not where you work cases. Create your own organization and do all real work there.
Orgs are isolated from each other by default; sharing data between them requires explicit linking. User profiles control who can do what: Admin, Org-Admin, Analyst, and Read-Only are the built-ins, and read-only users do not consume a license seat. Creating and locking orgs requires an admin-type profile with the manageOrganisation permission — on a fresh install, that is you.
Where Do Alerts Come From? (You Cannot Create One by Hand)
An alert in TheHive is an event generated by a detection tool — your SIEM, IDS, EDR, firewall, or a threat-intel platform like MISP. Here is the rule to say once and never forget: manual alert creation is impossible. Alerts must originate from external tools connected to TheHive; the platform is a triage desk, not a data-entry form.
Each alert is uniquely identified by its type + source + source reference triple, and TheHive enforces that uniqueness inside your org — re-imports of the same event get rejected, which is what stops a noisy integration from creating ten copies of one intrusion. The classic beginner integration is Wazuh: its official blog documents feeding Wazuh alerts into TheHive over the REST API, and those alerts land in the Alerts tab ready for triage.
Promote Your First Alert to a Case: The Three Triage Outcomes
Triage is the job the whole product exists to support. When an alert arrives, you have exactly three moves:
| Outcome | What it means | When to use it |
|---|---|---|
| Create a case from the alert | The alert becomes a case and stays linked to it | Something needs real investigation |
| Add to an existing case | The alert joins a case already in progress | It is part of an incident you are already working |
| Close the alert | The alert is dismissed, not escalated | False positive, duplicate, or noise |
A case carries a title, description, severity, TLP/PAP marking, tags, and an assignee, and moves through workflow states like New, In Progress, and Closed. The alert→case link stays visible forever, so the trail from "what fired" to "what we did" survives the investigation — that is the auditability auditors actually ask for.
Observables: The Evidence That Connects Your Cases
TheHive observables are the data points of an investigation: IP addresses, domains, FQDNs, URLs, file hashes, filenames, emails, registry keys — anything you can directly observe in the incident. Adding them to a case does two jobs at once: it records the evidence, and it powers correlation. TheHive matches observable values across your org and surfaces Similar alerts and Similar cases tabs, so a hash from last week's phishing case lights up when it appears in today's.
Two flags make observables smarter. Marking one as an IOC says "this is malicious infrastructure." Marking one as sighted says "we have seen this in our environment." The observables list then shows a color marker per value: grey means never seen elsewhere, red means seen elsewhere with at least one IOC marking, and blue means seen elsewhere with no IOC marking. Exclude noisy values (like your own company's domain) from similarity checks, or every case will look related to every other case.
If you run the stack on your own hardware, our VPS hosting guide covers the server-side basics — TheHive's Cassandra + Elasticsearch stack is happiest on a machine with real RAM to spare.
Run an Analyzer on an Observable: Let Cortex Do the Enrichment
TheHive analyzers are programs that take an observable plus configuration and return a verdict: given this hash, what does VirusTotal say? Given this domain, what does your MISP instance know? From a case, you select an observable, run an analyzer, and review the report — and reports can yield new observables, which you can import back into the case. That enrichment loop is the daily rhythm of working in TheHive.
Analyzers come with flavors — service-interaction profiles that declare the accepted data types, a TLP/PAP ceiling above which the analyzer refuses to run (an OPSEC guard so you never submit your company's crown-jewel sample to a public sandbox), and the configuration items like API keys. Analyzer configs are set per organization: an org admin enables the analyzer and fills in the keys. Common first analyzers are VirusTotal_GetReport (files, hashes, domains, IPs), the MISP search analyzer, and MalwareBazaar.
The Cortex Rule: It Is a Separate Service, Not a TheHive Tab
This is the architectural fact beginners get wrong most often, so say it once and keep it: Cortex is a separate application — its own organizations, users, web UI, API, and Elasticsearch 8 index — that TheHive calls over the network. It is the enrichment and response engine beside TheHive, not a tab inside it. Once the thehive cortex connector is configured, analyzers and responders appear wherever observables and cases appear — that one connection unlocks most of the product's power.
TheHive authenticates to Cortex with a bearer API key, configured in TheHive under Platform Management → Connectors → Cortex (server name, URL such as http://<server>:9001, bearer auth with the key — then test the connection). Cortex runs its analyzers and responders as Docker containers, so it needs access to a Docker socket. Version pairing matters: Cortex 4.0 (November 2025) moved to Elasticsearch 8, and TheHive 5.5+ no longer supports Cortex 3.1.5 or earlier — pair current with current.
Beyond analyzers, Cortex provides responders: actions TheHive can trigger on alerts, cases, tasks, and observables — send an email to constituents, block an IP at the proxy, notify the team. Analyzers answer questions; responders do things.
Tasks, Templates, and Teamwork
Each case breaks into tasks — identification, containment, eradication, "check the proxy logs" — and each task can be assigned to an analyst or picked up by anyone on the team. Tasks carry work logs where analysts narrate what they did and attach evidence, with rich-text or Markdown formatting. That is what makes a TheHive case readable months later: the evidence, the reasoning, and the actions are all in one place.
Case templates turn repeatable work into one click. A template pre-fills a new case's fields and tasks — phishing triage, malware analysis, whatever your team does weekly — and since 5.1 you can even apply a template to a running case to stack its tasks on top. Templates are manageable with the manageCaseTemplate permission, exportable across instances, and StrangeBee ships a set of 18 InterCERT-France playbook templates for the most common attack types. If you template nothing else, template the workflow you do most often; consistency is the whole point.
Connect MISP: Import Events, Export IOCs
The TheHive MISP integration is the bridge between your private cases and the threat-intel community. The MISP connector is enabled by default in TheHive: you connect your MISP instance, then import MISP events as alerts or cases (with a preview before importing), and export the observables you have marked as IOCs back to MISP as a new event. The mapping is clean — MISP attributes flagged to_ids arrive as IOC observables, and your IOC-flagged observables leave as to_ids attributes.
The connector also imports MISP taxonomies by default, so classification labels (TLP, incident types, confidence) are available from day one. If you are choosing between intake sources, MISP is the intel feed while Wazuh is the alarm feed — TheHive happily consumes both at once.
TheHive vs Wazuh vs Nuclei vs Shuffle: What Each Tool Actually Does
TheHive vs Wazuh is the comparison beginners ask about most, and the answer is a layer diagram, not a winner: Wazuh watches endpoints and generates alerts; TheHive manages the investigations those alerts become. They are complementary — the official Wazuh integration guide literally wires one into the other.
| Tool | Its job | Open source? | How it relates to TheHive |
|---|---|---|---|
| TheHive | Security case management: triage alerts, investigate cases | Commercial (Community license free, 2 users) | The hub — everything else feeds it |
| Wazuh | SIEM + XDR: watches endpoints, correlates logs, fires alerts | Yes, open source | The alarm — feeds alerts into TheHive |
| Nuclei | Vulnerability scanning with YAML templates | Yes, MIT licensed | A finding generator — scan results can become alerts/cases |
| Shuffle | SOAR: visual automation workflows across tools | Yes, open source | Orchestration-first; often sits beside TheHive's investigation-first workflow |
| Cortex | Observable enrichment (analyzers) + actions (responders) | Yes, AGPL | Not an alternative — TheHive's enrichment engine |
7 Beginner Mistakes That Break a TheHive Install
| # | Mistake | What to do instead |
|---|---|---|
| 1 | Working cases in the default Admin organization | Create your own org; Admin is for platform management only |
| 2 | Leaving [email protected] / secret in place | Change the default password on first login — the docs call this a critical risk |
| 3 | Trying to type an alert in by hand | Connect a real source (Wazuh, MISP); manual alert creation does not exist |
| 4 | Installing Cortex as if it were a TheHive plugin | Deploy Cortex as its own service and connect it with a bearer API key |
| 5 | Pairing TheHive 5.5+ with an old Cortex | Use Cortex 4.x (Elasticsearch 8); Cortex 3.1.5 and earlier are unsupported |
| 6 | Following a 2021 compose guide | Use the current StrangeBeeCorp/docker repo — old guides are TheHive 4-era |
| 7 | Ignoring the 14-day trial clock | Get a Community or paid license before the trial lapses into read-only mode |
TheHive 5, TheHive 6, and the License Question
If you came here looking for an open source SOC case management platform, here is the honest version: current TheHive is not open source. TheHive 3 and 4 were AGPL, but public access to them ended in July 2025. TheHive 5 (2021) and TheHive 6 (October 2026) are commercial annual subscriptions starting at €26,000, in Gold, Platinum, and ONE editions — ONE adds TheHive Flow, the native low-code orchestration engine with its new Automation tab.
The free paths are real, though: every install starts with a 14-day Platinum trial, a Community license covers 2 users for non-commercial use, and Cortex — the analyzer/responder engine — stays AGPL and free. For homelabs and students, TheHive Community + Cortex is the working combination.
Once the stack is running, keeping an eye on it matters: our Uptime Kuma beginner guide shows how to monitor services like TheHive and Cortex, and if you expose the instance beyond your LAN, our Caddy beginner guide covers putting it behind a proper domain with automatic HTTPS.
Sources
- StrangeBee announcement archive (TheHive 6, 5.8, 5.7 releases; InterCERT templates) — https://strangebee.com/blog/category/announcement/
- TheHive pricing (Gold/Platinum/ONE editions, €26,000 starting price, Community license) — https://strangebee.com/thehive-pricing/
- Deploy TheHive with Docker Compose (prod1/prod2 profiles, init.sh, stack components, prereqs) — https://docs.strangebee.com/thehive/installation/docker/
- Perform initial setup as admin ([email protected]/secret, 14-day Platinum trial, read-only mode) — https://docs.strangebee.com/thehive/administration/perform-initial-setup-as-admin/
- About organizations (tenancy, Admin org, linking, license limits) — https://docs.strangebee.com/thehive/administration/organizations/about-organizations/
- About profiles (Admin/Org-Admin/Analyst/Read-Only, license seats) — https://docs.strangebee.com/thehive/administration/profiles/
- About alerts (external-only origin, type+source+ref uniqueness, three triage outcomes) — https://docs.strangebee.com/thehive/user-guides/analyst-corner/alerts/about-alerts/
- About observables (types, IOC/sighted flags, similarity matching, grey/red/blue markers) — https://docs.strangebee.com/thehive/user-guides/analyst-corner/cases/cases-description/observables/
- Cortex docs home (separate service, responders, AGPL free) — https://docs.strangebee.com/cortex/
- Run Cortex with Docker (Docker socket, image thehiveproject/cortex) — https://docs.strangebee.com/cortex/installation-and-configuration/run-cortex-with-docker/
- Cortex authentication (bearer API key from TheHive) — https://docs.strangebee.com/cortex/installation-and-configuration/authentication/
- How to create a Cortex analyzer (program + flavors + TLP/PAP ceiling) — https://thehive-project.github.io/Cortex-Analyzers/dev_guides/how-to-create-an-analyzer/
- About case templates (apply to running cases since 5.1, manageCaseTemplate) — https://docs.strangebee.com/thehive/user-guides/organization/configure-organization/manage-templates/case-templates/about-case-templates/
- TheHive 5.1 release (Apply Case Template feature) — https://strangebee.com/blog/thehive-5-1-new-features/
- Release notes 5.4 (API v0 deprecation, /api/v1) — https://docs.strangebee.com/thehive/release-notes/release-notes-5.4/
- Using Wazuh and TheHive for threat protection and incident response (official integration) — https://wazuh.com/blog/using-wazuh-and-thehive-for-threat-protection-and-incident-response/
- Automation Series Part 3: Setting up TheHive (install + API arc) — https://ohlinger.co/posts/automation-series-part-3/
- TheHive + n8n integration guide — https://osher.com.au/tools/thehive/
- How to install TheHive on Linux (Cortex first-login screen) — https://letsdefend.io/blog/how-to-install-thehive-on-linux
- SOC homelab: TheHive, Cortex, MISP walkthrough (connector config path) — https://architvats96.medium.com/soc-homelab-part-4-thehive-cortex-misp-d24e05bb1b18
- TheHive Project THM room notes (analyzer templates per org) — https://basmala-yasser.medium.com/thehive-project-thm-ccc5070899e0
- Legacy TheHive announcement archive (responders/analyzers, 3/4 end of public access) — http://blog.thehive-project.org/category/announcement/
- Open-source SOAR comparison (Wazuh, Shuffle, Cortex licensing context) — https://aimultiple.com/open-source-soar
- Open-source SOAR tools (Shuffle's TheHive/MISP/Wazuh integrations) — https://heimdalsecurity.com/blog/open-source-soar-tools/
- ProjectDiscovery open-source page (Nuclei, template counts) — https://Projectdiscovery.io/open-source
- The ultimate beginner's guide to Nuclei — https://www.bugcrowd.com/blog/the-ultimate-beginners-guide-to-nuclei/
- SOAR platforms overview (Shuffle orchestration-first positioning) — https://theknowledgeengineers.com/software-advice/soar-platforms
Frequently Asked Questions
Is TheHive free to use?
Partly. Every install starts with a 14-day Platinum trial. For ongoing free use, StrangeBee offers a Community license for up to 2 users for non-commercial purposes (students, researchers, homelabs). Production use requires a paid subscription starting at €26,000 per year. Cortex, the analyzer engine, stays AGPL and free.
Can I create alerts manually in TheHive?
No. Alerts must originate from external tools connected to TheHive — a SIEM like Wazuh, an IDS, an EDR, or a threat-intel platform like MISP. TheHive is a triage and investigation desk; if you need test data, send it through an integration or the API, not a form.
Do I need Cortex to use TheHive?
Not strictly, but you will want it. Without Cortex you can triage alerts, manage cases, and track observables manually. With Cortex you get one-click analyzers (VirusTotal, MISP, MalwareBazaar) and responders (block an IP, notify the team). Cortex is a separate service you deploy alongside TheHive and connect with a bearer API key.
What is the difference between TheHive and Wazuh?
Wazuh is a SIEM/XDR that watches your endpoints and infrastructure and fires alerts when something looks wrong. TheHive is the case-management layer where analysts investigate those alerts. The canonical setup feeds Wazuh alerts into TheHive over the REST API — alarm and incident folder, two different jobs.
What version of TheHive should a beginner install?
Install the current major release — TheHive 6 (October 2026) via the official StrangeBeeCorp/docker compose repo, which pulls strangebee/thehive:6.0. Avoid older third-party compose guides: most describe the TheHive 4-era stack (old image names, Elasticsearch 5/7 layouts) that no longer applies.
