yorickdowne/eth-docker-audit.md

## eth-docker-audit.md

      
    Raw
  

              eth-docker-audit.md
            
          
    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 https://eth-docker.net
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
Attackers

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.
Audit

Assumptions

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.
Scope

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.
Re-audit

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.