Usage

To install run

> pip install ethpector

or build from source directly by

> make install

Use as follows:

usage: ethpector [-h] [--version] [-r rpc] [-e etherscan_token] [-c] [-v] [-vv] [-d] [-a] [-f] [--dont_drop_metadatastring] [--output OUTPUT [OUTPUT ...]] [--output_dir OUTPUT_DIR] contract

ethpector -- getting insights into evm binaries.

positional arguments:
  contract              EVM input bytecode or address if -a is provided

options:

-h, --help

show this help message and exit.

--version

show program’s version number and exit.

-r rpc, --rpc rpc

Ethereum node RPC url.

-e etherscan_token, --etherscan etherscan_token

Etherscan access token.

-c, --concolic

Symbolic execution engine loads values (storage state, call targets) from a node via RPC.

-v, --verbose

set loglevel to INFO.

-vv, --very-verbose

set loglevel to DEBUG.

-d, --deploy

Sets if deployment code is provided. EXPERIMENTAL.

-a, --address

Analyse address: data is loaded either via RPC or Etherscan.

-f, --tofile

Dump output as files.

--offline

Do not use any online resources.

--nodotenv

Do not load dotenv file to initialize config values.

--dont_drop_metadatastring

Includes the metadata string to the bytecode analysis.

--output OUTPUT

Output that should be produced: summary|disassembly|sourcecode|all|basicblocks|calls|storage|functions|known_interfaces. Note: Multiple OUTPUTS possible.

--output_dir OUTPUT_DIR

Directory to save the results if -f is specified. Default is ethspector-output/.

For improved analysis results bot an etherscan api token as well as a ethereum node is beneficial. They can either be configured via commandline options (–rpc and –etherscan), via environment variables or .env files.

An example .env file could look as follows:

ETHPECTOR_ETHERSCAN_TOKEN=[YOUR ETHERSCAN TOKEN]
ETHPECTOR_RPC=https://mainnet.infura.io/v3/[YOUR INFURA TOKEN]
ETHPECTOR_CHAINID=1
ETHPECTOR_MYTHRIL_EXECUTION_TIMEOUT=100
ETHPECTOR_MYTHRIL_CREATE_TIMEOUT=60
ETHPECTOR_MYTHRIL_MAX_DEPTH=512
ETHPECTOR_MYTHRIL_SOLVER_TIMEOUT=200000

A full list of configurable options can be found in src/ethpector/config/config.py.

The example folder holds some interesting binaries as well as addresses to test on.

Development

it is advised to use a virtual environment (venv) for development. Run the following command to initialize one

> python3 -m venv .venv

and activate it (in bash) using

   > source .venv/bin/activate

For more information refer to (venv_). Run

> make dev

to initialize the dev environment. If you want to install ethpector in development mode run

> make install-dev

Before committing anything to the repository please format, lint and test your code in that order. Fix all linter warnings and make sure all test are passing before a commit.

Use the following commands for that:

> make format
> make lint
> make test

or equivalently run

> make pre-commit

Some slow tests are excluded when running make test. Occasionally, one should run

> make test-all

to run the entire test-suite.

Linting and formatting should be automatically executed on every git commit, using pre-commit.

To create the documentation please run:

> make docs

Creating the docs need python dev dependencies to build see (Stackoverflow)

Credits

We thank all the developers of mythril for their great work. Without which this project would not exist.

• Mythril

We would like to thank the following projects for inspiration.

• Evmdis

• gsalzer s ethutils

Similar Projects

The following section contains a couple of similar projects and useful libraries that could serve as an alternative or to amend ethpector when analyzing smart contract binaries.

• eveem

• pakala

• manticore

• panoramix decompiler

• hevm

• ethtx

• slither

Funding

This project was created in the course of the KRYPTOMONITOR project.

The security research project KRYPTOMONITOR is funded by the Austrian security research programme KIRAS of the Federal Ministry of Agriculture, Regions and Tourism (BMLRT).

• Kryptomonitor Project