From d1eb136e78f7bf9363a2f759b79a6cb3faca1634 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 12:06:16 -0400 Subject: [PATCH 01/14] Up the version number to 0.2.0 (#22) --- etheno/etheno.py | 2 +- setup.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/etheno/etheno.py b/etheno/etheno.py index 14f8927..4667a61 100644 --- a/etheno/etheno.py +++ b/etheno/etheno.py @@ -1,4 +1,4 @@ -VERSION='0.0.1' +VERSION='0.2.0' VERSION_NAME="ToB/v%s/source/Etheno" % VERSION JSONRPC_VERSION = '2.0' VERSION_ID=67 diff --git a/setup.py b/setup.py index 5206cdd..70da4c8 100644 --- a/setup.py +++ b/setup.py @@ -3,10 +3,10 @@ setup( name='etheno', - description='Etheno is a JSON RPC multiplexer, Manticore wrapper, and test framework integration tool.', + description='Etheno is a JSON RPC multiplexer, Manticore wrapper, differential fuzzer, and test framework integration tool.', url='https://github.com/trailofbits/etheno', author='Trail of Bits', - version='0.0.1', + version='0.2.0', packages=find_packages(), python_requires='>=3.6', install_requires=[ From ccce600e649862375ef269970e76e1487f120db1 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 12:26:24 -0400 Subject: [PATCH 02/14] First cut at a CHANGELOG for 0.2.0 (#22) --- CHANGELOG.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..97ef76f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,41 @@ +# Change Log + +The format is based on [Keep a Changelog](http://keepachangelog.com/). + +## [Unreleased](https://github.com/trailofbits/manticore/compare/0.2.2...HEAD) + +## 0.2.0 — 2018-11-02 + +First formal release of Etheno. + +### Added + +- An [example](examples/ConstantinopleGasUsage) that can automatically reproduce [the Constantinople gas usage discrepancy](https://github.com/paritytech/parity-ethereum/pull/9746) that caused a hard-fork on Ropsten in October of 2018 +- More client integrations and support + - Support for JSON RPC clients that have no local accounts and only accept signed raw transactions + - Support for saving and loading genesis files + - Support for Geth with either an autogenerated or user-provided genesis + - Support for Parity with either an autogenerated or user-provided genesis + - Automated transaction synchronization between chains (_e.g._, if clients are running with different genesis blocks) +- Improved automated testing + - Automated differential testing that reports differences between clients + - Integration with the [Echidna](https://github.com/trailofbits/echidna) EVM fuzzer +- Improved extensibility and user friendliness + - Client and Plugin API + - Logging framework with ANSI color on the terminal + - Optional log directory with client- and plugin-specific log files, including auto-generated scripts to re-run the clients + +### Changed + +- The [`BrokenMetaCoin` example](examples/BrokenMetaCoin) was improved by adding various utilities for interacting with Manticore + +## 0.0.1 — 2018-10-07 + +Prerelease at TruffleCon, 2018. + +Initial Features: + +- Manticore Integration +- Truffle Integration +- Ganache Integration +- JSON RPC Multiplexing From 96376d78b937db1a20a99c2e2e642a376c517f74 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 14:13:09 -0400 Subject: [PATCH 03/14] Updated the intro to the README (#22) --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b71e821..d33684c 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@
-Etheno is a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools on large, multi-contract projects, like [Manticore](https://github.com/trailofbits/manticore/). In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. +Etheno is the Ethereum testing swiss army knife. It's a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like [Manticore](https://github.com/trailofbits/manticore/) and [Echidna](https://github.com/trailofbits/echidna) on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. -It is named after the Greek goddess [Stheno](https://en.wikipedia.org/wiki/Stheno), sister of Medusa, and mother of Echidna—which also happens to be the name of [our EVM property-based fuzz tester](https://github.com/trailofbits/echidna). +If you are a smart contract developer, you should use Echidna to test your contracts. If you are an Ethereum client developer, you should use Etheno to perform differential testing on your implementation. For example, Etheno is [capable of automatically reproducing](examples/ConstantinopleGasUsage) the Constantinople gas usage consensus bug that caused a fork on Ropsten. + +Etheno is named after the Greek goddess [Stheno](https://en.wikipedia.org/wiki/Stheno), sister of Medusa, and mother of Echidna—which also happens to be the name of [our EVM property-based fuzz tester](https://github.com/trailofbits/echidna). ## Features From 573d68117cab944f18b54dd7775a4e90b41f19f4 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 14:30:15 -0400 Subject: [PATCH 04/14] Capitalize Swiss Army (#22) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b77719d..f0d0012 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@
-Etheno is the Ethereum testing swiss army knife. It's a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like [Manticore](https://github.com/trailofbits/manticore/) and [Echidna](https://github.com/trailofbits/echidna) on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. +Etheno is the Ethereum testing Swiss Army knife. It's a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like [Manticore](https://github.com/trailofbits/manticore/) and [Echidna](https://github.com/trailofbits/echidna) on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. If you are a smart contract developer, you should use Echidna to test your contracts. If you are an Ethereum client developer, you should use Etheno to perform differential testing on your implementation. For example, Etheno is [capable of automatically reproducing](examples/ConstantinopleGasUsage) the Constantinople gas usage consensus bug that caused a fork on Ropsten. From bfc203fa1aced8f2a0d82ffe06360c6e2c6e176a Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 14:30:46 -0400 Subject: [PATCH 05/14] Unicode all the things (#22) --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f0d0012..c24b149 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@
-Etheno is the Ethereum testing Swiss Army knife. It's a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like [Manticore](https://github.com/trailofbits/manticore/) and [Echidna](https://github.com/trailofbits/echidna) on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. +Etheno is the Ethereum testing Swiss Army knife. It’s a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like [Manticore](https://github.com/trailofbits/manticore/) and [Echidna](https://github.com/trailofbits/echidna) on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. If you are a smart contract developer, you should use Echidna to test your contracts. If you are an Ethereum client developer, you should use Etheno to perform differential testing on your implementation. For example, Etheno is [capable of automatically reproducing](examples/ConstantinopleGasUsage) the Constantinople gas usage consensus bug that caused a fork on Ropsten. @@ -67,7 +67,7 @@ This command starts a JSON RPC server and forwards all messages to the given cli etheno https://client1.url.com:1234/ https://client2.url.com:8545/ http://client3.url.com:8888/ ``` -* `--port` or `-p` allows you to specify a port on which to run Etheno's JSON RPC server (default is 8545) +* `--port` or `-p` allows you to specify a port on which to run Etheno’s JSON RPC server (default is 8545) * `--run-publicly` allows incoming JSON RPC connections from external computers on the network * `--debug` will run a web-based interactive debugger in the event that an internal Etheno client throws an exception while processing a JSON RPC call; this should _never_ be used in conjunction with `--run-publicly` * `--master` or `-s` will set the “master” client, which will be used for synchronizing with Etheno clients like Manticore. If a master is not explicitly provided, it defaults to the first client listed. @@ -79,7 +79,7 @@ A Ganache instance can automatically be run within Etheno: etheno --ganache ``` -* `--ganache-port` will set the port on which Ganache is run; if omitted, Etheno will choose the lowest port higher than the port on which Etheno's JSON RPC server is running +* `--ganache-port` will set the port on which Ganache is run; if omitted, Etheno will choose the lowest port higher than the port on which Etheno’s JSON RPC server is running * `--ganache-args` lets you pass additional arguments to Ganache * `--accounts` or `-a` sets the number of accounts to create in Ganache (default is 10) * `--balance` or `-b` sets the default balance (in Ether) to seed to each Ganache account (default is 100.0) @@ -87,13 +87,13 @@ etheno --ganache ### Manticore Client -Manticore—which, by itself, does not implemnent a JSON RPC interface—can be run as an Etheno client, synchronizing its accounts with Etheno's master client and symbolically executing all transactions sent to Etheno. +Manticore—which, by itself, does not implemnent a JSON RPC interface—can be run as an Etheno client, synchronizing its accounts with Etheno’s master client and symbolically executing all transactions sent to Etheno. ``` etheno --manticore ``` This alone will not run any Manticore analyses; they must either be run manually, or automated through [the `--truffle` command](#truffle-integration); -* `--manticore-verbosity` sets Manticore's logging verbosity (default is 3) +* `--manticore-verbosity` sets Manticore’s logging verbosity (default is 3) * `--manticore-max-depth` sets the maximum state depth for Manticore to explore; if omitted, Manticore will have no depth limit ### Truffle Integration @@ -103,7 +103,7 @@ Truffle migrations can automatically be run within a Truffle project: etheno --truffle ``` -When combined with the `--manticore` option, this will automatically run Manticore's default analyses on all contracts created once the Truffle migration completes: +When combined with the `--manticore` option, this will automatically run Manticore’s default analyses on all contracts created once the Truffle migration completes: ``` etheno --truffle --manticore ``` @@ -144,4 +144,4 @@ Documentation is available in several places: ## License -Etheno is licensed and distributed under the [AGPLv3](LICENSE) license. [Contact us](mailto:opensource@trailofbits.com) if you're looking for an exception to the terms. +Etheno is licensed and distributed under the [AGPLv3](LICENSE) license. [Contact us](mailto:opensource@trailofbits.com) if you’re looking for an exception to the terms. From 3f0dc4b8abe79e88f7b60935ee8d4b1730e9c307 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 14:36:25 -0400 Subject: [PATCH 06/14] Added PyPI classifiers --- setup.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 9fee5bb..7b8dc1b 100644 --- a/setup.py +++ b/setup.py @@ -24,5 +24,13 @@ 'console_scripts': [ 'etheno = etheno.__main__:main' ] - } + }, + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: GNU Affero General Public License v3', + 'Topic :: Security', + 'Topic :: Software Development :: Testing' + ] ) From 88667aae2a9b0b5101ce875d00ed3812c7e18d03 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:20:43 -0400 Subject: [PATCH 07/14] Added information about Geth and Parity (#22) --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index c24b149..2703543 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,19 @@ etheno https://client1.url.com:1234/ https://client2.url.com:8545/ http://client * `--run-publicly` allows incoming JSON RPC connections from external computers on the network * `--debug` will run a web-based interactive debugger in the event that an internal Etheno client throws an exception while processing a JSON RPC call; this should _never_ be used in conjunction with `--run-publicly` * `--master` or `-s` will set the “master” client, which will be used for synchronizing with Etheno clients like Manticore. If a master is not explicitly provided, it defaults to the first client listed. +* `--raw`, when prefixed before a client URL, will cause Etheno to auto-sign all transactions and submit then to the client as raw transactions + +### Geth and Parity Integration + +A Geth and/or Parity instance can be run as a private chain with +* `--geth` or `-go` for Geth +* `--parity` or `-pa` for Parity + +Each will be instantiated with an autogenerated genesis block. You may provide a custom `genesis.json` file in Geth format using the `--genesis` or `-j` argument. The genesis used for each run will automatically be saved to the log directory (if one is provided using the `--log-dir` option), or it can be manually saved to a location provided with the `--save-genesis` option. + +The network ID of each client will default to 0x657468656E6F (equal to the string `etheno` in ASCII). This can be overridden with the `--network-id` or `-i` option. + +EIP and hard fork block numbers can be set within a custom genesis.json as usual, or they may be specified as commandline options such as `--constantinople`. ### Ganache Integration From a22b04880f5c55a4f4be923ff7feb8d70c379c1c Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:23:24 -0400 Subject: [PATCH 08/14] Added differential testing (#22) --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 2703543..7ceddf6 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,15 @@ etheno --ganache * `--balance` or `-b` sets the default balance (in Ether) to seed to each Ganache account (default is 100.0) * `--gas-price` or `-c` sets the default gas price for Ganache (default is 20000000000) +### Differential Testing + +Whenever two or more clients are run within Etheno, the differential +testing plugin will automatically be loaded. This plugin checks for a +variety of different discrepancies between the clients, such as gas +usage differences. A report is printed when Etheno exits. + +This plugin can be disabled with the `--no-differential-testing` option. + ### Manticore Client Manticore—which, by itself, does not implemnent a JSON RPC interface—can be run as an Etheno client, synchronizing its accounts with Etheno’s master client and symbolically executing all transactions sent to Etheno. From b44c3952d1ce5634ef7593d175231472464361a6 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:24:03 -0400 Subject: [PATCH 09/14] Removed a superfluous space --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97ef76f..f25ae98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ First formal release of Etheno. - Improved automated testing - Automated differential testing that reports differences between clients - Integration with the [Echidna](https://github.com/trailofbits/echidna) EVM fuzzer -- Improved extensibility and user friendliness +- Improved extensibility and user friendliness - Client and Plugin API - Logging framework with ANSI color on the terminal - Optional log directory with client- and plugin-specific log files, including auto-generated scripts to re-run the clients From cd38d5e9cda36ca71cefe70f123ba448f54d2889 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:28:12 -0400 Subject: [PATCH 10/14] Added Echidna (#22) --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 7ceddf6..2f4757b 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,17 @@ usage differences. A report is printed when Etheno exits. This plugin can be disabled with the `--no-differential-testing` option. +### Property-Based Fuzz Testing + +Echidna can be run to fuzz test the clients, which is useful for differential testing: +``` +etheno --echidna +``` +By default, Echidna deploys a generic fuzz testing contract to all clients, enumerates a minimal set of transactions that maximize the coverage of the contract, sends those transactions to the clients, and then exits. + +* `--fuzz-limit` limits the number of transactions that Echidna will emit +* `--fuzz-contract` lets the user specify a custom contract for Echidna to deploy and fuzz + ### Manticore Client Manticore—which, by itself, does not implemnent a JSON RPC interface—can be run as an Etheno client, synchronizing its accounts with Etheno’s master client and symbolically executing all transactions sent to Etheno. From efec8203d62d07d571cd29fffee3cb1b77228012 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:29:47 -0400 Subject: [PATCH 11/14] Echidna --> Etheno --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f4757b..1b46f05 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Etheno is the Ethereum testing Swiss Army knife. It’s a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like [Manticore](https://github.com/trailofbits/manticore/) and [Echidna](https://github.com/trailofbits/echidna) on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle. -If you are a smart contract developer, you should use Echidna to test your contracts. If you are an Ethereum client developer, you should use Etheno to perform differential testing on your implementation. For example, Etheno is [capable of automatically reproducing](examples/ConstantinopleGasUsage) the Constantinople gas usage consensus bug that caused a fork on Ropsten. +If you are a smart contract developer, you should use Etheno to test your contracts. If you are an Ethereum client developer, you should use Etheno to perform differential testing on your implementation. For example, Etheno is [capable of automatically reproducing](examples/ConstantinopleGasUsage) the Constantinople gas usage consensus bug that caused a fork on Ropsten. Etheno is named after the Greek goddess [Stheno](https://en.wikipedia.org/wiki/Stheno), sister of Medusa, and mother of Echidna—which also happens to be the name of [our EVM property-based fuzz tester](https://github.com/trailofbits/echidna). From aad4a612d2e5b22340475a817779144184f11d2e Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:34:29 -0400 Subject: [PATCH 12/14] Added a section on logging (#22) --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 1b46f05..3daf93a 100644 --- a/README.md +++ b/README.md @@ -152,6 +152,20 @@ This script does not need to import Manticore or create a `ManticoreEVM` object; Additional arguments can be passed to Truffle using `--truffle-args`. +### Logging + +By default, Etheno only prints log messages to the console with a log +level defaulting to `INFO`. An alternative log level can be specified +with `--log-level` or `-l`. You can specify a log file with the +`--log-file` option. In addition, you can provide the path to a +logging directory with `--log-dir` in which the following will be +saved: +* a complete log file including log messages at all log levels; +* separate log files for each Etheno client and plugin; +* the genesis file used to instantiate clients; +* a subdirectory in which each client and plugin can store additional files such as test results; +* a script to re-run Geth and/or Parity using the same genesis and chain data that Etheno used. + ## Requirements * Python 3.6 or newer From d63b1c1018dd409e92bc4a08ae035955dbca8cd0 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:36:32 -0400 Subject: [PATCH 13/14] Switch to suggesting the users install from PyPI (#22) --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3daf93a..cdff481 100644 --- a/README.md +++ b/README.md @@ -45,10 +45,8 @@ Alternatively, natively install Etheno in a few shell commands: # Install system dependencies sudo apt-get update && sudo apt-get install python3 python3-pip -y -# Clone and install Etheno -git clone https://github.com/trailofbits/etheno.git -cd etheno -pip3 install . +# Install Etheno +pip3 install --user etheno # Use the Etheno CLI cd /path/to/a/truffle/project From 8052145137d95898b54a44faa1fcc8107ac71693 Mon Sep 17 00:00:00 2001 From: Evan Sultanik Date: Fri, 2 Nov 2018 15:37:54 -0400 Subject: [PATCH 14/14] Fix sublist indentation (#22) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cdff481..befa4ec 100644 --- a/README.md +++ b/README.md @@ -174,8 +174,8 @@ saved: * [Truffle and Ganache](https://truffleframework.com/) for their associated integrations * [Geth](https://github.com/ethereum/go-ethereum) and/or [Parity](https://github.com/paritytech/parity-ethereum), if you would like to have Etheno run them * [Echidna](https://github.com/trailofbits/echidna), for smart contract fuzzing and differential testing -** Note that Etheno currently requires the features in the [`dev-no-hedgehog` branch](https://github.com/trailofbits/echidna/tree/dev-no-hedgehog); Etheno will prompt you to automatically install this when you try and run it the first time -** Running Echidna also requires the [`solc`](https://github.com/ethereum/solidity) compiler + * Note that Etheno currently requires the features in the [`dev-no-hedgehog` branch](https://github.com/trailofbits/echidna/tree/dev-no-hedgehog); Etheno will prompt you to automatically install this when you try and run it the first time + * Running Echidna also requires the [`solc`](https://github.com/ethereum/solidity) compiler ## Getting Help