Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(container): forward signals after privilege drop

Yudhi Armyndharis2a4b92236847
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f9db9eb5..710203a94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- Forward container shutdown signals after dropping process privileges in Compose and Helm.
- Preserve webhook outbox payloads until delivery or durable failure storage succeeds.
- Enforce webhook replay retention and keep later eligible failures moving through batches.
- Keep one terminal webhook failure per receiver idempotency key.
diff --git a/charts/openwa/values.yaml b/charts/openwa/values.yaml
index fe23dc8ca..41bd573fe 100644
--- a/charts/openwa/values.yaml
+++ b/charts/openwa/values.yaml
@@ -107,14 +107,14 @@ terminationGracePeriodSeconds: 45
# fsGroup is what makes a fresh volume writable by it. OnRootMismatch makes the
# kubelet re-own the volume only when its root has the wrong group or mode,
# instead of touching every file on every mount. `add: null` removes the
-# default list below; Helm merges maps, so leaving it out keeps all five.
+# default list below; Helm merges maps, so leaving it out keeps all six.
# The RuntimeDefault seccomp profile is opt-in (it can also be set alone,
# under either context) until a whatsapp-web.js session start under it has
# been confirmed on arm64, where the image uses Debian's Chromium.
podSecurityContext: {}
-# Parity with docker-compose hardening. The five added capabilities are used
-# only by the root entrypoint (chown, then the gosu drop); see
+# Parity with docker-compose hardening. The added capabilities support
+# the root entrypoint and init signal forwarding after the gosu drop; see
# podSecurityContext above for the non-root alternative.
containerSecurityContext:
readOnlyRootFilesystem: true
@@ -126,6 +126,7 @@ containerSecurityContext:
- CHOWN
- DAC_OVERRIDE
- FOWNER
+ - KILL
- SETGID
- SETUID
diff --git a/docker-compose.yml b/docker-compose.yml
index 858527745..c0a6e4b11 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -62,7 +62,7 @@ services:
- internal-docker
# Container hardening: Chromium runs with --no-sandbox, so the
# container itself is the confinement boundary. cap_drop ALL + a minimal re-add
- # ONLY for the root entrypoint's chown + gosu privilege-drop; once gosu setuids to
+ # for root entrypoint ownership, the gosu drop and init signal forwarding. Once gosu setuids to
# the openwa user the node/Chromium process keeps NO effective capabilities.
# read_only rootfs (Chromium's profile lives on the writable /app/data volume;
# HOME=/tmp + tmpfs absorb stray writes). no-new-privileges blocks setuid escalation.
@@ -74,6 +74,7 @@ services:
- CHOWN # entrypoint: chown openwa /app/data on the named volume
- DAC_OVERRIDE # entrypoint: chown across pre-existing files
- FOWNER
+ - KILL # dumb-init: forward signals to the openwa process after gosu drops uid
- SETGID # gosu: drop to the openwa group
- SETUID # gosu: drop to the openwa user
read_only: true
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 81a69c3b7..fe4579c2e 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1167,8 +1167,9 @@ npm run migration:run:main:prod # inside the released image
By default the entrypoint starts as root, re-owns `/app/data` to the `openwa` user (uid/gid 997) on
every start, and then drops privileges with `gosu`. Keep that path intact:
-- Keep the `CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `SETGID` and `SETUID` entries under `cap_add` in
- `docker-compose.yml`; the `chown` and the `gosu` drop need them.
+- Keep the `CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `KILL`, `SETGID` and `SETUID` entries under `cap_add` in
+ `docker-compose.yml`; the entrypoint needs ownership and privilege-drop permissions, and
+ `dumb-init` needs `KILL` to forward shutdown signals to the process after its UID changes.
- Setting `user:` on `openwa-api` (or `--user` on `docker run`) starts the entrypoint as that uid
instead. It then skips the `chown` and the drop, so `/app/data` must already be writable by that
uid: `user: "997:997"` works on a volume a root start has already re-owned, and the `cap_add` list
diff --git a/scripts/check-chart-behaviour.mjs b/scripts/check-chart-behaviour.mjs
index 94c99cdc3..f3a475445 100644
--- a/scripts/check-chart-behaviour.mjs
+++ b/scripts/check-chart-behaviour.mjs
@@ -195,6 +195,8 @@ const check = (id, ok, detail) => results.push({ id, ok, detail });
const problems = [
podContext(byDefault) && 'the default render sets a pod securityContext',
!addsCaps(byDefault) && 'the default render lost the capabilities the root entrypoint needs',
+ !/^ {14}- KILL$/m.test(byKind(byDefault, 'StatefulSet')[0] ?? '') &&
+ 'the root init cannot forward shutdown signals after the privilege drop',
!/runAsNonRoot: true/.test(pod) && 'podSecurityContext.runAsNonRoot does not reach the pod spec',
!/fsGroup: 997/.test(pod) && 'podSecurityContext.fsGroup does not reach the pod spec',
// Without it the kubelet re-owns every file on the volume on every mount before the pod starts.
diff --git a/scripts/smoke-test-non-root.sh b/scripts/smoke-test-non-root.sh
index 79e04524f..d637321e2 100755
--- a/scripts/smoke-test-non-root.sh
+++ b/scripts/smoke-test-non-root.sh
@@ -22,9 +22,13 @@ else
fi
VOL=""
+SIGNAL_CONTAINER=""
# Only remove an image this script created — never one the caller handed us.
cleanup() {
+ if [ -n "$SIGNAL_CONTAINER" ]; then
+ docker rm -f "$SIGNAL_CONTAINER" > /dev/null 2>&1 || true
+ fi
if [ -n "$VOL" ]; then
docker volume rm -f "$VOL" > /dev/null 2>&1 || true
fi
@@ -65,6 +69,37 @@ else
exit 1
fi
+echo ""
+echo "==> Checking signal forwarding with Compose capabilities..."
+CAPS=$(docker run --rm -i --entrypoint node "$IMAGE_TAG" -e \
+ 'const fs=require("fs"),yaml=require("js-yaml");console.log(yaml.load(fs.readFileSync(0,"utf8")).services["openwa-api"].cap_add.join(" "))' < docker-compose.yml)
+set --
+for cap in $CAPS; do
+ set -- "$@" --cap-add "$cap"
+done
+SIGNAL_CONTAINER=$(docker run -d --read-only --tmpfs /tmp --cap-drop ALL "$@" \
+ --security-opt no-new-privileges "$IMAGE_TAG" node -e \
+ 'const fs=require("fs");if(process.getuid()!==997||!/^CapEff:\s+0+$/m.test(fs.readFileSync("/proc/self/status","utf8")))process.exit(1);process.on("SIGTERM",()=>process.exit(0));console.log("signal-ready");setInterval(()=>{},1000)')
+for attempt in 1 2 3 4 5; do
+ if docker logs "$SIGNAL_CONTAINER" | grep -q '^signal-ready$'; then
+ break
+ fi
+ if [ "$attempt" -eq 5 ]; then
+ echo "FAIL: the non-root signal test did not become ready" >&2
+ exit 1
+ fi
+ sleep 1
+done
+docker stop --time 5 "$SIGNAL_CONTAINER" > /dev/null
+SIGNAL_EXIT=$(docker inspect --format '{{.State.ExitCode}}' "$SIGNAL_CONTAINER")
+if [ "$SIGNAL_EXIT" != 0 ]; then
+ echo "FAIL: the unprivileged process did not receive SIGTERM (exit $SIGNAL_EXIT)" >&2
+ exit 1
+fi
+echo "PASS: init forwards SIGTERM and the non-root process has no effective capabilities"
+docker rm "$SIGNAL_CONTAINER" > /dev/null
+SIGNAL_CONTAINER=""
+
echo ""
echo "==> Checking /app/data ownership on start..."
VOL="openwa-smoke-data-$$"