Increase documentation

README.md

@@ -6,6 +6,7 @@
 
 [![Discord](https://img.shields.io/discord/481002907366588416.svg)](https://discord.gg/E3YrVtG)
 [![PyPI](https://badge.fury.io/py/mythril.svg)](https://pypi.python.org/pypi/mythril)
+[![Read the Docs](https://readthedocs.org/projects/mythril-classic/badge/?version=master&style=plastic)](https://mythril-classic.readthedocs.io/en/master/)
 ![Master Build Status](https://img.shields.io/circleci/project/github/ConsenSys/mythril-classic/master.svg)
 [![Waffle.io - Columns and their card count](https://badge.waffle.io/ConsenSys/mythril-classic.svg?columns=In%20Progress)](https://waffle.io/ConsenSys/mythril-classic/)
 [![Sonarcloud - Maintainability](https://sonarcloud.io/api/project_badges/measure?project=mythril&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=mythril)
@@ -40,7 +41,7 @@ Instructions for using Mythril Classic are found on the [Wiki](https://github.co
 For support or general discussions please join the Mythril community on [Discord](https://discord.gg/E3YrVtG).
 
 ## Bulding the Documentation
-Mythril Classic's documentation is contained in the `docs` folder. It is based on Sphinx and can be built using the Makefile contained in the subdirectory:
+Mythril Classic's documentation is contained in the `docs` folder and published to [Read the Docs](https://mythril-classic.readthedocs.io/en/master/). It is based on Sphinx and can be built using the Makefile contained in the subdirectory:
 
 ```
 cd docs

docs/source/about.rst

@@ -0,0 +1,6 @@
+What is Mythril Classic?
+========================
+
+Mythril Classic is a security analysis tool for Ethereum smart contracts. It was `introduced at HITBSecConf 2018 <https://github.com/b-mueller/smashing-smart-contracts/blob/master/smashing-smart-contracts-1of1.pdf>`_.
+
+Mythril Classic detects a range of security issues, including integer underflows, owner-overwrite-to-Ether-withdrawal, and others. However, the analysis will not detect business logic issues and is not equivalent to formal verification.

docs/source/analysis-modules.rst

@@ -0,0 +1,15 @@
+Analysis Modules
+================
+
+Mythril Classic's detection capabilities are written in modules in the `/analysis/modules <https://github.com/ConsenSys/mythril-classic/tree/master/mythril/analysis/modules>`_ directory.
+
+These are our current detection capabilities:
+
+TODO: Table of things we detect.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   module-list.rst
+   create-module.rst

docs/source/create-module.rst

@@ -0,0 +1,4 @@
+Creating a Module
+=================
+
+Create a module in the :code:`analysis/modules` directory, and create an instance of a class that inherits :code:`DetectionModule` named :code:`detector`. Take a look at the `suicide module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/suicide.py>`_ as an example.

docs/source/index.rst

@@ -2,16 +2,20 @@ Welcome to Mythril Classic's documentation!
 ===========================================
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Package Contents:
+   :maxdepth: 1
+   :caption: Table of Contents:
 
+   about
+   installation
+   security-analysis
+   analysis-modules
    mythril
 
 
-
-Indices and tables
+Indices and Tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+

docs/source/installation.rst

@@ -0,0 +1,66 @@
+Installation and Setup
+======================
+
+Mythril can be setup using different methods.
+
+**************
+PyPI on Mac OS
+**************
+
+.. code-block:: bash
+
+   brew update
+   brew upgrade
+   brew tap ethereum/ethereum
+   brew install leveldb
+   brew install solidity
+   pip3 install mythril
+
+
+**************
+PyPI on Ubuntu
+**************
+
+.. code-block:: bash
+
+   # Update
+   sudo apt update
+
+   # Install solc
+   sudo apt install software-properties-common
+   sudo add-apt-repository ppa:ethereum/ethereum
+   sudo apt install solc
+
+   # Install libssl-dev, python3-dev, and python3-pip
+   sudo apt install libssl-dev python3-dev python3-pip
+
+   # Install mythril
+   pip3 install mythril
+   myth --version
+
+
+******
+Docker
+******
+
+All Mythril releases, starting from v0.18.3, are published to DockerHub as Docker images under the :code:`mythril/myth` name.
+
+After installing `Docker CE <https://docs.docker.com/install/>`_:
+
+   .. code-block:: bash
+
+      # Pull the latest release of mythril/myth
+      $ docker pull mythril/myth
+
+Use :code:`docker run mythril/myth` the same way you would use the :code:`myth` command
+
+   .. code-block:: bash
+
+      docker run mythril/myth --help
+      docker run mythril/myth -dc "0x6060"
+
+To pass a file from your host machine to the dockerized Mythril, you must mount its containing folder to the container properly. For :code:`contract.sol` in the current working directory, do:
+
+   .. code-block:: bash
+
+      docker run -v $(pwd):/tmp mythril/myth -x /tmp/contract.sol

docs/source/module-list.rst

@@ -0,0 +1,68 @@
+Modules
+=======
+
+***********************************
+Delegate Call To Untrusted Contract
+***********************************
+
+The `delegatecall module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/delegatecall.py>`_ detects `SWC-112 (DELEGATECALL to Untrusted Callee) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-112>`_.
+
+***********************************
+Dependence on Predictable Variables
+***********************************
+
+The `predictable variables module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/dependence_on_predictable_vars.py>`_ detects `SWC-120 (Weak Randomness) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-120>`_ and `SWC-116 (Timestamp Dependence) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-116>`_.
+
+******************
+Deprecated Opcodes
+******************
+
+The `deprecated opcodes module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/deprecated_ops.py>`_ detects `SWC-111 (Use of Deprecated Functions) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-111>`_.
+
+***********
+Ether Thief
+***********
+
+The `Ether Thief module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/ether_thief.py>`_ detects `SWC-105 (Unprotected Ether Withdrawal) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-105>`_.
+
+**********
+Exceptions
+**********
+
+The `exceptions module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/exceptions.py>`_ detects `SWC-110 (Assert Violation) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-110>`_.
+
+**************
+External Calls
+**************
+
+The `external calls module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/external_calls.py>`_ detects `SWC-117 (Reentrancy) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-117>`_ by detecting state changes after calls to external contracts.
+
+*******
+Integer
+*******
+
+The `integer module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/integer.py>`_ detects `SWC-101 (Integer Overflow and Underflow) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-101>`_.
+
+**************
+Multiple Sends
+**************
+
+The `multiple sends module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/multiple_sends.py>`_ detects `SWC-113 (Denial of Service with Failed Call) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-113>`_ by checking for multiple calls or sends in a single transaction.
+
+*******
+Suicide
+*******
+
+The `suicide module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/suicide.py>`_ detects `SWC-106 (Unprotected SELFDESTRUCT) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-106>`_.
+
+****************************
+Transaction Order Dependence
+****************************
+
+The `transaction order dependence module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/transaction_order_dependence.py>`_ detects `SWC-114 (Transaction Order Dependence / Race Conditions) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-114>`_.
+
+****************
+Unchecked Retval
+****************
+
+The `unchecked retval module <https://github.com/ConsenSys/mythril-classic/blob/develop/mythril/analysis/modules/unchecked_retval.py>`_ detects `SWC-104 (Unchecked Call Return Value) <https://smartcontractsecurity.github.io/SWC-registry/docs/SWC-104>`_.

docs/source/modules.rst

@@ -1,7 +0,0 @@
-mythril
-=======
-
-.. toctree::
-   :maxdepth: 4
-
-   mythril

docs/source/mythril.rst

@@ -1,4 +1,4 @@
-mythril package
+Mythril Package
 ===============
 
 Subpackages

docs/source/security-analysis.rst

@@ -0,0 +1,92 @@
+Security Analysis
+=================
+
+Run :code:`myth -x` with one of the input options described below will run the analysis modules in the `/analysis/modules <https://github.com/ConsenSys/mythril-classic/tree/master/mythril/analysis/modules>`_ directory.
+
+Mythril detects a range of security issues, including integer underflows, owner-overwrite-to-ether-withdrawals, unprotected selfdestructs, and others. However, the analysis will not detect business logic issues and is not equivalent to formal verification.
+
+***********************
+Analyzing Solidity Code
+***********************
+
+In order to work with Solidity source code files, the `solc command line compiler <https://solidity.readthedocs.io/en/develop/using-the-compiler.html>`_ needs to be installed and in PATH. You can then provide the source file(s) as positional arguments.
+
+.. code-block:: bash
+
+   $ myth -x ether_send.sol
+   ==== Unprotected Ether Withdrawal ====
+   SWC ID: 105
+   Severity: High
+   Contract: Crowdfunding
+   Function name: withdrawfunds()
+   PC address: 730
+   Estimated Gas Usage: 1132 - 1743
+   Anyone can withdraw ETH from the contract account.
+   Arbitrary senders other than the contract creator can withdraw ETH from the contract account without previously having sent an equivalent amount of ETH to it. This is likely to be a vulnerability.
+   --------------------
+   In file: tests/testdata/input_contracts/ether_send.sol:21
+
+   msg.sender.transfer(address(this).balance)
+
+   --------------------
+
+If an input file contains multiple contract definitions, Mythril analyzes the *last* bytecode output produced by solc. You can override this by specifying the contract name explicitly:
+
+.. code-block:: bash
+
+   myth -x OmiseGo.sol:OMGToken
+
+Specifying Solc Versions
+########################
+
+You can specify a version of the solidity compiler to be used with :code:`--solv <version number>`. Please be aware that this uses `py-solc <https://github.com/ethereum/py-solc>`_ and will only work on Linux and macOS. It will check the version of solc in your path, and if this is not what is specified, it will download binaries on Linux or try to compile from source on macOS.
+
+
+Output Formats
+##############
+
+By default, analysis results are printed to the terminal in text format. You can change the output format with the :code:`-o` argument:
+
+.. code-block:: bash
+
+   myth -xo jsonv2 underflow.sol
+
+Available formats are :code:`text`, :code:`markdown`, :code:`json`, and :code:`jsonv2`. For integration with other tools, :code:`jsonv2` is generally preferred over :code:`json` because it is consistent with other `MythX <https://mythx.io>`_ tools.
+
+****************************
+Analyzing On-Chain Contracts
+****************************
+
+When analyzing contracts on the blockchain, Mythril will by default attempt to query INFURA. You can use the built-in INFURA support or manually configure the RPC settings with the :code:`--rpc` argument.
+
++--------------------------------+-------------------------------------------------+
+| :code:`--rpc ganache`          | Connect to local Ganache                        |
++--------------------------------+-------------------------------------------------+
+| :code:`--rpc infura-[netname]` | Connect to mainnet, rinkeby, kovan, or ropsten. |
++--------------------------------+-------------------------------------------------+
+| :code:`--rpc host:port`        | Connect to custom rpc                           |
++--------------------------------+-------------------------------------------------+
+| :code:`--rpctls <True/False>`  | RPC connection over TLS (default: False)        |
++--------------------------------+-------------------------------------------------+
+
+To specify a contract address, use :code:`-a <address>`
+
+Analyze mainnet contract via INFURA:
+
+.. code-block:: bash
+
+   myth -x -a 0x5c436ff914c458983414019195e0f4ecbef9e6dd
+
+Adding the :code:`-l` flag will cause mythril to automatically retrieve dependencies, such as dynamically linked library contracts:
+
+.. code-block:: bash
+
+   myth -xla 0xEbFD99838cb0c132016B9E117563CB41f2B02264 -v4
+
+******************
+Speed vs. Coverage
+******************
+
+The execution timeout can be specified with the :code:`--execution-timeout <seconds>` argument. When the timeout is reached, mythril will stop analysis and print out all currently found issues.
+
+The maximum recursion depth for the symbolic execution engine can be controlled with the :code:`--max-depth` argument. The default value is 22. Lowering this value will decrease the number of explored states and analysis time, while increasing this number will increase the number of explored states and increase analysis time. For some contracts, it helps to fine tune this number to get the best analysis results.