D4C

Malicious version of Geth for fuzzing the devp2p protocols of ethereum.

Getting Started

Setup a private network with Kurtosis

To start fuzzing the ethereum network you will first need a private network. If you don't already have one, follow the instructions below.

First install kurtosis and docker by following the instructions on kurtosis docs

Once this is done, create a "network_params.json" configuration file. Here's an example configuration file to launch a network with two nodes: Geth/lighthouse and Besu/lighthouse

network_params.json

{
  "participants": [
      {
          "el_type": "geth",
          "el_image": "ethereum/client-go:latest",
          "cl_type": "lighthouse",
          "cl_image": "sigp/lighthouse:latest",
          "count": 1
      },
      {
          "el_type": "besu",
          "el_image": "hyperledger/besu:develop",
          "cl_type": "lighthouse",
          "cl_image": "sigp/lighthouse:latest",
          "count": 1
      }
  ],
  "launch_additional_services": false
}

You can view all the options for the configuration file (useful if you want to choose or add other implementations or activate service/monitoring tools) here :

https://github.com/kurtosis-tech/eth2-package#configuration

Run the command :

kurtosis run --enclave myTestnet github.com/kurtosis-tech/ethereum-package "$(cat ./network_params.json)"

You can replace "myTestnet" with the name of your choice and replace "./network_params.json" with the path and name of your configuration file.

After running the command and installation is done, your private network should be available and running in the background.

For more information and more commands check the Kurtosis docs

Launch fuzz test with the devp2p cli

If you don't already have GO installed, go to GO website and follow the installation instructions.

Build D4C on Linux and Mac

Start by cloning the repo and go to the root of the project and run the command :

make all

Build D4C on Windows

Coming soon...

Once you have built the project you can now run fuzz tests by going to the root of the project and running devp2p binaries followed by the appropriate command:

./build/bin/devp2p

You can find out more about the commands available to launch different fuzz tests, as well as the options, in the Command list section and explanations of the fuzzers in the Fuzzers section.

Automatic fuzz test with kurtosis configuration file

If you don't already have GO installed, go to GO website and follow the installation instructions.

Build D4C on Linux and Mac

Start by cloning the repo and go to the root of the project and run the command :

make all

then build the docker image with the command :

docker build . -t d4c:local

Build D4C on Windows

Coming soon...

Once you have built the docker image you can now run fuzz tests by specify the d4c image in the config and adding environment variables with the value "on" to the kurtosis config file like :

"el_type": "d4c:local"
"el_extra_env_vars": {
                "OPTION_NAME": "on",
            },

You can find out more about the environment variables available to launch different fuzz tests, in the Options list section and explanations of the fuzzers in the Fuzzers section.

Command list :

Wrong Version field ping

- Usage : Sends ping to a node with a wrong version field

./build/bin/devp2p discv4 wrong-version-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Wrong To field ping

- Usage : Sends ping to a node with a wrong To field

./build/bin/devp2p discv4 wrong-to-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Wrong From field ping

- Usage : Sends ping to a node with a wrong From field

./build/bin/devp2p discv4 wrong-from-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Extra Data ping

- Usage : Sends ping to a node with fuzzed extra data

./build/bin/devp2p discv4 extra-data-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Notes :

The command send two extra data fields by default, the choice of the number of additional fields will be added soon.

Wrong From field and Extra Data ping

- Usage : Sends ping to a node with fuzzed extra data and a wrong From field

./build/bin/devp2p discv4 wrong-from-extra-data-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Notes :

The command send two extra data fields by default, the choice of the number of additional fields will be added soon.

Rlpx Wrong Auth Version ping

- Usage : Sends a rlpx ping to a node with a auth wrong version field

./build/bin/devp2p rlpx wrong-version-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Rlpx Wrong Resp Version ping

- Usage : Sends a rlpx ping to a node with a resp wrong version field

./build/bin/devp2p rlpx wrong-resp-version-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

RlpxBigAuth ping

- Usage : ping node with a big auth version

./build/bin/devp2p rlpx big-auth-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

RlpxExtraData Auth

- Usage : ping node with extra data in auth-body

./build/bin/devp2p rlpx extra-data-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

RlpxExtraData Resp

- Usage : ping node with extra data in ack-body

./build/bin/devp2p rlpx extra-data-resp-ping <node> <fuzzer-name> <run> <string-to-mutate>

Args information :

node : enode adress of the node you want to ping
fuzzer-name : name of the fuzzer you want to use
run : indicate the number of fuzz test you want to run
string-to-mutate : required if you want to use the mutation-fuzzer, enter the string that you want to mutate.

Available fuzzers :

random-fuzzer
mutation-fuzzer
string-fuzzer

Option list :

Random Status

- Usage : Sends a eth wire protocol Status message (0x00) with fuzzed data

"FUZZING_STATUS": "on"

Big Status

- Usage : Sends a eth wire protocol Status message (0x00) with additional data and extra fields

"BIG_STATUS": "on"

Notes :

The fuzzer send two extra data fields by default, the choice of the number of additional fields will be added soon.

Random NewBlockHashes

- Usage : Sends a eth wire protocol NewBlockHashes (0x01) with random and fuzzed hashes and random numbers

"FUZZING_NEWBLOCKHASHES": "on"

Notes :

The fuzzer send 10 hashes by default, the choice of the number of hashes will be added soon.

Fuzzers

Random fuzzer

Generate a random string, default values are :

MinLength: 10,
MaxLength: 20,
CharStart: 32,
CharRange: 32