TheHive 5 + Cortex SOAR
Incident response platform — tích hợp Wazuh alerts, auto-analyze IoCs.
Bối cảnh & Lý do triển khai
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ục | Nội dung |
|---|---|
| Ứng dụng trong doanh nghiệp | Incident response workflow, IoC enrichment tự động, case tracking |
| Tác dụng chính | Không bỏ sót alert, có audit trail đầy đủ, analyst có context trước khi respond |
| Nếu không triển khai | Alert từ Wazuh/CrowdSec chìm vào log, không có incident tracking |
| Các service phụ thuộc vào đây | Wazuh 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ủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| thehive (TheHive + Cortex) · VM270 | 10.11.25.11 | 25 (SEC) · node2 | Má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.211 | 45 (MGMT) · cluster HOATRANHUB | Node 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) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | Là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) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấ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) · VM280 | 10.11.45.25 | 45 (MGMT) · node1 | Nguồ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) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhà 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) · VM246 | 10.11.35.46 | 35 (DMZ) · node2 | Relay 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) · VM235 | 10.11.45.35 | 45 (MGMT) · node2 | Scrape 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) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Nhậ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.16 | 45 (MGMT) · NAS | NAS 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ị |
|---|---|
| VMID | 270 |
| Hostname | thehive |
| IP | 10.11.25.11/24 |
| Gateway | 10.11.25.1 |
| VLAN | 25 (VLAN_SEC) |
| vCPU | 4 |
| RAM | 8 GB |
| Disk | 50 GB (scsi0, SSD vm-ceph) |
| OS | Ubuntu Server 24.04 LTS |
| Phân bổ node | node2 |
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ần | Phiên bản | Ghi chú |
|---|---|---|
| Hệ điều hành | Ubuntu 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 Engine | docker-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). |
| TheHive | 5.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. |
| Cortex | 3.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 / Nginx | cassandra: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-cli | 0.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_exporter | 1.12.1 | Cài theo script bài 15, đổi biến phiên bản; cổng 9100. |
| proxmox-backup-client | proxmox-backup-client-static 4.x, repo pbs-client suite trixie | Bả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). |
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)
- VM ID:
270 - Name:
thehive - Bỏ tick Start after created
- 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
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph - Disk size:
50 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:4, Type:x86-64-v2-AES
- Memory (MiB):
8192
- Bridge:
vmbr0, VLAN Tag:25, Model:VirtIO (paravirtualized), Firewall: ☐
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
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
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
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
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)
[email protected] / Hoatran@2024!HoatranLabs
# 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:
| Analyzer | Config cần thiết |
|---|---|
| VirusTotal_GetReport | key: VirusTotal API key |
| Shodan_DNSResolve | key: Shodan API key |
| AbuseIPDB_1_0 | key: AbuseIPDB API key |
| URLScan_Search_0_1 | key: URLScan.io API key |
| OTXQuery_2_0 | key: AlienVault OTX API key |
| MaxMind_GeoIP_3_0 | Tải DB file GeoLite2 |
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!(mailboxnoreply@ở 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.
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
4.3 Authentik SSO cho TheHive
Trong Authentik (VM234):
- Name:
thehive-oidc - Client type: Confidential
- Redirect URIs:
https://thehive.hoatranlabs.local/api/ssoLogin - Scopes: openid, email, profile, groups
- Name:
TheHive - Slug:
thehive - Provider: chọn
thehive-oidcvừa tạo - Launch URL:
https://thehive.hoatranlabs.local
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ọnFilteredEventvà 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
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
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'
Troubleshooting
| Vấn đề | Nguyên nhân | Giải pháp |
|---|---|---|
| TheHive không kết nối Cassandra | Cassandra chưa fully ready | Chờ 90s sau khi start, check docker logs cassandra |
Elasticsearch healthcheck failed | vm.max_map_count thấp | sysctl -w vm.max_map_count=262144 |
TheHive lỗi 502 Bad Gateway | Container thehive chưa start xong | Chờ 3-5 phút, check docker logs thehive |
| Cortex không chạy được analyzer | Docker socket không mount | Verify /var/run/docker.sock trong compose |
Cortex analyzer báo lỗi kiểu client version ... is too old khi gọi Docker | Docker 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ểm | Repo 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 đúng | Redirect URI mismatch | Kiểm tra Authentik provider redirect URI |
| Wazuh alert không tạo case | Script permission, API key sai | Test 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 timeout | API key ngoài sai hoặc hết quota | Kiểm tra VirusTotal/Shodan quota |
| OutOfMemory Cassandra | Heap quá thấp | Tă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=262144persistent 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)