Skip to main content

Manticore is a symbolic execution tool for analysis of binaries and smart contracts.

Project description

Manticore


Build Status Coverage Status PyPI Version Slack Status Documentation Status Example Status LGTM Total Alerts

Manticore is a symbolic execution tool for analysis of smart contracts and binaries.

Features

  • Program Exploration: Manticore can execute a program with symbolic inputs and explore all the possible states it can reach
  • Input Generation: Manticore can automatically produce concrete inputs that result in a given program state
  • Error Discovery: Manticore can detect crashes and other failure cases in binaries and smart contracts
  • Instrumentation: Manticore provides fine-grained control of state exploration via event callbacks and instruction hooks
  • Programmatic Interface: Manticore exposes programmatic access to its analysis engine via a Python API

Manticore can analyze the following types of programs:

  • Ethereum smart contracts (EVM bytecode)
  • Linux ELF binaries (x86, x86_64, aarch64, and ARMv7)
  • WASM Modules

Installation

Note: We recommend installing Manticore in a virtual environment to prevent conflicts with other projects or packages

Option 1: Installing from PyPI:

pip install manticore

Option 2: Installing from PyPI, with extra dependencies needed to execute native binaries:

pip install "manticore[native]"

Option 3: Installing a nightly development build (fill in the latest version from the PyPI history):

pip install "manticore[native]==0.x.x.devYYMMDD"

Option 4: Installing from the master branch:

git clone https://github.com/trailofbits/manticore.git
cd manticore
pip install -e ".[native]"

Option 5: Install via Docker:

docker pull trailofbits/manticore

Once installed, the manticore CLI tool and Python API will be available.

For a development installation, see our wiki.

Usage

CLI

Manticore has a command line interface which can perform a basic symbolic analysis of a binary or smart contract. Analysis results will be placed into a workspace directory beginning with mcore_. For information about the workspace, see the wiki.

EVM

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.

Click to expand:
$ manticore examples/evm/umd_example.sol 
 [9921] m.main:INFO: Registered plugins: DetectUninitializedMemory, DetectReentrancySimple, DetectExternalCallAndLeak, ...
 [9921] m.e.manticore:INFO: Starting symbolic create contract
 [9921] m.e.manticore:INFO: Starting symbolic transaction: 0
 [9921] m.e.manticore:INFO: 4 alive states, 6 terminated states
 [9921] m.e.manticore:INFO: Starting symbolic transaction: 1
 [9921] m.e.manticore:INFO: 16 alive states, 22 terminated states
[13761] m.c.manticore:INFO: Generated testcase No. 0 - STOP(3 txs)
[13754] m.c.manticore:INFO: Generated testcase No. 1 - STOP(3 txs)
...
[13743] m.c.manticore:INFO: Generated testcase No. 36 - THROW(3 txs)
[13740] m.c.manticore:INFO: Generated testcase No. 37 - THROW(3 txs)
[9921] m.c.manticore:INFO: Results in ~/manticore/mcore_gsncmlgx
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. See a demo

Native

Click to expand:
$ manticore examples/linux/basic
[9507] m.n.manticore:INFO: Loading program examples/linux/basic
[9507] m.c.manticore:INFO: Generated testcase No. 0 - Program finished with exit status: 0
[9507] m.c.manticore:INFO: Generated testcase No. 1 - Program finished with exit status: 0
[9507] m.c.manticore:INFO: Results in ~/manticore/mcore_7u7hgfay
[9507] m.n.manticore:INFO: Total time: 2.8029580116271973

API

Manticore provides a Python programming interface which can be used to implement powerful custom analyses.

EVM

For Ethereum smart contracts, the API can be used for detailed verification of arbitrary contract properties. Users can set the starting conditions, execute symbolic transactions, then review discovered states to ensure invariants for a contract hold.

Click to expand:
from manticore.ethereum import ManticoreEVM
contract_src="""
contract Adder {
    function incremented(uint value) public returns (uint){
        if (value == 1)
            revert();
        return value + 1;
    }
}
"""
m = ManticoreEVM()

user_account = m.create_account(balance=10000000)
contract_account = m.solidity_create_contract(contract_src,
                                              owner=user_account,
                                              balance=0)
value = m.make_symbolic_value()

contract_account.incremented(value)

for state in m.ready_states:
    print("can value be 1? {}".format(state.can_be_true(value == 1)))
    print("can value be 200? {}".format(state.can_be_true(value == 200)))

Native

It is also possible to use the API to create custom analysis tools for Linux binaries. Tailoring the initial state helps avoid state explosion problems that commonly occur when using the CLI.

Click to expand:
# example Manticore script
from manticore.native import Manticore

m = Manticore.linux('./example')

@m.hook(0x400ca0)
def hook(state):
  cpu = state.cpu
  print('eax', cpu.EAX)
  print(cpu.read_int(cpu.ESP))

  m.kill()  # tell Manticore to stop

m.run()

WASM

Manticore can also evaluate WebAssembly functions over symbolic inputs for property validation or general analysis.

Click to expand:
from manticore.wasm import ManticoreWASM

m = ManticoreWASM("collatz.wasm")

def arg_gen(state):
    # Generate a symbolic argument to pass to the collatz function.
    # Possible values: 4, 6, 8
    arg = state.new_symbolic_value(32, "collatz_arg")
    state.constrain(arg > 3)
    state.constrain(arg < 9)
    state.constrain(arg % 2 == 0)
    return [arg]


# Run the collatz function with the given argument generator.
m.collatz(arg_gen)

# Manually collect return values
# Prints 2, 3, 8
for idx, val_list in enumerate(m.collect_returns()):
    print("State", idx, "::", val_list[0])

Requirements

  • Manticore requires Python 3.6 or greater
  • Manticore officially supports the latest LTS version of Ubuntu provided by Github Actions
    • Manticore has experimental support for EVM and WASM (but not native Linux binaries) on MacOS
  • We recommend running with increased stack size. This can be done by running ulimit -s 100000 or by passing --ulimit stack=100000000:100000000 to docker run

Compiling Smart Contracts

  • Ethereum smart contract analysis requires the solc program in your $PATH.
  • Manticore uses crytic-compile to build smart contracts. If you're having compilation issues, consider running crytic-compile on your code directly to make it easier to identify any issues.
  • We're still in the process of implementing full support for the EVM Istanbul instruction semantics, so certain opcodes may not be supported. In a pinch, you can try compiling with Solidity 0.4.x to avoid generating those instructions.

Using a different solver (Z3, Yices, CVC4)

Manticore relies on an external solver supporting smtlib2. Currently Z3, Yices and CVC4 are supported and can be selected via commandline or configuration settings. By default Manticore will use Z3. Once you've installed a different solver, you can choose which one to use like this: manticore --smt.solver yices

Installing CVC4

For more details go to https://cvc4.github.io/. Otherwise just get the binary and use it.

    sudo wget -O /usr/bin/cvc4 https://github.com/CVC4/CVC4/releases/download/1.7/cvc4-1.7-x86_64-linux-opt
    sudo chmod +x /usr/bin/cvc4

Installing Yices

Yices is incredibly fast. More details here https://yices.csl.sri.com/

    sudo add-apt-repository ppa:sri-csl/formal-methods
    sudo apt-get update
    sudo apt-get install yices2

Getting Help

Feel free to stop by our #manticore slack channel in Empire Hacking for help using or extending Manticore.

Documentation is available in several places:

  • The wiki contains information about getting started with Manticore and contributing

  • The API reference has more thorough and in-depth documentation on our API

  • The examples directory has some small examples that showcase API features

  • The manticore-examples repository has some more involved examples, including some real CTF problems

If you'd like to file a bug report or feature request, please use our issues page.

For questions and clarifications, please visit the discussion page.

License

Manticore is licensed and distributed under the AGPLv3 license. Contact us if you're looking for an exception to the terms.

Publications

If you are using Manticore on an academic work, consider applying to the Crytic $10k Research Prize.

Demo Video from ASE 2019

Brief Manticore demo video

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

manticore-0.3.4.dev200822.tar.gz (358.4 kB view details)

Uploaded Source

Built Distribution

manticore-0.3.4.dev200822-py3-none-any.whl (398.2 kB view details)

Uploaded Python 3

File details

Details for the file manticore-0.3.4.dev200822.tar.gz.

File metadata

  • Download URL: manticore-0.3.4.dev200822.tar.gz
  • Upload date:
  • Size: 358.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.3.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5

File hashes

Hashes for manticore-0.3.4.dev200822.tar.gz
Algorithm Hash digest
SHA256 a6aa37739ab5b939b2a17ca25ff437704011b653790fa2387f3ce81169bfee09
MD5 e2c672206b4dd3f15d50980cd57bf434
BLAKE2b-256 2cf6f0d954f7d2cf96eb7ad91d7e395c6820daea12ff3b843a26cc9792f0d1e0

See more details on using hashes here.

Provenance

File details

Details for the file manticore-0.3.4.dev200822-py3-none-any.whl.

File metadata

  • Download URL: manticore-0.3.4.dev200822-py3-none-any.whl
  • Upload date:
  • Size: 398.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.3.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5

File hashes

Hashes for manticore-0.3.4.dev200822-py3-none-any.whl
Algorithm Hash digest
SHA256 8636ed73a638f7b7abd3c8a9e1c60cccfab2cd217e68fbcdd106b08cdc2f2430
MD5 bf605f926c4b828ea0f0f1da15c23fd1
BLAKE2b-256 2ba4488d4c6821c8b31c16117ddff9b0b5813a6f4c7f4e9629170db81225d26b

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page