System & Network TheHive SOAR
Bài 35 · Giai đoạn 7 — Observability & Security nâng cao

TheHive 5 + Cortex SOAR

Incident response platform — tích hợp Wazuh alerts, auto-analyze IoCs.

VM270 · node2 Ubuntu Server 24.04 LTS 10.11.25.11 4 vCPU · 8 GB · 50 GB

Bối cảnh & Lý do triển khai

Vị trí trong chuỗi bài: Bài 35 thuộc Giai đoạn 7 — Observability & Security nâng cao, nối tiếp Bài 34. Vault / OpenBao và đứng trước Bài 36. CrowdSec IPS.
Mức độ cần thiết: 🟡 Quan trọng — Security Orchestration, Automation & Response

Wazuh SIEM hiện đang generate hàng trăm alert/ngày nhưng chưa có workflow xử lý: ai nhận alert, điều tra thế nào, đóng case ra sao? TheHive cung cấp case management platform — mỗi Wazuh alert nghiêm trọng tự động tạo case trong TheHive để SOC analyst xử lý. Cortex chạy cùng VM thực hiện automated analysis: khi có IoC (IP, domain, hash), Cortex tự gọi VirusTotal, Shodan, AbuseIPDB để enrich thông tin mà không cần analyst làm thủ công.

Đây là bước hoàn thiện vòng lặp detect-respond: Wazuh detect → TheHive manage case → Cortex analyze IoC → analyst response với đầy đủ context.

MụcNội dung
Ứng dụng trong doanh nghiệpIncident response workflow, IoC enrichment tự động, case tracking
Tác dụng chínhKhông bỏ sót alert, có audit trail đầy đủ, analyst có context trước khi respond
Nếu không triển khaiAlert từ Wazuh/CrowdSec chìm vào log, không có incident tracking
Các service phụ thuộc vào đâyWazuh SIEM (nguồn alert), Mattermost (notify), Mailu (email notify)

Danh sách máy chủ & IP liên quan

Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.

Máy chủIPVLAN · NodeVai trò trong bài này
thehive (TheHive + Cortex) · VM27010.11.25.1125 (SEC) · node2Máy chủ của bài — chạy TheHive 5 (:9000) và Cortex 3 (:9001) cùng Cassandra, Elasticsearch, Nginx HTTPS bằng Docker Compose.
node2 (Proxmox VE)10.11.45.21145 (MGMT) · cluster HOATRANHUBNode Proxmox chứa VM270; tạo VM (VLAN tag 25, scsi0 50 GiB trên SSD vm-ceph) và cài Ubuntu qua qm terminal.
pihole (Pi-hole DNS) · VM24710.11.45.5345 (MGMT) · node3Làm DNS cho VM; thêm bản ghi thehive.hoatranlabs.local và cortex.hoatranlabs.local trỏ về VM TheHive (bài 12).
step-ca (step-CA PKI) · VM24210.11.25.4225 (SEC) · node1Cấp một chứng chỉ TLS cho Nginx (SAN gồm thehive, cortex, IP) qua step ca certificate, hiệu lực 1 năm (bài 13).
wazuh-siem (Wazuh SIEM) · VM28010.11.45.2545 (MGMT) · node1Nguồn alert: script custom-thehive.py trong container manager gửi alert level 10 trở lên tới API TheHive (bài 17).
authentik (Authentik SSO) · VM23410.11.25.4025 (SEC) · node1Nhà cung cấp OAuth2/OIDC cho đăng nhập SSO của TheHive (redirect /api/ssoLogin, application slug thehive) (bài 14).
mailu (Mailu Mail Server) · VM24610.11.35.4635 (DMZ) · node2Relay SMTP cổng 587 (STARTTLS) cho SMTP của TheHive (Platform management → SMTP); gửi email thông báo khi có alert mức High (bài 16).
prometheus (Prometheus + Alertmanager) · VM23510.11.45.3545 (MGMT) · node2Scrape node_exporter của VM TheHive cổng 9100 để lấy metrics số case mở và alert mới (job thehive-node, bài 15).
pbs01 (PBS Primary) · VM10110.11.45.1745 (MGMT) · node4Nhận backup file-level /opt/thehive (loại trừ dữ liệu Cassandra, Elasticsearch), token vm-backup@pbs!thehive (bài 04).
syno-primary (Synology NAS)10.11.45.1645 (MGMT) · NASNAS chứa datastore syno-primary — đích lưu bản backup cấu hình TheHive/Cortex (bài 04).

Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local.

Thông tin VM

Thông sốGiá trị
VMID270
Hostnamethehive
IP10.11.25.11/24
Gateway10.11.25.1
VLAN25 (VLAN_SEC)
vCPU4
RAM8 GB
Disk50 GB (scsi0, SSD vm-ceph)
OSUbuntu Server 24.04 LTS
Phân bổ nodenode2
Dung lượng đĩa theo kế hoạch lab 800 GB SSD + 1 TB HDD (bài 07, mục 8.4): dựng bằng create-lab-vms.sh thì scsi0 = 50 GB trên SSD vm-ceph, không có đĩa dữ liệu scsi1 (Cassandra và Elasticsearch cần IOPS ngẫu nhiên nên ở lại SSD, trong /opt/thehive/cassandra/data và /opt/thehive/elasticsearch/data); số 50 GB khớp vms.csv và chỉ là trần danh nghĩa (thin provisioning), môi trường thật nên cấp lớn hơn (bài từng ghi 100 GB). Elasticsearch ngừng gán shard mới khi đĩa dùng từ 85% (low watermark mặc định) nên giữ đĩa dưới 80%, và nodetool snapshot ở mục 4.6 không tự xóa nên định kỳ chạy docker exec cassandra nodetool clearsnapshot --all (cần kiểm lại trên máy thật).

Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):

Thành phầnPhiên bảnGhi chú
Hệ điều hànhUbuntu Server 24.04.5 LTS "Noble Numbat" (ISO ubuntu-24.04.5-live-server-amd64.iso)24.04.5 ra ngày 2026-09-10; hỗ trợ chuẩn tới 04/2029. Kernel GA 6.8, systemd 255, cgroup v2. StrangeBee liệt kê Ubuntu 20.04/22.04/24.04 là hệ điều hành được hỗ trợ (docs.strangebee.com, trang System requirements).
Docker Enginedocker-ce 29.9.1 (repo download.docker.com/linux/ubuntu suite noble, ngày 2026-10-14)Yêu cầu của StrangeBee: Docker Engine từ 23.0.15 và Compose plugin từ 2.20.2. Compose plugin mới nhất trong repo noble: 5.6.0. Gỡ docker.io, docker-compose-v2 của Ubuntu trước khi cài (mục 1.4).
TheHive5.3 (image strangebee/thehive:5.3, ghim)Chạy trong container nên host chỉ cần Docker. Docs StrangeBee hiện liệt kê tới 5.8.1; bài giữ 5.3 để các bước khớp nhau.
Cortex3.1.8 (image thehiveproject/cortex:3.1.8, ghim)Cortex gọi Docker qua /var/run/docker.sock để chạy analyzer; ghi chú tương thích Docker 29 ở mục 6.
Cassandra / Elasticsearch / Nginxcassandra:4.1, elasticsearch:7.17.18, nginx:1.25-alpine (ghim, container)Giữ nguyên; khớp dải Cassandra 4.0.x–4.1.x và Elasticsearch 7.10.x–8.x mà StrangeBee liệt kê cho TheHive 5.3.
step-cli0.31.0 (step-cli_0.31.0-1_amd64.deb)Bài 13 ghim 0.27.4 cho step-ca; chưa kiểm cặp CLI 0.31.0 với step-ca 0.27.4 trên máy thật.
node_exporter1.12.1Cài theo script bài 15, đổi biến phiên bản; cổng 9100.
proxmox-backup-clientproxmox-backup-client-static 4.x, repo pbs-client suite trixieBản tĩnh nên không phụ thuộc glibc của noble; cần kiểm lại trên máy thật (mục 4.6).
01

Tạo VM trên Proxmox

Tải Ubuntu ISO (nếu chưa có) · Tạo VM · Cài đặt Ubuntu 24.04

1.1 Tải Ubuntu ISO (nếu chưa có)

wget -O /var/lib/vz/template/iso/ubuntu-24.04-server.iso \
  https://releases.ubuntu.com/24.04/ubuntu-24.04.5-live-server-amd64.iso

1.2 Tạo VM

Cách 1: Web UI Proxmox (GUI)

1
Đăng nhập Proxmox Web UI → chọn Node: node2 → nhấn Create VM (góc trên phải)
2
General:
  • VM ID: 270
  • Name: thehive
  • Bỏ tick Start after created
3
OS:
  • Storage: local (hoặc nơi chứa ISO)
  • ISO Image: ubuntu-24.04-server.iso
  • Guest OS Type: Linux, Version: 6.x - 2.6 Kernel
4
System:
  • Machine: q35
  • SCSI Controller: VirtIO SCSI single
  • BIOS: SeaBIOS
  • Qemu Agent: ☑
5
Disks:
  • Bus/Device: SCSI 0, Storage: vm-ceph
  • Disk size: 50 GiB, Cache: Write back, Discard: ☑
6
CPU:
  • Sockets: 1, Cores: 4, Type: x86-64-v2-AES
7
Memory:
  • Memory (MiB): 8192
8
Network:
  • Bridge: vmbr0, VLAN Tag: 25, Model: VirtIO (paravirtualized), Firewall: ☐
9
Confirm: Xem lại → Finish → Start VM → Console để bắt đầu cài Ubuntu.
Proxmox Create VM trên node2 → tab Confirm: thehive (VMID 270), 4 cores, 8192 MiB, scsi0 100G trên vm-ceph, net0 vmbr0 tag=25.
Proxmox Create VM trên node2 → tab Confirm: thehive (VMID 270), 4 cores, 8192 MiB, scsi0 100G trên vm-ceph, net0 vmbr0 tag=25.

Cách 2: CLI (qm create)

qm create 270 --name thehive --memory 8192 --cores 4 --sockets 1 \
  --net0 virtio,bridge=vmbr0,tag=25 \
  --scsi0 vm-ceph:50,cache=writeback \
  --ide2 local:iso/ubuntu-24.04-server.iso,media=cdrom \
  --boot "order=ide2;scsi0" \
  --ostype l26 --machine q35 --bios seabios \
  --agent 1 --serial0 socket --vga serial0
qm start 270

1.3 Cài đặt Ubuntu 24.04

Theo dõi console qua qm terminal 270:

  • Username: sysadmin, hostname: thehive
  • Ubuntu Pro: Skip for now (nếu màn hình này xuất hiện)
  • SSH: Install OpenSSH server ✓
  • Không cần snap packages

1.4 Cấu hình sau cài đặt

# Ubuntu 24.04 có needrestart: đặt chế độ tự động để apt không hiện hộp thoại hỏi khởi động lại dịch vụ
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
apt install -y qemu-guest-agent curl wget git vim net-tools jq ufw ca-certificates

# Gỡ gói Docker của Ubuntu (nếu có) rồi cài Docker CE từ repo chính thức, suite noble, nguồn deb822 + Signed-By
apt remove -y docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc 2>/dev/null || true
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
cat > /etc/apt/sources.list.d/docker.sources << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
docker --version && docker compose version   # bài đã kiểm với docker-ce 29.9.1 (2026-10-14); StrangeBee cần Engine >= 23.0.15 và Compose plugin >= 2.20.2

systemctl enable --now qemu-guest-agent docker

# Thêm sysadmin vào group docker
usermod -aG docker sysadmin

# Static IP
ip -br link                 # xem tên NIC thật (ens18, enp6s18...) vì máy q35 có thể không phải ens18
NIC=$(ip -br link | awk '$1!="lo"{print $1; exit}')
echo "NIC = $NIC"

# Ubuntu 24.04 ghi mạng của bản cài vào /etc/netplan/50-cloud-init.yaml (DHCP); giữ nguyên tệp đó thì DHCP
# cộng dồn với IP tĩnh. Tắt phần mạng của cloud-init rồi thay bằng một tệp duy nhất:
echo 'network: {config: disabled}' > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
rm -f /etc/netplan/*.yaml
cat > /etc/netplan/01-netcfg.yaml << EOF
network:
  version: 2
  ethernets:
    ${NIC}:
      addresses: [10.11.25.11/24]
      routes:
        - to: default
          via: 10.11.25.1
      nameservers:
        addresses: [10.11.45.53]
        search: [hoatranlabs.local]
EOF
chmod 600 /etc/netplan/01-netcfg.yaml
netplan apply   # nếu đang SSH bằng IP DHCP thì phiên sẽ đứt; đăng nhập lại bằng 10.11.25.11

# Firewall
ufw default deny incoming
ufw default allow outgoing
ufw allow from 10.11.0.0/16 to any port 22
ufw allow from 10.11.0.0/16 to any port 9000
ufw allow from 10.11.0.0/16 to any port 9001
ufw allow from 10.11.0.0/16 to any port 80
ufw allow from 10.11.0.0/16 to any port 443
ufw --force enable
02

Cài đặt TheHive 5 + Cortex

Cấu trúc thư mục · Lấy TLS cert từ step-CA · Cấu hình TheHive

2.1 Cấu trúc thư mục

mkdir -p /opt/thehive/{thehive,cortex,cassandra,elasticsearch,nginx}
mkdir -p /opt/thehive/thehive/{data,logs,config}
mkdir -p /opt/thehive/cortex/{data,logs,config,jobs}
mkdir -p /opt/thehive/cassandra/{data}
mkdir -p /opt/thehive/elasticsearch/{data,logs}
mkdir -p /opt/thehive/nginx/certs

# Permissions
chown -R 1000:1000 /opt/thehive/thehive/{data,logs}
chown -R 999:999  /opt/thehive/cassandra/data
chown -R 1000:1000 /opt/thehive/elasticsearch/{data,logs}
chown -R 1000:1000 /opt/thehive/cortex/{data,logs,jobs}

# Elasticsearch cần vm.max_map_count cao
echo "vm.max_map_count=262144" >> /etc/sysctl.conf
sysctl -p

2.2 Lấy TLS cert từ step-CA

# Cài step CLI 0.31.0 bằng gói .deb (tên tệp có hậu tố "-1"; URL đã kiểm trả HTTP 200 ngày 2026-10-15)
STEP_VERSION="0.31.0"
wget -O /tmp/step.deb "https://dl.smallstep.com/gh-release/cli/gh-release-header/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb"
dpkg -i /tmp/step.deb
step version

step ca bootstrap --ca-url https://step-ca.hoatranlabs.local:9000 --fingerprint <FINGERPRINT>

step ca certificate thehive.hoatranlabs.local \
  /opt/thehive/nginx/certs/thehive.crt \
  /opt/thehive/nginx/certs/thehive.key \
  --san thehive.hoatranlabs.local --san cortex.hoatranlabs.local \
  --san 10.11.25.11 --ca-url https://step-ca.hoatranlabs.local:9000 --not-after 2160h

TheHive (container thehive) gọi Mailu qua STARTTLS (cổng 587, cert step-CA, xác thực chứng chỉ) và gọi Authentik qua HTTPS cho SSO (mục 4.3), nên JVM của TheHive phải tin cậy root CA của step-CA. Với TheHive 5.5.3 trở về trước (image strangebee/thehive:5.3), cách theo tài liệu StrangeBee là tạo truststore và truyền qua JAVA_OPTS (từ 5.5.4 mới có biến TH_CACERT_FOLDER/TH_CACERT_STRING nhận file PEM). Truststore này chỉ chứa root CA của lab (TheHive chỉ gọi dịch vụ nội bộ); file phải tồn tại TRƯỚC docker compose up, nếu không Docker sẽ tạo thư mục rỗng tại đường dẫn mount:

# Lưu root CA step-CA ở đường dẫn dùng chung của lab (như bài 13, 21, 22)
step ca root /usr/local/share/ca-certificates/hoatranlabs-root.crt
update-ca-certificates

# Tạo truststore JKS chứa root CA (dùng keytool có sẵn trong image TheHive; hoặc keytool của bất kỳ JDK nào)
docker run --rm --user root --entrypoint keytool \
  -v /usr/local/share/ca-certificates/hoatranlabs-root.crt:/ca/root.crt:ro \
  -v /opt/thehive/thehive/config:/out \
  strangebee/thehive:5.3 \
  -importcert -noprompt -trustcacerts -alias hoatranlabs-root \
  -file /ca/root.crt -keystore /out/truststore.jks -storetype JKS -storepass changeit

Cortex không cần truststore này: Cortex chỉ nhận kết nối HTTP nội bộ từ TheHive và không gửi mail.

2.3 Cấu hình TheHive

cat > /opt/thehive/thehive/config/application.conf << 'EOF'
# TheHive 5 Configuration
play.http.secret.key = "hoatranlabs_thehive_secret_change_in_prod_2024"

# Database — Cassandra
db.janusgraph {
  storage.backend = cql
  storage.cql.cluster-name = thehive
  storage.cql.local-datacenter = "datacenter1"
  storage.hostname = ["cassandra"]
  storage.cql.port = 9042
  storage.cql.replication-factor = 1
}

# Index backend — Elasticsearch
index.search {
  backend = elasticsearch
  hostname = ["elasticsearch"]
  index-name = thehive
}

# File storage — local
storage {
  provider = localfs
  localfs.location = /opt/thehive/data
}

# Cortex connector
play.modules.enabled += org.thp.thehive.connector.cortex.CortexConnector
cortex {
  servers = [
    {
      name = cortex-local
      url  = "http://cortex:9001"
      auth {
        type = "bearer"
        key  = "CORTEX_API_KEY_PLACEHOLDER"
      }
      wsConfig {}
    }
  ]
  refreshDelay = 5 seconds
  maxRetryOnError = 3
  statusCheckInterval = 1 minute
}

# SMTP (Mailu) không khai báo trong application.conf: TheHive 5 cấu hình SMTP trong giao diện
# (Platform management → SMTP, xem mục 3.4)
EOF

2.4 Docker Compose — Toàn bộ stack

cat > /opt/thehive/docker-compose.yml << 'EOF'
version: "3.8"

services:
  # ===== Cassandra (TheHive database) =====
  cassandra:
    image: cassandra:4.1
    container_name: cassandra
    hostname: cassandra
    restart: unless-stopped
    environment:
      CASSANDRA_CLUSTER_NAME: "thehive"
      CASSANDRA_DC: datacenter1
      CASSANDRA_RACK: rack1
      HEAP_NEWSIZE: "128M"
      MAX_HEAP_SIZE: "1024M"
    volumes:
      - /opt/thehive/cassandra/data:/var/lib/cassandra
    networks:
      - thehive-net
    healthcheck:
      test: ["CMD", "cqlsh", "-e", "describe keyspaces"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 60s

  # ===== Elasticsearch (Cortex + TheHive index) =====
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.18
    container_name: elasticsearch
    hostname: elasticsearch
    restart: unless-stopped
    environment:
      discovery.type: single-node
      xpack.security.enabled: "false"
      ES_JAVA_OPTS: "-Xms1g -Xmx1g"
      cluster.name: hive
      thread_pool.search.queue_size: "100000"
    volumes:
      - /opt/thehive/elasticsearch/data:/usr/share/elasticsearch/data
      - /opt/thehive/elasticsearch/logs:/usr/share/elasticsearch/logs
    networks:
      - thehive-net
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 30s

  # ===== Cortex 3 =====
  cortex:
    image: thehiveproject/cortex:3.1.8
    container_name: cortex
    hostname: cortex
    restart: unless-stopped
    environment:
      - job_directory=/opt/cortex/jobs
    volumes:
      - /opt/thehive/cortex/data:/var/log/cortex
      - /opt/thehive/cortex/config:/etc/cortex
      - /opt/thehive/cortex/jobs:/opt/cortex/jobs
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - thehive-net
    depends_on:
      elasticsearch:
        condition: service_healthy
    ports:
      - "9001:9001"
    command: ["--no-config", "--config-file", "/etc/cortex/application.conf"]

  # ===== TheHive 5 =====
  thehive:
    image: strangebee/thehive:5.3
    container_name: thehive
    hostname: thehive
    restart: unless-stopped
    environment:
      - JVM_OPTS=-Xms1g -Xmx3g
      # Truststore chứa root CA step-CA (mục 2.2): TheHive tin cậy Mailu STARTTLS và Authentik
      - JAVA_OPTS=-Djavax.net.ssl.trustStore=/etc/thehive/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit
    volumes:
      - /opt/thehive/thehive/data:/opt/thehive/data
      - /opt/thehive/thehive/logs:/var/log/thehive
      - /opt/thehive/thehive/config/application.conf:/etc/thehive/application.conf:ro
      - /opt/thehive/thehive/config/truststore.jks:/etc/thehive/truststore.jks:ro
    networks:
      - thehive-net
    depends_on:
      cassandra:
        condition: service_healthy
      elasticsearch:
        condition: service_healthy
      cortex:
        condition: service_started
    ports:
      - "9000:9000"
    command: ["--config-file", "/etc/thehive/application.conf"]

  # ===== Nginx reverse proxy =====
  nginx:
    image: nginx:1.25-alpine
    container_name: nginx-thehive
    restart: unless-stopped
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - /opt/thehive/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - /opt/thehive/nginx/certs:/etc/nginx/certs:ro
    networks:
      - thehive-net
    depends_on:
      - thehive
      - cortex

networks:
  thehive-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/24
EOF

2.5 Cấu hình Cortex

cat > /opt/thehive/cortex/config/application.conf << 'EOF'
play.http.secret.key = "hoatranlabs_cortex_secret_change_in_prod_2024"

search {
  index = cortex
  uri   = "http://elasticsearch:9200"
}

cache.job = 10 minutes

job {
  runner = [docker, process]
  dockerDirectory = /opt/cortex/jobs
}

# Docker-based analyzers
docker {
  autoUpdate = true
}
EOF

2.6 Nginx config

cat > /opt/thehive/nginx/nginx.conf << 'EOF'
events { worker_connections 1024; }

http {
  upstream thehive  { server thehive:9000; }
  upstream cortex   { server cortex:9001; }

  server {
    listen 80;
    server_name thehive.hoatranlabs.local cortex.hoatranlabs.local;
    return 301 https://$host$request_uri;
  }

  server {
    listen 443 ssl;
    server_name thehive.hoatranlabs.local;
    ssl_certificate     /etc/nginx/certs/thehive.crt;
    ssl_certificate_key /etc/nginx/certs/thehive.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    client_max_body_size 50m;

    location / {
      proxy_pass http://thehive;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto https;
      proxy_read_timeout 600;
    }
  }

  server {
    listen 443 ssl;
    server_name cortex.hoatranlabs.local;
    ssl_certificate     /etc/nginx/certs/thehive.crt;
    ssl_certificate_key /etc/nginx/certs/thehive.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
      proxy_pass http://cortex;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-Proto https;
      proxy_read_timeout 600;
    }
  }
}
EOF

2.7 Khởi động stack

cd /opt/thehive
docker compose up -d cassandra elasticsearch
# Chờ Cassandra healthy (~60 giây)
docker compose logs -f cassandra --tail=20

docker compose up -d cortex
sleep 30
docker compose up -d thehive nginx
docker compose ps
docker compose logs -f thehive --tail=30
Terminal: docker compose ps liệt kê cassandra, elasticsearch, cortex, thehive, nginx-thehive đều Up/healthy sau khi khởi động stack.
Terminal: docker compose ps liệt kê cassandra, elasticsearch, cortex, thehive, nginx-thehive đều Up/healthy sau khi khởi động stack.
03

Cấu hình ban đầu

TheHive — Tạo admin account · Cortex — Lấy API key để kết nối TheHive · Cortex — Cài đặt Analyzers

3.1 TheHive — Tạo admin account

Truy cập https://thehive.hoatranlabs.local

Trình duyệt: https://thehive.hoatranlabs.local hiện trang đăng nhập TheHive 5, khóa HTTPS hợp lệ do step-CA cấp.
Trình duyệt: https://thehive.hoatranlabs.local hiện trang đăng nhập TheHive 5, khóa HTTPS hợp lệ do step-CA cấp.

Login lần đầu: [email protected] / secret → đổi ngay thành [email protected] / Hoatran@2024!

Tạo organisation:

  • Settings → Organisations → Add organisation: HoatranLabs
  • Tạo user: admin với role org-admin
TheHive → Organisations: tổ chức HoatranLabs vừa tạo cùng user admin với role org-admin.
TheHive → Organisations: tổ chức HoatranLabs vừa tạo cùng user admin với role org-admin.

3.2 Cortex — Lấy API key để kết nối TheHive

Truy cập http://10.11.25.11:9001 (hoặc https://cortex.hoatranlabs.local)

1
Create admin account tại first run: [email protected] / Hoatran@2024!
2
Create organisation: HoatranLabs
3
Admin → API Keys → Create → Copy key
Cortex (http://10.11.25.11:9001) → Admin → API Keys: key vừa tạo cho org HoatranLabs để thay CORTEX_API_KEY_PLACEHOLDER (che giá trị).
Cortex (http://10.11.25.11:9001) → Admin → API Keys: key vừa tạo cho org HoatranLabs để thay CORTEX_API_KEY_PLACEHOLDER (che giá trị).
4
Cập nhật key vào TheHive config:
# Sửa CORTEX_API_KEY_PLACEHOLDER bằng key thực
sed -i 's/CORTEX_API_KEY_PLACEHOLDER/<actual-cortex-key>/' \
  /opt/thehive/thehive/config/application.conf
docker compose restart thehive

3.3 Cortex — Cài đặt Analyzers

# Vào Cortex container
docker exec -it cortex bash

# Cài cortex-analyzers
pip install cortexutils
cortex-analyzer-catalogue list | grep -E "VirusTotal|Shodan|AbuseIPDB|URLScan|OTX|MaxMind"

Trong Cortex UI → Organization → Analyzers → Enable:

AnalyzerConfig cần thiết
VirusTotal_GetReportkey: VirusTotal API key
Shodan_DNSResolvekey: Shodan API key
AbuseIPDB_1_0key: AbuseIPDB API key
URLScan_Search_0_1key: URLScan.io API key
OTXQuery_2_0key: AlienVault OTX API key
MaxMind_GeoIP_3_0Tải DB file GeoLite2
Cortex → Organization → Analyzers: VirusTotal_GetReport, Shodan_DNSResolve, AbuseIPDB_1_0, URLScan_Search_0_1 đã Enable.
Cortex → Organization → Analyzers: VirusTotal_GetReport, Shodan_DNSResolve, AbuseIPDB_1_0, URLScan_Search_0_1 đã Enable.

3.4 TheHive — Cấu hình SMTP (Mailu)

TheHive 5 cấu hình SMTP trong giao diện, không đọc khối play.mailer trong application.conf (tài liệu StrangeBee chỉ mô tả cách này; application.conf chỉ giữ thông tin khởi động như secret, database, index, file storage, connector). Đăng nhập bằng tài khoản admin nền tảng (profile admin có quyền managePlatform, ví dụ [email protected] ở mục 3.1), vào Platform management (menu bên trái) → tab SMTP và nhập:

  • Server name or IP address: mailu.hoatranlabs.local
  • Port: 587
  • Send emails from: [email protected]
  • Connection security: STARTTLS (khớp cổng 587 của Mailu)
  • Username / Password: [email protected] / Noreply@Mailu2024! (mailbox noreply@ ở bài 16)

Bấm Test SMTP configuration để nhận email xác nhận. Mailu dùng cert step-CA nên JVM của TheHive phải tin cậy root CA (truststore ở mục 2.2); phải xong bước này trước khi tạo notification email ở mục 4.4.

04

Tích hợp với hạ tầng

Pi-hole DNS · Wazuh → TheHive Integration · Authentik SSO cho TheHive

4.1 Pi-hole DNS

# Thêm DNS record thehive.hoatranlabs.local và cortex.hoatranlabs.local → 10.11.25.11
# Cách 1: Pi-hole Admin UI → Settings → Local DNS Records (thêm 2 domain trên, IP: 10.11.25.11)
# Cách 2: SSH vào VM Pi-hole (chạy Docker), thêm 2 dòng add_dns "thehive.hoatranlabs.local" "10.11.25.11"
#         và add_dns "cortex.hoatranlabs.local" "10.11.25.11" vào /opt/pihole/scripts/add_dns_records.sh (Bài 12) rồi chạy lại script
ssh [email protected]

4.2 Wazuh → TheHive Integration

Wazuh chạy bằng Docker trên VM280 (Bài 17 mục 5.6; container manager single-node-wazuh.manager-1). Tạo script integration bên trong container manager (thư mục /var/ossec/integrations nằm trong volume single-node_wazuh_integrations nên được giữ lại khi container restart):

docker exec -i single-node-wazuh.manager-1 bash -c 'cat > /var/ossec/integrations/custom-thehive.py' << 'PYEOF'
#!/usr/bin/env python3
"""Wazuh → TheHive: Tạo alert khi rule level >= 10"""
import sys, json, requests, urllib3
urllib3.disable_warnings()

THEHIVE_URL = "https://thehive.hoatranlabs.local"
THEHIVE_KEY = "YOUR_THEHIVE_API_KEY"  # Tạo từ TheHive → My Profile → API Key

def send_to_thehive(alert):
    rule = alert.get("rule", {})
    level = rule.get("level", 0)
    if level < 10:
        return  # Chỉ gửi alert level 10+

    headers = {
        "Authorization": f"Bearer {THEHIVE_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "title": f"[Wazuh-L{level}] {rule.get('description', 'Unknown')}",
        "description": json.dumps(alert, indent=2),
        "type": "external",
        "source": "wazuh",
        "sourceRef": str(alert.get("id", "0")),
        "severity": 3 if level >= 14 else 2 if level >= 10 else 1,
        "tlp": 2,
        "tags": [f"wazuh", f"rule-{rule.get('id','0')}", f"level-{level}"]
    }
    resp = requests.post(
        f"{THEHIVE_URL}/api/v1/alert",
        json=payload, headers=headers, verify=False, timeout=10
    )
    resp.raise_for_status()

if __name__ == "__main__":
    try:
        alert_file = open(sys.argv[1])
        data = json.load(alert_file)
        send_to_thehive(data)
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
PYEOF

# Wazuh Integrator chỉ chạy file có tên đúng bằng <name> trong ossec.conf (ở đây: custom-thehive), nên cần
# thêm wrapper thực thi `custom-thehive` gọi script Python ở trên bằng Python nhúng của Wazuh
# (rút gọn từ wrapper chuẩn trong hướng dẫn Wazuh–TheHive)
docker exec -i single-node-wazuh.manager-1 bash -c 'cat > /var/ossec/integrations/custom-thehive' << 'SHEOF'
#!/bin/sh
WAZUH_PATH="/var/ossec"
exec "${WAZUH_PATH}/framework/python/bin/python3" "${WAZUH_PATH}/integrations/custom-thehive.py" "$@"
SHEOF

# Cả wrapper và script: thuộc root:wazuh, quyền 750 (theo tài liệu Wazuh về custom integration)
docker exec single-node-wazuh.manager-1 chmod 750 /var/ossec/integrations/custom-thehive /var/ossec/integrations/custom-thehive.py
docker exec single-node-wazuh.manager-1 chown root:wazuh /var/ossec/integrations/custom-thehive /var/ossec/integrations/custom-thehive.py

Thêm khối sau vào cấu hình manager (đặt trong <ossec_config>). Với wazuh-docker, ossec.conf của manager được mount từ host tại /opt/wazuh-docker/single-node/config/wazuh_cluster/wazuh_manager.conf (Bài 17 mục 5.6) và được copy vào container mỗi lần container khởi động — vì vậy sửa file trên host này, không sửa trực tiếp /var/ossec/etc/ossec.conf trong container:

<integration>
  <name>custom-thehive</name>
  <hook_url>https://thehive.hoatranlabs.local</hook_url>
  <level>10</level>
  <alert_format>json</alert_format>
</integration>
docker restart single-node-wazuh.manager-1
TheHive → Alerts: alert '[Wazuh-L<level>] <mô tả rule>' (level từ 10 trở lên), source wazuh, tags wazuh/rule-<id>/level-<n>, do script custom-thehive tạo sau khi restart container single-node-wazuh.manager-1.
TheHive → Alerts: alert '[Wazuh-L<level>] <mô tả rule>' (level từ 10 trở lên), source wazuh, tags wazuh/rule-<id>/level-<n>, do script custom-thehive tạo sau khi restart container single-node-wazuh.manager-1.

4.3 Authentik SSO cho TheHive

Trong Authentik (VM234):

1
Applications → Providers → Create → OAuth2/OpenID Provider
  • Name: thehive-oidc
  • Client type: Confidential
  • Redirect URIs: https://thehive.hoatranlabs.local/api/ssoLogin
  • Scopes: openid, email, profile, groups
Authentik (VM234) → Applications → Providers: provider thehive-oidc (OAuth2/OpenID, Confidential) với Redirect URI https://thehive.hoatranlabs.local/api/ssoLogin và scopes openid, email, profile, groups.
Authentik (VM234) → Applications → Providers: provider thehive-oidc (OAuth2/OpenID, Confidential) với Redirect URI https://thehive.hoatranlabs.local/api/ssoLogin và scopes openid, email, profile, groups.
2
Applications → Applications → Create (như Bài 14 mục 8.2)
  • Name: TheHive
  • Slug: thehive
  • Provider: chọn thehive-oidc vừa tạo
  • Launch URL: https://thehive.hoatranlabs.local
3
Click Create

Thêm vào /opt/thehive/thehive/config/application.conf:

# SSO via Authentik
auth {
  providers = [
    {name: session}
    {name: basic, realm: thehive}
    {name: oauth2
     clientId: "thehive-client-id"
     clientSecret: "thehive-client-secret"
     redirectUri: "https://thehive.hoatranlabs.local/api/ssoLogin"
     responseType: "code"
     grantType: "authorization_code"
     authorizationUrl: "https://authentik.hoatranlabs.local:9443/application/o/authorize/"
     tokenUrl: "https://authentik.hoatranlabs.local:9443/application/o/token/"
     userUrl: "https://authentik.hoatranlabs.local:9443/application/o/userinfo/"
     scope: ["openid", "email", "profile"]
     userIdField: "email"
     userOrganisation: "HoatranLabs"
    }
  ]
}

4.4 Mailu — Email notifications

Sau khi SMTP đã test OK (mục 3.4), đăng nhập bằng org-admin, vào Organization (menu bên trái) → tab Notifications → nút thêm (+):

  • Name: High alert email (tên phải duy nhất)
  • Trigger: AlertCreated; muốn chỉ gửi khi severity >= High thì chọn FilteredEvent và nhập JSON filter theo severity (cú pháp xem "Write a FilteredEvent trigger" của StrangeBee)
  • Notifier: EmailToAddr, To: [email protected] (mailbox có sẵn ở bài 16); bật Enable notification rồi Confirm
TheHive → Organization → Notifications: notifier EmailToAddr gửi tới admin@hoatranlabs.local, trigger AlertCreated (hoặc FilteredEvent lọc severity >= High).
TheHive → Organization → Notifications: notifier EmailToAddr gửi tới [email protected], trigger AlertCreated (hoặc FilteredEvent lọc severity >= High).

4.5 Prometheus Monitoring

# Custom exporter đơn giản — cronjob ghi metrics
cat > /usr/local/bin/thehive-exporter.sh << 'EOF'
#!/bin/bash
# Lấy case/alert metrics từ TheHive API
API="https://thehive.hoatranlabs.local/api/v1"
KEY="YOUR_THEHIVE_API_KEY"
METRIC_FILE="/var/lib/prometheus/node-exporter/thehive.prom"

OPEN_CASES=$(curl -sf -H "Authorization: Bearer $KEY" "$API/case?status=Open" | jq 'length' 2>/dev/null || echo 0)
NEW_ALERTS=$(curl -sf -H "Authorization: Bearer $KEY" "$API/alert?status=New" | jq 'length' 2>/dev/null || echo 0)

cat > "$METRIC_FILE" << PEOF
# HELP thehive_open_cases Number of open cases
# TYPE thehive_open_cases gauge
thehive_open_cases $OPEN_CASES
# HELP thehive_new_alerts Number of new unprocessed alerts
# TYPE thehive_new_alerts gauge
thehive_new_alerts $NEW_ALERTS
PEOF
EOF
chmod +x /usr/local/bin/thehive-exporter.sh
echo "*/5 * * * * root /usr/local/bin/thehive-exporter.sh" >> /etc/cron.d/thehive-exporter
# prometheus.yml scrape (VM235):
  - job_name: 'thehive-node'
    static_configs:
      - targets: ['10.11.25.11:9100']
    relabel_configs:
      - target_label: instance
        replacement: thehive-vm270

4.6 PBS Backup

# Cài proxmox-backup-client (bản static, không phụ thuộc glibc của Ubuntu 24.04) từ client-only repository công khai của Proxmox.
# Suite "trixie" là suite có bản static mới nhất (đã kiểm repo ngày 2026-10-15); chạy trên noble: cần kiểm lại trên máy thật
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
  -O /usr/share/keyrings/proxmox-archive-keyring.gpg
cat > /etc/apt/sources.list.d/pbs-client.sources << 'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt install -y proxmox-backup-client-static

# Token + namespace tạo sẵn theo Bài 04 mục 5.7 (user vm-backup@pbs, token "thehive",
# ACL DatastoreBackup tại /datastore/syno-primary/vm-thehive)
export PBS_PASSWORD='<TOKEN_SECRET>'   # secret của token vm-backup@pbs!thehive

# Mẫu --exclude tính theo gốc của archive (/opt/thehive), không phải đường dẫn tuyệt đối trên hệ thống:
# /cassandra/data = /opt/thehive/cassandra/data (dấu / đầu mẫu = neo tại /opt/thehive)
proxmox-backup-client backup \
  thehive-config.pxar:/opt/thehive \
  --exclude /cassandra/data \
  --exclude /elasticsearch/data \
  --repository 'vm-backup@[email protected]:syno-primary' \
  --ns vm-thehive

# Cassandra backup riêng (snapshot)
docker exec cassandra nodetool snapshot thehive
05

Kiểm tra & Xác minh

# 1. Tất cả containers healthy
cd /opt/thehive && docker compose ps

# 2. TheHive API health
curl -sf https://thehive.hoatranlabs.local/api/v1/status | jq '.versions'

# 3. Cortex health
curl -sf http://10.11.25.11:9001/api/status | jq '.status'

# 4. Test tạo alert thủ công
curl -XPOST https://thehive.hoatranlabs.local/api/v1/alert \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Alert","type":"external","source":"test","sourceRef":"test-001","severity":2}'

# 5. Cassandra health
docker exec cassandra nodetool status

# 6. Elasticsearch health (compose không publish cổng 9200 ra host nên kiểm tra từ trong container)
docker exec elasticsearch curl -sf http://localhost:9200/_cluster/health | jq '.status'

# 7. Kiểm tra Cortex analyzers
curl -H "Authorization: Bearer <cortex-api-key>" \
  http://10.11.25.11:9001/api/analyzer | jq '.[].name'
Terminal: docker compose ps, curl /api/v1/status, Cortex /api/status, nodetool status và ES cluster health trả kết quả OK.
Terminal: docker compose ps, curl /api/v1/status, Cortex /api/status, nodetool status và ES cluster health trả kết quả OK.
06

Troubleshooting

Vấn đềNguyên nhânGiải pháp
TheHive không kết nối CassandraCassandra chưa fully readyChờ 90s sau khi start, check docker logs cassandra
Elasticsearch healthcheck failedvm.max_map_count thấpsysctl -w vm.max_map_count=262144
TheHive lỗi 502 Bad GatewayContainer thehive chưa start xongChờ 3-5 phút, check docker logs thehive
Cortex không chạy được analyzerDocker socket không mountVerify /var/run/docker.sock trong compose
Cortex analyzer báo lỗi kiểu client version ... is too old khi gọi DockerDocker Engine 29.0–29.2 chỉ nhận API từ 1.44; từ 29.3 mức tối thiểu hạ về 1.40 (release notes Docker 29). Client Docker trong Cortex 3.1.8 dùng API nào thì chưa kiểmRepo noble hiện là 29.9.1 nên thường không gặp. Nếu gặp: docker version xem mức tối thiểu của daemon, docker logs cortex; cần kiểm lại trên máy thật (tra biến DOCKER_MIN_API_VERSION trong release notes Docker 29)
OIDC login không redirect đúngRedirect URI mismatchKiểm tra Authentik provider redirect URI
Wazuh alert không tạo caseScript permission, API key saiTest thủ công script custom-thehive.py, check ossec.log (docker exec single-node-wazuh.manager-1 tail -n 50 /var/ossec/logs/ossec.log)
Cortex analyzer timeoutAPI key ngoài sai hoặc hết quotaKiểm tra VirusTotal/Shodan quota
OutOfMemory CassandraHeap quá thấpTăng MAX_HEAP_SIZE env, thêm RAM cho VM

Checklist triển khai

  • VM270 tạo thành công, IP 10.11.25.11, VLAN 25
  • vm.max_map_count=262144 persistent trong /etc/sysctl.conf
  • TLS cert cho thehive.hoatranlabs.local và cortex.hoatranlabs.local
  • Tất cả containers: cassandra, elasticsearch, cortex, thehive, nginx — UP healthy
  • TheHive UI truy cập được tại https://thehive.hoatranlabs.local
  • Cortex UI truy cập được tại https://cortex.hoatranlabs.local
  • Organisation HoatranLabs tạo trong cả TheHive và Cortex
  • Cortex API key kết nối vào TheHive thành công
  • Analyzers: VirusTotal, AbuseIPDB, Shodan, URLScan enable và test OK
  • Wazuh integration script deploy, test alert tạo case trong TheHive
  • Authentik SSO login vào TheHive hoạt động
  • DNS records: thehive.hoatranlabs.local, cortex.hoatranlabs.local
  • SMTP (Platform management → SMTP) test OK; Mailu email notification khi alert mức High
  • Prometheus scrape node_exporter VM270
  • PBS backup chạy thành công

Cập nhật: 2026-10-15 (Ubuntu Server 24.04 LTS)

Zalo