SOC 部署：TheHive 5.4 + Cortex 3.1.8

在任意支持 Docker 的 Linux 主机上部署 TheHive + Cortex 事件响应平台。

本技能 不会 创建虚拟机。 它要求目标主机已配置 SSH 访问且已安装 Docker。如需底层基础设施，请先使用 hyperv-create-vm 或 proxmox-create-vm。

适用场景

• “部署 thehive”
• “搭建 thehive”
• “安装 thehive 和 cortex”
• “thehive 实验环境”
• “事件响应平台”

用户输入

前提条件检查

# 确认 SSH 可连通
ssh  "echo OK"

# 确认 Docker 与 Compose v2 已安装
ssh  "docker --version && docker compose version"

# 检查内存（需至少 4GB 可用内存）
ssh  "free -h | grep Mem"

执行流程

单命令部署

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
2. 执行 docker compose up -d（启动 Cassandra、Elasticsearch、TheHive 与 Cortex）
3. 轮询各服务健康端点，直至全部响应成功：
   • 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 key
5. Cortex 初始化（含 CSRF 流程）：
   • POST /api/maintenance/migrate
   • POST /api/user（创建 superadmin；此为“首次用户”专用端点）
   • POST /api/login → 获取 session cookie
   • GET /api/user/admin → 提取 CORTEX-XSRF-TOKEN cookie
   • POST /api/organization（需携带 CSRF cookie 及对应 header）
   • POST /api/user（创建组织管理员，需携带 CSRF）
   • POST /api/user//key/renew（需携带 CSRF）→ 获取组织级 API key
   • POST /api/user/admin/key/renew（需携带 CSRF）→ 获取 superadmin API key
6. 配置 TheHive-Cortex 集成：
   • 更新 docker-compose.yml：添加参数 --cortex-hostnames cortex --cortex-keys
   • docker compose up -d thehive（仅重启 TheHive 服务）
   • 等待 30 秒，确保 TheHive 启动完成
7. 验证两个 API 均可返回 Bearer 类型密钥
8. 将凭证信息写入 ~/thehive-cortex/api-keys.txt

向用户输出结果

TheHive + Cortex 已成功部署！

TheHive: http://:9000
Cortex:  http://:9001

登录凭证：
  TheHive 管理员：     admin@thehive.local / 
  Cortex superadmin： admin / 
  Cortex 组织管理员： -admin（仅 API key）

API 密钥：
  TheHive：           
  Cortex superadmin： 
  Cortex 组织管理员： 

MCP 连接配置：
  THEHIVE_URL=http://:9000
  THEHIVE_API_KEY=
  CORTEX_URL=http://:9001
  CORTEX_API_KEY=

密钥已保存至：~/thehive-cortex/api-keys.txt

关键注意事项（Critical Gotchas）

完整细节请参阅 references/gotchas.md：

1. Cortex 的 CSRF 机制（自动化最大障碍）：所有变更类请求均需同时携带 CORTEX-XSRF-TOKEN cookie 与 X-CORTEX-XSRF-TOKEN header。标准 Play Framework 的绕过 header 不生效。获取首个 API key 后，可改用 Authorization: Bearer 认证方式跳过 CSRF 校验。
2. TheHive 密码修改端点：POST /password/change 需提供 currentPassword 与 password 字段。PATCH 方式虽返回 204，但会静默忽略 password 字段。
3. Bash 中密码含 ! 字符：应使用 printf '...' | curl -d @- 方式传参，避免直接使用 -d 并在其中嵌入感叹号（!）导致 shell 解析异常。
4. “首次用户”一次性限制：Cortex 的 POST /api/user（无认证）仅在系统中尚无任何用户时有效。
5. TheHive 启动延迟：执行 docker compose up -d 后需等待 15–30 秒（等待 Cassandra 初始化完成）。
6. 密钥（secret）长度要求：TheHive 基于 Play Framework 的 JWT 实现要求 secret 至少 32 字符。
7. 集成推荐使用组织管理员密钥：TheHive-Cortex 集成应使用组织管理员（org admin）密钥，而非 superadmin 密钥，以遵循最小权限原则。

API 快速参考

完整端点列表请参阅 references/api-reference.md。

超时策略

整个部署耗时约 5–7 分钟（主要耗时在服务就绪等待）。若本地未缓存镜像，需额外增加约 5 分钟用于拉取镜像。流程分为两阶段：

• 第一阶段：docker compose up -d + 镜像拉取（约 5 分钟）
• 第二阶段：账号初始化 + API 密钥生成（约 3 分钟）

配套技能

• hyperv-create-vm — 创建 Hyper-V 虚拟机，随后在其上部署 TheHive
• proxmox-create-vm — 创建 Proxmox LXC/VM，随后在其上部署 TheHive
• soc-deploy-misp — 同步部署 MISP，用于威胁情报支撑