Deploy TheHive + Cortex incident response platform on any Docker-ready Linux host.

This skill does NOT create VMs. It expects an SSH target with Docker installed. Use hyperv-create-vm or proxmox-create-vm first if you need infrastructure.

When to Use

• "deploy thehive"
• "set up thehive"
• "install thehive and cortex"
• "thehive lab"
• "incident response platform"

User Inputs

Parameter	Default	Required
SSH target	-	Yes (user@host)
Admin password	ChangeMe123!	No
Org name (Cortex)	SOC	No
TheHive secret	(generated 40-char)	No

Prerequisites Check

# SSH works
ssh  "echo OK"
# Docker + Compose v2
ssh  "docker --version && docker compose version"
# RAM check (need 4GB+ free)
ssh  "free -h | grep Mem"

Execution

Single command deployment

scp scripts/setup.sh :~/
scp references/docker-compose.yml :~/thehive-cortex/docker-compose.yml
ssh  "bash ~/setup.sh '' ''"

What setup.sh does (from thehive-cortex-setup-guide.md)

• Create directory + write docker-compose.yml
• docker compose up -d (Cassandra + ES + TheHive + Cortex)
• Poll health endpoints until all services respond:

- GET :9200/_cluster/health (Elasticsearch) - GET :9000/api/status (TheHive) - GET :9001/api/status (Cortex)

• TheHive admin setup:

- POST /api/v1/login with admin@thehive.local / secret - POST /api/v1/user/admin@thehive.local/password/change (NOT PATCH) - POST /api/v1/user/admin@thehive.local/key/renew -> API key

• Cortex setup (CSRF dance):

- POST /api/maintenance/migrate - POST /api/user (create superadmin, first-user endpoint) - POST /api/login -> session cookie - GET /api/user/admin -> capture CORTEX-XSRF-TOKEN cookie - POST /api/organization (with CSRF cookie + header) - POST /api/user (org admin, with CSRF) - POST /api/user//key/renew (with CSRF) -> org key - POST /api/user/admin/key/renew (with CSRF) -> super key

• Wire integration:

- Update docker-compose.yml: add --cortex-hostnames cortex --cortex-keys - docker compose up -d thehive (restart only TheHive) - Wait 30s for TheHive startup

• Verify both APIs respond with Bearer keys
• Write credentials to ~/thehive-cortex/api-keys.txt

Output to User

TheHive + Cortex deployed!
TheHive: http://:9000
Cortex:  http://:9001
Credentials:
  TheHive admin:     admin@thehive.local / 
  Cortex superadmin: admin / 
  Cortex org admin:  -admin (API key only)
API Keys:
  TheHive:           
  Cortex superadmin: 
  Cortex org admin:  
MCP Connection:
  THEHIVE_URL=http://:9000
  THEHIVE_API_KEY=
  CORTEX_URL=http://:9001
  CORTEX_API_KEY=
Keys saved to: ~/thehive-cortex/api-keys.txt

Critical Gotchas

See references/gotchas.md for full details:

• Cortex CSRF (biggest automation blocker): Cookie CORTEX-XSRF-TOKEN + header X-CORTEX-XSRF-TOKEN on ALL mutating requests. Standard Play Framework bypass headers do NOT work. After first API key, use Authorization: Bearer to skip CSRF
• TheHive password endpoint: POST /password/change with currentPassword+password. The PATCH endpoint returns 204 but silently ignores the password field
• Bash ! in passwords: Use printf '...' | curl -d @-, not direct -d with exclamation marks
• First-user one-shot: Cortex POST /api/user without auth only works when zero users exist
• TheHive startup delay: 15-30s after compose up (waits for Cassandra)
• Secret length: TheHive Play Framework JWT needs 32+ char secret
• Use org admin key (not superadmin) for TheHive-Cortex integration (least privilege)

API Quick Reference

See references/api-reference.md for the full endpoint list.

Timeout Strategy

Setup takes ~5-7 min (mostly waiting for services). If docker images are not cached, add ~5 min for pull. Split into:

• Turn 1: docker compose up -d + pull images (~5 min)
• Turn 2: Account setup + API keys (~3 min)

Pairs With

• hyperv-create-vm - create a Hyper-V VM, then deploy TheHive on it
• proxmox-create-vm - create a Proxmox LXC/VM, then deploy TheHive on it
• soc-deploy-misp - deploy MISP alongside for threat intelligence

# SSH works
ssh  "echo OK"
# Docker + Compose v2
ssh  "docker --version && docker compose version"
# RAM check (need 4GB+ free)
ssh  "free -h | grep Mem"

scp scripts/setup.sh :~/
scp references/docker-compose.yml :~/thehive-cortex/docker-compose.yml
ssh  "bash ~/setup.sh '' ''"

TheHive + Cortex deployed!
TheHive: http://:9000
Cortex:  http://:9001
Credentials:
  TheHive admin:     admin@thehive.local / 
  Cortex superadmin: admin / 
  Cortex org admin:  -admin (API key only)
API Keys:
  TheHive:           
  Cortex superadmin: 
  Cortex org admin:  
MCP Connection:
  THEHIVE_URL=http://:9000
  THEHIVE_API_KEY=
  CORTEX_URL=http://:9001
  CORTEX_API_KEY=
Keys saved to: ~/thehive-cortex/api-keys.txt