Skip to content

Instantly share code, notes, and snippets.

Created November 13, 2022 14:07
Show Gist options
  • Save yorickdowne/ebd82c3c43520811ee9b289efc0efe78 to your computer and use it in GitHub Desktop.
Save yorickdowne/ebd82c3c43520811ee9b289efc0efe78 to your computer and use it in GitHub Desktop.
Eth-docker audit notes

eth-docker informal specification

User behavior and threat model

A typical user of eth-docker is someone who wants to become a validator on the Ethereum network, also known as staking or staker, or someone who is already a validator on the Ethereum network and wants to add more validators to their setup. They can be someone who is going to setup their machine at home, someone who is going to use some kind of VPS to host their setup, or some kind of institutional staker working for large staking services or large investors.

eth-docker is an automation wrapper to run an "Ethereum node", consisting of a consensus layer client, execution layer client, and validator client. A high-level overview as well as full documentation is at

eth-docker uses the client team's docker images or source code, as chosen by the user of eth-docker. It then builds local docker images that ensure that all clients are run as a "non-root" user, and adds an entrypoint script to handle optional components such as MEV, checkpoint sync, additional user-chosen parameters.

Users can, optionally on Ethereum mainnet and by default on Ethereum testnet, use eth-docker to create validator keys. Doing so is discouraged on mainnet, where users should use an air-gapped machine to create their mnemonic. eth-docker encourages setting a withdrawal address during key generation, but does not enforce this.

When a user has imported their validator signing key, it and its password are kept in a docker volume accessible by the validator client, or in the case of combined consensus layer/validator clients such as Teku and Nimbus, by the combined client.

Access to the validator signing key and its password would allow a malicious actor to cause a "slashing event" for the validator. It would not get them access to the ETH balance of the validator.

Malicious actors

Here is a short list of the different malicious actors that could potentially be involved in undesirable behaviors from the user’s perpective.

The eth-docker developers

We want to prevent or mitigate the ability of any developer working on eth-docker from accessing the keystore file(s) and their passwords.

Ethereum client and tool developers

If a client's code is compromised, the validator signing key can be exfiltrated


We want to prevent or mitigate the ability of an attacker to gain access to the validator signing key, even in the event of a remote exploit in one of the Ethereum clients

Upstream dependencies

As an automation wrapper, eth-docker is entirely dependent on code developed upstream by the Ethereum client teams.

For monitoring, it uses 3rd-party dependencies such as prometheus, grafana, node exporter. These are optional.

Key handling

eth-docker interfaces with the Ethereum key manager API, implemented by the Ethereum clients, to import or delete validator signing keys. It uses the same API to set and delete individual fee recipient and gas limit on a per-key basis.

A legacy keyy import method using the Ethereum client's CLI is also present.

Design and threat mitigations

eth-docker builds a local docker image, either from the published image of the Ethereum client, or from its published source on github. This local image uses a non-root user, even where the published image uses root.

To contain possible exploits, the execution layer client uses ID 10001, the consensus layer client uses ID 10002, and the validator client uses ID 10000. These run in separate containers. An attacker who, for example, gains access to the execution layer client through its publicly available protocols, would need to escape the container and get root access to the host in order to be able to read the validator signing key.

For Teku and Nimbus in particular, the threat model is different, as they combine the consensus layer and validator clients: A successful remote compromise of the consensus layer client would give an attacker access to the validator signing keys.



The machine that eth-docker is running on has not been compromised. If someone has root or docker group access to the host machine itself, there is no further mitigation possible.


Security of the validator key

Compare security of the validator key when the validator client is run by eth-docker to security of the validator key when the validator client is run by systemd or the client team's docker image without the use of eth-docker

Pay attention to security of key import.

Out of scope

Security of the validator client itself regarding its handling of validator keys, we're not auditing the clients. We are auditing the tool that runs the clients.


Please indicate which changes in eth-docker would trigger the need for a re-audit. eth-docker undergoes frequent changes in reaction to changes in the clients. It's desirable to clearly identify the type of change that would require a re-audit.

Copy link

Saw your post, here are some additional stuff, can provide a lot more info if you would like. most o this comes from issues we have had at Manifold Finance.


UIDs below 10,000 are a security risk, as a container breakout could result in the container being ran as a more privileged user on the host kernel with the same UID.

Static GID/UID is also useful for chown'ing files outside the container where such a user does not exist as indicated by your use case for keys.

Client teams do not use any sort of BOM/sin releases, let alone provide sha256 sums.

There are more , example is golang cache modules thru google, when buildtime comes we turn that off.


Supply chain Levels for Software Artifacts, or SLSA (salsa)

The initial v0.1 specification is out and is now ready to be tried out and tested.
They also released a set of tools and services to generate SLSA 1-2 provenance Read more about it here

Host Machine

Setup the host machine correctly, as an example NTP is typically not conf. correctly.

Disable SSH access to container. At Manifold we use Talos Linux, only access is by API.

pathological cases

Intel Nehalem chips can be subject to sporadic pauses in certain circumstances
The issue is related to aggressive power-saving optimizations introduced in Intel chips.

i.e your system may freeze for periods as small as 1/10 of a second and as much as 30 seconds.

see why power saving is not your friend

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment