TheHive Case Management
TheHive and Cortex for open-source IR case management — setting up cases, managing observables, running Cortex analyzers, and integrating TheHive into a broader IR workflow.
Your SOC has been tracking incidents in a shared Google Doc. Every incident is formatted differently, evidence is scattered across personal drives, and there's no way to search across past incidents for similar IOCs. TheHive is the most widely deployed open-source IR case management system — it provides a structured incident record, IOC management, task tracking, and through Cortex, automated enrichment. This chapter explains how to use it effectively in a real incident, not just how to install it.
TheHive Case Structure
TheHive Case Anatomy
═══════════════════════════════════════════════════════════════════
Case
├── Metadata: title, severity (1-4), TLP, PAP, tags, status
├── Summary: free-text incident summary and timeline notes
├── Tasks: work items with assignees and status
│ ├── Task 1: Initial triage (In Progress, Analyst A)
│ ├── Task 2: Scope determination (Waiting, Analyst B)
│ └── Task 3: Containment (To Do)
├── Observables: IOCs extracted from the incident
│ ├── IP: 185.220.101.47 (TLP:RED) — can run Cortex analyzers
│ ├── Domain: evil-c2-domain.com
│ ├── Hash: sha256:abc123...
│ └── Email: attacker@evil.com
└── Cortex Jobs: enrichment results attached to observables
├── VirusTotal_GetReport: 47/70 engines flagged IP
└── AbuseIPDB_Checker: reported 23 times, confidence 95%
TheHive API Integration
TheHive's REST API lets you create cases programmatically from SIEM alerts, EDR detections, or any other alert source. This is the integration point that makes TheHive useful as a coordination platform rather than just a manual case entry system.
"""
Create a TheHive case from a structured alert.
Requires: pip install thehive4py
"""
from thehive4py.api import TheHiveApi
from thehive4py.models import Case, CaseObservable, CaseTask
# Initialize connection
api = TheHiveApi(
url="https://thehive.corp.local",
apiKey="YOUR_THEHIVE_API_KEY"
)
def create_incident_case(
title: str,
severity: int, # 1=Low, 2=Medium, 3=High, 4=Critical
description: str,
iocs: list[dict], # [{"dataType": "ip", "data": "1.2.3.4"}, ...]
tasks: list[str]
) -> str:
"""Create a case with observables and tasks. Returns case ID."""
# Create the case
case = Case(
title=title,
severity=severity,
description=description,
tlp=2, # TLP:AMBER
pap=2, # PAP:AMBER
tags=["automated", "ir"]
)
response = api.create_case(case)
case_id = response.json()["id"]
# Add observables (IOCs)
for ioc in iocs:
observable = CaseObservable(
dataType=ioc["dataType"], # "ip", "domain", "hash", "url", "email"
data=ioc["data"],
tlp=2,
ioc=True,
tags=["auto-imported"]
)
api.create_case_observable(case_id, observable)
# Add tasks
for task_title in tasks:
task = CaseTask(title=task_title, status="Waiting")
api.create_case_task(case_id, task)
return case_id
# Example: create case from a CrowdStrike alert
case_id = create_incident_case(
title="CrowdStrike: Cobalt Strike Beacon — LAPTOP-JSMITH",
severity=3,
description="CrowdStrike detected Cobalt Strike beacon activity on LAPTOP-JSMITH at 03:12 UTC. Process: powershell.exe → svchost.exe. C2 contact to 185.220.101.47:443.",
iocs=[
{"dataType": "ip", "data": "185.220.101.47"},
{"dataType": "domain", "data": "evil-c2-domain.com"},
{"dataType": "hash", "data": "sha256:a1b2c3d4e5f6..."}
],
tasks=[
"Initial triage — confirm beacon",
"Scope determination — check for lateral movement",
"Containment — EDR isolation",
"Evidence collection",
"Persistence hunt"
]
)
print(f"Case created: {case_id}")Cortex Analyzer Integration
Cortex runs analysis jobs against observables. Configure the analyzers you use most and set up auto-analysis on case creation.
"""Trigger Cortex analyzers on a TheHive observable."""
from thehive4py.api import TheHiveApi
api = TheHiveApi(
url="https://thehive.corp.local",
apiKey="YOUR_THEHIVE_API_KEY"
)
def run_analyzers_on_observable(case_id: str, observable_id: str):
"""Run all applicable Cortex analyzers on an observable."""
# List available analyzers
analyzers = api.get_analyzers(data_type="ip")
preferred = [
"VirusTotal_GetReport_3_0",
"AbuseIPDB_1_0",
"Shodan_DNSResolve_1_0",
"OTXQuery_2_0"
]
for analyzer in analyzers.json():
if analyzer["name"] in preferred:
result = api.run_analyzer(
cortex_id="cortex-main",
observable_id=observable_id,
analyzer_id=analyzer["id"]
)
print(f"Started: {analyzer['name']} — job ID: {result.json()['id']}")
# Run immediately after creating observables in a new case
run_analyzers_on_observable("~12345", "~67890")Case Templates for Common Incident Types
TheHive supports case templates that pre-populate tasks, tags, and severity for common incident types. Create a template for each playbook in Part 5 so new cases start with the right task list pre-built.
| Incident type | Template pre-filled tasks |
|---|---|
| Ransomware | Confirm ransomware → P1 declaration → Insurer notification → Scope → Simultaneous containment → Persistence hunt → Backup assessment → Recovery planning |
| Phishing / credential harvest | Triage reported email → Extract IOCs → Scope (who else received it?) → Confirm credential capture? → Session revoke + password reset → Email purge → Scope endpoint |
| BEC | Confirm fraudulent transfer → Bank fraud contact → FBI IC3 filing → Mailbox audit → Inbox rule hunt → OAuth app audit → Containment |
| Web shell | Locate shells → Log analysis → Lateral movement check → Remove shells → Patch initial access vector → Server hardening |
Q & A
Q: TheHive case data contains sensitive incident details. How do you protect it?
TheHive's TLP and PAP markings control sharing, but they're advisory labels, not technical access controls. For technical protection: (1) Deploy TheHive on an isolated segment — not accessible from the internet or general corporate network. (2) Use HTTPS with a valid certificate. (3) API keys for service accounts should be rotated and scoped with minimal permissions. (4) TheHive supports user roles — analysts see cases assigned to them; only IR leads and SOC managers see all cases. Configure RBAC before deployment. (5) TheHive stores case data in Elasticsearch — at-rest encryption of the Elasticsearch data directory protects against physical storage compromise. (6) For highly sensitive incidents (insider threat, executive compromise), consider a separate TheHive instance with access restricted to the specific investigation team.