SOC Deploy: TheHive 5.4 + Cortex 3.1.8
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
CODEBLOCK0
Execution
Single command deployment
CODEBLOCK1
What setup.sh does (from thehive-cortex-setup-guide.md)
- 1. 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)
- 4. 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
- 5. 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/<org-admin>/key/renew (with CSRF) -> org key
-
POST /api/user/admin/key/renew (with CSRF) -> super key
- 6. Wire integration:
- Update docker-compose.yml: add
--cortex-hostnames cortex --cortex-keys <org-admin-key>
-
docker compose up -d thehive (restart only TheHive)
- Wait 30s for TheHive startup
- 7. Verify both APIs respond with Bearer keys
- Write credentials to INLINECODE22
Output to User
CODEBLOCK2
Critical Gotchas
See references/gotchas.md for full details:
- 1. 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 - INLINECODE37 - create a Proxmox LXC/VM, then deploy TheHive on it
- INLINECODE38 - deploy MISP alongside for threat intelligence
SOC 部署：TheHive 5.4 + Cortex 3.1.8
在任何支持 Docker 的 Linux 主机上部署 TheHive + Cortex 事件响应平台。
此技能不会创建虚拟机。 它需要一个已安装 Docker 的 SSH 目标。如果需要基础设施，请先使用 hyperv-create-vm 或 proxmox-create-vm。
使用场景
- - 部署 thehive
- 搭建 thehive
- 安装 thehive 和 cortex
- thehive 实验室
- 事件响应平台
用户输入
| 参数 | 默认值 | 是否必需 |
|---|
| SSH 目标 | - | 是 (user@host) |
| 管理员密码 |
ChangeMe123! | 否 |
| 组织名称 (Cortex) | SOC | 否 |
| TheHive 密钥 | (自动生成40位字符) | 否 |
前置条件检查
bash
SSH 连接测试
ssh
echo OK
Docker + Compose v2 检查
ssh docker --version && docker compose version
内存检查（需要4GB+可用空间）
ssh free -h | grep Mem
执行步骤
单命令部署
bash
scp scripts/setup.sh :~/
scp references/docker-compose.yml :~/thehive-cortex/docker-compose.yml
ssh bash ~/setup.sh
setup.sh 执行内容（来自 thehive-cortex-setup-guide.md）
- 1. 创建目录 + 写入 docker-compose.yml
- docker compose up -d（启动 Cassandra + ES + TheHive + Cortex）
- 轮询健康检查端点 直到所有服务响应：
- GET :9200/_cluster/health（Elasticsearch）
- GET :9000/api/status（TheHive）
- GET :9001/api/status（Cortex）
- 4. TheHive 管理员设置：
- POST /api/v1/login 使用 admin@thehive.local / secret
- POST /api/v1/user/admin@thehive.local/password/change（非 PATCH）
- POST /api/v1/user/admin@thehive.local/key/renew -> API 密钥
- 5. Cortex 设置（CSRF 处理）：
- POST /api/maintenance/migrate
- POST /api/user（创建超级管理员，首次用户端点）
- POST /api/login -> 会话 Cookie
- GET /api/user/admin -> 捕获 CORTEX-XSRF-TOKEN Cookie
- POST /api/organization（带 CSRF Cookie + 请求头）
- POST /api/user（组织管理员，带 CSRF）
- POST /api/user//key/renew（带 CSRF）-> 组织密钥
- POST /api/user/admin/key/renew（带 CSRF）-> 超级密钥
- 6. 集成配置：
- 更新 docker-compose.yml：添加 --cortex-hostnames cortex --cortex-keys
- docker compose up -d thehive（仅重启 TheHive）
- 等待 30 秒让 TheHive 启动
- 7. 验证两个 API 都能使用 Bearer 密钥响应
- 写入凭据 到 ~/thehive-cortex/api-keys.txt
输出给用户
TheHive + Cortex 部署完成！
TheHive: http://:9000
Cortex: http://:9001
凭据信息：
TheHive 管理员: admin@thehive.local /
Cortex 超级管理员: admin /
Cortex 组织管理员: -admin（仅 API 密钥）
API 密钥：
TheHive:
Cortex 超级管理员:
Cortex 组织管理员:
MCP 连接配置：
THEHIVE_URL=http://:9000
THEHIVEAPIKEY=
CORTEX_URL=http://:9001
CORTEXAPIKEY=
密钥已保存至：~/thehive-cortex/api-keys.txt
关键注意事项
详见 references/gotchas.md：
- 1. Cortex CSRF（最大的自动化障碍）： 所有修改请求都需要 Cookie CORTEX-XSRF-TOKEN + 请求头 X-CORTEX-XSRF-TOKEN。标准的 Play Framework 绕过请求头无效。获取第一个 API 密钥后，使用 Authorization: Bearer 跳过 CSRF
- TheHive 密码端点： POST /password/change 使用 currentPassword+password。PATCH 端点返回 204 但会静默忽略密码字段
- Bash 中密码包含 !： 使用 printf ... | curl -d @-，不要直接使用带感叹号的 -d 参数
- 首次用户一次性设置： Cortex 的 POST /api/user 无需认证仅在零用户时有效
- TheHive 启动延迟： compose up 后需要 15-30 秒（等待 Cassandra）
- 密钥长度： TheHive Play Framework JWT 需要 32 位以上字符的密钥
- 使用组织管理员密钥（非超级管理员）进行 TheHive-Cortex 集成（最小权限原则）
API 快速参考
完整端点列表请参见 references/api-reference.md。
超时策略
设置过程约需 5-7 分钟（主要是等待服务启动）。如果 Docker 镜像未缓存，需额外增加约 5 分钟用于拉取。建议分步执行：
- - 第一步：docker compose up -d + 拉取镜像（约 5 分钟）
- 第二步：账户设置 + API 密钥（约 3 分钟）
配合使用
- - hyperv-create-vm - 创建 Hyper-V 虚拟机，然后在其上部署 TheHive
- proxmox-create-vm - 创建 Proxmox LXC/容器，然后在其上部署 TheHive
- soc-deploy-misp - 同时部署 MISP 用于威胁情报
