soc/docs/ops-runbook-...

Runbook: IRIS Admin API Key — Keep It Static

Problem

When the iriswebapp_app container is recreated, post_init.py runs on startup and sets the administrator's API key. If IRIS_ADM_API_KEY is not set in the env, it generates a new random key via secrets.token_urlsafe(nbytes=64). This breaks the soc-integrator (HTTP 401 / 502) until the key is manually re-synced.

Root cause: iris-web/.env line IRIS_ADM_API_KEY was commented out → random rotation on every container recreate.

Fix already applied (2026-03-23)

iris-web/.env now has IRIS_ADM_API_KEY explicitly set to the current live key. post_init.py reads this env var and reuses it on every startup — no more rotation.

---

If the key ever needs to be reset (e.g. suspected compromise)

Step 1 — Choose or generate a new key

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

Note the output — this is <NEW_KEY>.

Step 2 — Update iris-web/.env

# Edit the file
vi /home/tum/soc/iris-web/.env

Find and update the line:

IRIS_ADM_API_KEY=<NEW_KEY>

Step 3 — Update soc-integrator

vi /home/tum/soc/soc-integrator/.env

Set:

IRIS_API_KEY=<NEW_KEY>

Step 4 — Recreate both containers

# IRIS app (re-runs post_init.py with new key)
cd /home/tum/soc/iris-web
docker compose up -d --force-recreate app

# soc-integrator (bakes new IRIS_API_KEY into container env)
cd /home/tum/soc/soc-integrator
docker compose up -d --force-recreate

Note: docker restart does NOT re-read .env — you must use --force-recreate.

Step 5 — Verify

# 1. Confirm key in DB matches what you set
docker exec iriswebapp_db psql -U postgres -d iris_db \
  -c "SELECT api_key FROM \"user\" WHERE name='administrator';"

# 2. End-to-end sync test
cd /home/tum/soc
python3 scripts/test-wazuh-iris-sync.py --no-send --minutes 60
# Expected: all steps pass

---

Diagnosing a broken key (soc-integrator returning 502 / 401)

# Check integrator logs
docker logs soc-integrator --tail=50 | grep -i "iris\|401\|502"

# Read current key from IRIS DB
docker exec iriswebapp_db psql -U postgres -d iris_db \
  -c "SELECT api_key FROM \"user\" WHERE name='administrator';"

# Compare with what soc-integrator has baked in
docker exec soc-integrator env | grep IRIS_API_KEY

# If they differ → follow steps 2-5 above (no need to generate a new key,
# just re-sync the existing DB key into the two .env files)

---

Service key inventory (all static as of 2026-03-23)

Service	Credential	Location
IRIS admin API key	IRIS_ADM_API_KEY in iris-web/.env	Set statically; reused by post_init.py
IRIS API key (integrator side)	IRIS_API_KEY in soc-integrator/.env	Must match IRIS DB value
Wazuh API	wazuh-wui / password	wazuh-docker/single-node/docker-compose.yml env block
Wazuh Indexer	admin / password	Same compose file
Shuffle API key	SHUFFLE_API_KEY	Shuffle/.env + soc-integrator/.env
Integrator internal key	INTERNAL_API_KEY	soc-integrator/.env