[OisinKyne]

Problem

jwt/jwt.hex was tracked in this repo, so every deployment used the same, public Engine API secret. The Engine API port (8551) is published on 127.0.0.1 by default and is reachable by every container on the compose network, so anyone who can reach it could drive the execution client.

Change

• A one-shot jwt-init service (busybox, no network) generates 32 random bytes from /dev/urandom as 64 hex characters, with no 0x and no newline, into a jwt Docker volume. It writes to a temporary file and renames it, and never replaces an existing secret.
• Every execution and consensus client service (nethermind, lighthouse, el-nethermind, el-reth, cl-grandine, cl-lighthouse, cl-teku, cl-lodestar, cl-prysm, cl-nimbus) wait for it (depends_on: service_completed_successfully) and mount the volume read-only at the path they used before.
• The secret is in a named volume rather than ./jwt, so no host user can read it without root. Inside the volume it is 0444 root:root: Teku and Nimbus run as UID 1000 and the other clients as root, so no single owner or mode below world-readable works without changing users, and only these clients mount the volume.
• An operator-provided jwt/jwt.hex (for an execution client outside the stack) is loaded into the volume instead. It must be one line of 64 hex characters, otherwise jwt-init fails and the clients do not start. The old public secret is ignored if it is left there.
• jwt/jwt.hex is deleted from git and ignored. README and CLAUDE.md updated.

Upgrade behaviour

• git pull and docker compose up -d, as documented. The changed mount makes compose recreate the execution and consensus clients, and both start with the new secret. The secret is rotated on purpose.
• Between git pull and docker compose up -d the old containers keep running on the old secret, which they hold in memory. If one of them restarts in that window it finds no file: Nethermind, Reth and Lighthouse then write their own, the others exit. The pair recovers on docker compose up -d, and a file written this way is loaded like an operator-provided one.
• git pull refuses to run if jwt/jwt.hex was changed locally. The README says what to do.
• Anything outside the stack that used the old secret (an external consensus or execution client) must be given the new one: docker compose run --rm jwt-init cat /jwt/jwt.hex.

Testing

Done, without Docker:

• All compose files parse. A script checked that every service that passes a JWT flag depends on jwt-init, mounts the jwt volume read-only at the directory its flag points to, and that nothing else mounts ./jwt.
• .github/scripts/check_exposure.py passes.
• The jwt-init script was run under dash with GNU tools for: first run, re-run, stale temporary file, own secret (plain, 0x and newline, mode 0600), old public secret, and invalid files (short, CRLF, two lines, empty).
• Image users were read from the registry configs of the pinned tags: Teku and Nimbus are UID 1000, the rest root.
• git pull over a clean and a locally changed jwt/jwt.hex was simulated with a toy repo.

Not done:

• Nothing was run under Docker. Not tested: the script under busybox ash and its applets (od -An -tx1 -v -N32, grep -x, cmp -s), that compose recreates both clients on upgrade, that each client reads the secret from the volume, Docker Desktop, rootless Docker and podman.

Manual test checklist

On a Linux Docker host, with .env from .env.sample.hoodi:

• Fresh install: docker compose up -d. docker compose logs jwt-init says Generated a new Engine API secret, docker compose ps -a jwt-init shows exit 0, and docker compose run --rm jwt-init ls -ln /jwt shows -r--r--r-- ... 0 0 64 ... jwt.hex. jwt/ holds only .gitkeep and git status is clean. The consensus client reports the execution client as online.
• Re-run and restart: note docker compose run --rm jwt-init sha256sum /jwt/jwt.hex. It is unchanged, and the clients are not recreated, after docker compose up -d, after docker compose restart, and after docker compose down && docker compose up -d. After docker compose down -v && docker compose up -d it is different and the clients connect.
• Upgrade: start from main with the clients connected. git pull this branch: the containers keep running. docker compose up -d recreates the execution and consensus clients, they connect, and the secret is not 7074a5bf....
• Upgrade with a changed jwt/jwt.hex: git pull refuses. Follow the README. jwt-init logs Loaded the Engine API secret from jwt/jwt.hex and the volume holds that secret.
• Old public secret left in jwt/jwt.hex: jwt-init logs Ignoring jwt/jwt.hex and a new secret is generated.
• Invalid jwt/jwt.hex (for example echo zz > jwt/jwt.hex): jwt-init exits 1 with a message and the clients are not started.
• Each profile: EL=el-nethermind and EL=el-reth, each with CL=cl-lighthouse, cl-grandine, cl-teku, cl-lodestar, cl-prysm and cl-nimbus. The consensus client starts, reads the secret and reports the execution client as online. Teku and Nimbus matter most, as they do not run as root. Also the default services with no .env (nethermind, lighthouse).
• Permissions: docker compose exec <el> touch /root/jwt/x fails (read-only). A non-root host user cannot read /var/lib/docker/volumes/<project>_jwt/_data/jwt.hex.
• If available: repeat the fresh install on Docker Desktop (macOS or Windows) and on rootless Docker.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud