Package: manticore
ManticoreManticore is a symbolic execution tool for analysis of smart contracts and binaries.FeaturesProgram Exploration: Manticore can execute a program with symbolic inputs and explore all the possible states it can reachInput Generation: Manticore can automatically produce concrete inputs that result in a given program stateError Discovery: Manticore can detect crashes and other failure cases in binaries and smart contractsInstrumentation: Manticore provides fine-grained control of state exploration via event callbacks and instruction hooksProgrammatic Interface: Manticore exposes programmatic access to its analysis engine via a Python APIManticore can analyze the following types of programs:Ethereum smart contracts (EVM bytecode)Linux ELF binaries (x86, x86_64, aarch64, and ARMv7)WASM ModulesInstallationNote: We recommend installing Manticore in avirtual environmentto prevent conflicts with other projects or packagesOption 1: Installing from PyPI:pipinstallmanticoreOption 2: Installing from PyPI, with extra dependencies needed to execute native binaries:pipinstall"manticore[native]"Option 3: Installing a nightly development build:pipinstall--pre"manticore[native]"Option 4: Installing from themasterbranch:gitclonehttps://github.com/trailofbits/manticore.gitcdmanticore
pipinstall-e".[native]"Option 5: Install via Docker:dockerpulltrailofbits/manticoreOnce installed, themanticoreCLI tool and Python API will be available.For a development installation, see ourwiki.UsageCLIManticore 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 withmcore_. For information about the workspace, see thewiki.EVMManticore CLI automatically detects you are trying to test a contract if (for ex.)
the contract has a.solor a.vyextension. See ademo.Click to expand:$manticoreexamples/evm/umd_example.sol[9921]m.main:INFO:Registeredplugins:DetectUninitializedMemory,DetectReentrancySimple,DetectExternalCallAndLeak,...[9921]m.e.manticore:INFO:Startingsymboliccreatecontract[9921]m.e.manticore:INFO:Startingsymbolictransaction:0[9921]m.e.manticore:INFO:4alivestates,6terminatedstates[9921]m.e.manticore:INFO:Startingsymbolictransaction:1[9921]m.e.manticore:INFO:16alivestates,22terminatedstates[13761]m.c.manticore:INFO:GeneratedtestcaseNo.0-STOP(3txs)[13754]m.c.manticore:INFO:GeneratedtestcaseNo.1-STOP(3txs)...[13743]m.c.manticore:INFO:GeneratedtestcaseNo.36-THROW(3txs)[13740]m.c.manticore:INFO:GeneratedtestcaseNo.37-THROW(3txs)[9921]m.c.manticore:INFO:Resultsin~/manticore/mcore_gsncmlgxManticore-verifierAn 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-verifierdocumentation.
See ademoNativeClick to expand:$manticoreexamples/linux/basic[9507]m.n.manticore:INFO:Loadingprogramexamples/linux/basic[9507]m.c.manticore:INFO:GeneratedtestcaseNo.0-Programfinishedwithexitstatus:0[9507]m.c.manticore:INFO:GeneratedtestcaseNo.1-Programfinishedwithexitstatus:0[9507]m.c.manticore:INFO:Resultsin~/manticore/mcore_7u7hgfay[9507]m.n.manticore:INFO:Totaltime:2.8029580116271973APIManticore provides a Python programming interface which can be used to implement powerful custom analyses.EVMFor 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:frommanticore.ethereumimportManticoreEVMcontract_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)forstateinm.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)))NativeIt 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 scriptfrommanticore.nativeimportManticorem=Manticore.linux('./example')@m.hook(0x400ca0)defhook(state):cpu=state.cpuprint('eax',cpu.EAX)print(cpu.read_int(cpu.ESP))m.kill()# tell Manticore to stopm.run()WASMManticore can also evaluate WebAssembly functions over symbolic inputs for property validation or general analysis.Click to expand:frommanticore.wasmimportManticoreWASMm=ManticoreWASM("collatz.wasm")defarg_gen(state):# Generate a symbolic argument to pass to the collatz function.# Possible values: 4, 6, 8arg=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, 8foridx,val_listinenumerate(m.collect_returns()):print("State",idx,"::",val_list[0])RequirementsManticore requires Python 3.7 or greaterManticore officially supports the latest LTS version of Ubuntu provided by Github ActionsManticore has experimental support for EVM and WASM (but not native Linux binaries) on MacOSWe recommend running with increased stack size. This can be done by runningulimit -s 100000or by passing--ulimit stack=100000000:100000000todocker runCompiling Smart ContractsEthereum smart contract analysis requires thesolcprogram in your$PATH.Manticore usescrytic-compileto build smart contracts. If you're having compilation issues, consider runningcrytic-compileon 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 (Yices, Z3, 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.
If Yices is available, Manticore will use it by default. If not, it will fall back to Z3 or CVC4. If you want to manually choose which solver to use, you can do so like this:manticore --smt.solver Z3Installing CVC4For more details go tohttps://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/cvc4Installing YicesYices is incredibly fast. More details herehttps://yices.csl.sri.com/sudo add-apt-repository ppa:sri-csl/formal-methods
    sudo apt-get update
    sudo apt-get install yices2Getting HelpFeel free to stop by our #manticore slack channel inEmpire Hackingfor help using or extending Manticore.Documentation is available in several places:Thewikicontains information about getting started with Manticore and contributingTheAPI referencehas more thorough and in-depth documentation on our APITheexamplesdirectory has some small examples that showcase API featuresThemanticore-examplesrepository has some more involved examples, including some real CTF problemsIf you'd like to file a bug report or feature request, please use ourissuespage.For questions and clarifications, please visit thediscussionpage.LicenseManticore is licensed and distributed under the AGPLv3 license.Contact usif you're looking for an exception to the terms.PublicationsManticore: A User-Friendly Symbolic Execution Framework for Binaries and Smart Contracts, Mark Mossberg, Felipe Manzano, Eric Hennenfent, Alex Groce, Gustavo Grieco, Josselin Feist, Trent Brunson, Artem Dinaburg - ASE 19If you are using Manticore on an academic work, consider applying to theCrytic $10k Research Prize.Demo Video from ASE 2019