Merge pull request #44 from trailofbits/22-readme-update

Update the README for v0.2.0

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

README.md

@@ -5,9 +5,11 @@
 <br />
 
 
-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 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).
 
 ## Features
 
@@ -43,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
@@ -65,10 +65,23 @@ 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.
+* `--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
 
@@ -77,21 +90,41 @@ 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)
 * `--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.
+
+### 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.
+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
@@ -101,7 +134,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
 ```
@@ -117,6 +150,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
@@ -127,8 +174,8 @@ Additional arguments can be passed to Truffle using `--truffle-args`.
 * [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
 
@@ -142,4 +189,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.

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

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=[
@@ -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'
+    ]
 )