From b45b3d2c44dd6bce708dcf3a0b03dcdb31fe504d Mon Sep 17 00:00:00 2001 From: feliam Date: Mon, 6 Jul 2020 12:45:08 -0300 Subject: [PATCH 1/3] Add doc, fix output bugs --- docs/index.rst | 1 + docs/verifier.rst | 172 +++++++++++++++++++++++++++++++++ manticore/ethereum/verifier.py | 7 +- 3 files changed, 177 insertions(+), 3 deletions(-) create mode 100644 docs/verifier.rst diff --git a/docs/index.rst b/docs/index.rst index 049b77883..57bd7e570 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,7 @@ Manticore is a symbolic execution tool for analysis of binaries and smart contra :maxdepth: 2 :caption: Contents: + verifier base worker states diff --git a/docs/verifier.rst b/docs/verifier.rst new file mode 100644 index 000000000..31e8d8f4f --- /dev/null +++ b/docs/verifier.rst @@ -0,0 +1,172 @@ +Property based symbolic executor: manticore-verifier +==================================================== +Manticore installs a separated CLI tool to do property based symbolic execution of smart contracts. :: + + $ manticore-verifier your_contract.sol + +**manticore-verifier** initializes an emulated blockchain ennvironment with a configurable set of +acocunts and then sends various symbolic transactions to the target contract containing property methods. +If a way to break a property is found the full transaction trace to reproduce the behaivor is provided. +A configurable stopping condition bounds the exploration, properties not failing are considered to pass. + + +Writing properties in {Solidity/ Vyper} +--------------------------------------- +**manticore-verifier** will detect and test property methods written in the +original contract language. A property can be written in the original language +by simply naming a method in a specific way. For example methods names starting with ```crytic_```. + +.. code-block:: javascript + + function crytic_test_true_property() view public returns (bool){ + return true; + } + +You can select your own way to name property methods using the ``--propre`` commandline argument. :: + + --propre PROPRE A regular expression for selecting properties + +Normal properties +^^^^^^^^^^^^^^^^^ +In the most common case after some precondition is met some logic property must always be true. +Normal properties are property methods that must always return true (or REVERT). + + +Reverting properties +^^^^^^^^^^^^^^^^^^^^ +Sometimes it is difficult to detect that a revert has happened in an internal transaction. +manticor-verifier allows to test for ALWAYS REVERTing property methdos. +Revert properties are property methods that must always REVERT. +Reverting property are any property method that contains "revert". For example: + +.. code-block:: javascript + + function crytic_test_must_always_revert() view public returns (bool){ + return true; + } + + +Selecting a target contract +=========================== +**manticore-verifier** needs to be pointed to a the target contract containing any number of property methods. +The target contract is the entry point of the exploration. It needs to initilize any internal structure or external contracts to a correct initial state. All methods of this contract matching the property name criteria will be tested. :: + + --contract_name CONTRACT_NAME The target contract name defined in the source code + + +User accounts +============= +You can specify what are the accounts used in the exploration. +Normaly you do not want the owner or deployer of the contract to send the symbolic transaction and to use as eparated unused account to actually check the property methods. +There are 3 types of user accounts: + + - deployer: The account used to create the target contract + - senders: A set of accounts used to send symbolic transactions. Think that these transactions are the ones trying to put the contract in a state that makes the property fail. + - psender: The account used as caller to test tha actual property methos + + +You can specify those via commanline arguments :: + + --deployer DEPLOYER (optional) address of account used to deploy the contract + --senders SENDERS (optional) a comma separated list of sender addresses. + The properties are going to be tested sending + transactions from these addresses. + --psender PSENDER (optional) address from where the property is tested + + +Or, if you prefer, you can specify a yaml file like this :: + + deployer: "0x41414141414141414141" + sender: ["0x51515151515151515151", "0x52525252525252525252"] + psender: "0x616161616161616161" + +If you specify the accounts both ways the commandline takes precedence over the yaml file. +If you do not provide specific accounts **manticore-verifier** will choose them for you. + + +Stopping condition +================== +The exploration will continue to sent symbolic transactions until one of the stopping criteria is met. + +Maximun number of trasactions +----------------------------- +You can be interested only in what could happen under a number of transactions. After a maximun number of transactions is reached the explorations ends. Properties that had not be found to be breakable are considered a pass. +You can modify the max number of transactions to test vis a command line argument, otherwise it will stop at 3 transactions. :: + + --maxt MAXT Max transaction count to explore + +Maximun coverage % attained +--------------------------- +By default if a transaction does not produce new coverage the exploration is stopped. But you can add a further constraining, if the provided coverage percentage is obtained stop. Not that this is the total % of runtime bytecode covered. By default compilers add dead code and also in this case the rntime contains the code of the propertie methods. So use with care. :: + + --maxcov MAXCOV Stop after maxcov % coverage is obtained in the main + contract + + +Timeout +------- +Exploration will stop after the timeout seconds have pass. :: + + --timeout TIMEOUT Exploration timeout in seconds + + +Walkthrough +----------- +Consider this little contract containing a bug: + +.. code-block:: javascript + + contract Ownership{ // It can have an owner! + address owner = msg.sender; + function Onwer() public{ + owner = msg.sender; + } + modifier isOwner(){ + require(owner == msg.sender); + _; + } + } + contract Pausable is Ownership{ //It is also pausable. You can pause it. You can resume it. + bool is_paused; + modifier ifNotPaused(){ + require(!is_paused); + _; + } + function paused() isOwner public{ + is_paused = true; + } + function resume() isOwner public{ + is_paused = false; + } + } + contract Token is Pausable{ //<< HERE it is. + mapping(address => uint) public balances; // It maintains a balance sheet + function transfer(address to, uint value) ifNotPaused public{ //and can transfer value + balances[msg.sender] -= value; // from one account + balances[to] += value; // to the other + } + } + +Assuming the programmer did not want to allow the magic creation of tokens. +We can design a property around the fact that the initial token count can not be increased over time. Even more relaxed, after the contract creation any account must have less that total count of tokens. The property looks like this : + +.. code-block:: javascript + + contract TestToken is Token{ + constructor() public{ + //here lets initialize the thing + balances[msg.sender] = 10000; //deployer account owns it all! + } + + function crytic_test_balance() view public returns (bool){ + return balances[msg.sender] <= 10000; //nobody can have more than 100% of the tokens + } + + } + +And you can unleash the verifier like this:: + + $manticore-verifier testtoken.sol --contract TestToken + + +f/ diff --git a/manticore/ethereum/verifier.py b/manticore/ethereum/verifier.py index 702fd0bb6..c56f79111 100644 --- a/manticore/ethereum/verifier.py +++ b/manticore/ethereum/verifier.py @@ -167,7 +167,7 @@ def manticore_verifier( print(f"# Owner account: 0x{int(owner_account):x}") print(f"# Contract account: 0x{int(contract_account):x}") for n, user_account in enumerate(user_accounts): - print(f"# Sender_{n} account: 0x{int(checker_account):x}") + print(f"# Sender_{n} account: 0x{int(user_account):x}") print(f"# PSender account: 0x{int(checker_account):x}") properties = {} @@ -211,7 +211,7 @@ def manticore_verifier( # check if we sent more than MAXTX transaction if tx_num >= MAXTX: - print("Max numbr of transactions reached({tx_num})") + print(f"Max numbr of transactions reached({tx_num})") break tx_num += 1 @@ -219,7 +219,7 @@ def manticore_verifier( new_coverage = m.global_coverage(contract_account) if new_coverage >= MAXCOV: print( - "Current coverage({new_coverage}%) is greater than max allowed({MAXCOV}%).Stopping exploration." + f"Current coverage({new_coverage}%) is greater than max allowed({MAXCOV}%).Stopping exploration." ) break @@ -484,4 +484,5 @@ def main(): deployer=deployer, psender=psender, timeout=args.timeout, + propre=args.propre, ) From ff774620f1baa949c720e8f76ad4ec8e4888d829 Mon Sep 17 00:00:00 2001 From: feliam Date: Mon, 6 Jul 2020 20:38:31 -0300 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Eric Hennenfent --- docs/verifier.rst | 18 +++++++++--------- manticore/ethereum/verifier.py | 4 ++-- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/verifier.rst b/docs/verifier.rst index 31e8d8f4f..67e3c7771 100644 --- a/docs/verifier.rst +++ b/docs/verifier.rst @@ -4,8 +4,8 @@ Manticore installs a separated CLI tool to do property based symbolic execution $ manticore-verifier your_contract.sol -**manticore-verifier** initializes an emulated blockchain ennvironment with a configurable set of -acocunts and then sends various symbolic transactions to the target contract containing property methods. +**manticore-verifier** initializes an emulated blockchain environment with a configurable set of +accounts and then sends various symbolic transactions to the target contract containing property methods. If a way to break a property is found the full transaction trace to reproduce the behaivor is provided. A configurable stopping condition bounds the exploration, properties not failing are considered to pass. @@ -35,7 +35,7 @@ Normal properties are property methods that must always return true (or REVERT). Reverting properties ^^^^^^^^^^^^^^^^^^^^ Sometimes it is difficult to detect that a revert has happened in an internal transaction. -manticor-verifier allows to test for ALWAYS REVERTing property methdos. +manticore-verifier allows to test for ALWAYS REVERTing property methods. Revert properties are property methods that must always REVERT. Reverting property are any property method that contains "revert". For example: @@ -57,15 +57,15 @@ The target contract is the entry point of the exploration. It needs to initilize User accounts ============= You can specify what are the accounts used in the exploration. -Normaly you do not want the owner or deployer of the contract to send the symbolic transaction and to use as eparated unused account to actually check the property methods. +Normaly you do not want the owner or deployer of the contract to send the symbolic transaction and to use a separate unused account to actually check the property methods. There are 3 types of user accounts: - deployer: The account used to create the target contract - senders: A set of accounts used to send symbolic transactions. Think that these transactions are the ones trying to put the contract in a state that makes the property fail. - - psender: The account used as caller to test tha actual property methos + - psender: The account used as caller to test the actual property methods -You can specify those via commanline arguments :: +You can specify those via command line arguments :: --deployer DEPLOYER (optional) address of account used to deploy the contract --senders SENDERS (optional) a comma separated list of sender addresses. @@ -86,9 +86,9 @@ If you do not provide specific accounts **manticore-verifier** will choose them Stopping condition ================== -The exploration will continue to sent symbolic transactions until one of the stopping criteria is met. +The exploration will continue to send symbolic transactions until one of the stopping criteria is met. -Maximun number of trasactions +Maximum number of transactions ----------------------------- You can be interested only in what could happen under a number of transactions. After a maximun number of transactions is reached the explorations ends. Properties that had not be found to be breakable are considered a pass. You can modify the max number of transactions to test vis a command line argument, otherwise it will stop at 3 transactions. :: @@ -97,7 +97,7 @@ You can modify the max number of transactions to test vis a command line argumen Maximun coverage % attained --------------------------- -By default if a transaction does not produce new coverage the exploration is stopped. But you can add a further constraining, if the provided coverage percentage is obtained stop. Not that this is the total % of runtime bytecode covered. By default compilers add dead code and also in this case the rntime contains the code of the propertie methods. So use with care. :: +By default, if a transaction does not produce new coverage, the exploration is stopped. But you can add a further constraint so that if the provided coverage percentage is obtained, stop. Note that this is the total % of runtime bytecode covered. By default, compilers add dead code, and also in this case the runtime contains the code of the properties methods. So use with care. :: --maxcov MAXCOV Stop after maxcov % coverage is obtained in the main contract diff --git a/manticore/ethereum/verifier.py b/manticore/ethereum/verifier.py index c56f79111..20002f874 100644 --- a/manticore/ethereum/verifier.py +++ b/manticore/ethereum/verifier.py @@ -211,7 +211,7 @@ def manticore_verifier( # check if we sent more than MAXTX transaction if tx_num >= MAXTX: - print(f"Max numbr of transactions reached({tx_num})") + print(f"Max number of transactions reached ({tx_num})") break tx_num += 1 @@ -219,7 +219,7 @@ def manticore_verifier( new_coverage = m.global_coverage(contract_account) if new_coverage >= MAXCOV: print( - f"Current coverage({new_coverage}%) is greater than max allowed({MAXCOV}%).Stopping exploration." + f"Current coverage({new_coverage}%) is greater than max allowed ({MAXCOV}%). Stopping exploration." ) break From 00cca28aace265899ccfed08ce01935fe3ee9166 Mon Sep 17 00:00:00 2001 From: feliam Date: Tue, 7 Jul 2020 16:27:37 -0300 Subject: [PATCH 3/3] Readme link --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 15e92ad20..788ef568f 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,8 @@ Manticore has a command line interface which can perform a basic symbolic analys Analysis results will be placed into a workspace directory beginning with `mcore_`. For information about the workspace, see the [wiki](https://github.com/trailofbits/manticore/wiki/What's-in-the-workspace%3F). #### EVM -Solidity smart contracts must have a `.sol` extension for analysis by Manticore. See a [demo](https://asciinema.org/a/154012). +Manticore CLI automatically detects you are trying to test a contract if (for ex.) + the contract has a `.sol` or a `.vy` extension. See a [demo](https://asciinema.org/a/154012).
Click to expand: @@ -99,6 +100,12 @@ $ manticore examples/evm/umd_example.sol ```
+##### Manticore-verifier + +An alternative CLI tool is provided that simplifys contract testing and +allows writing properties methods in the same high-level language the contract uses. +Checkout manticore-verifier [documentation](http://manticore.readthedocs.io/en/latest/verifier.html). +See a [demo](https://asciinema.org/a/xd0XYe6EqHCibae0RP6c7sJVE) #### Native