This week, we launched five challenges as part of the Ethereal Virtual Hackathon with a prize pool of $6k (paid in crypto, obviously). This quick guide explains how to perform an analysis with MythX API.

What is MythX?

MythX is a security analysis platform for Ethereum smart contracts. It performs a comprehensive range of industry-leading analyses on smart contracts, including input fuzzing, static and symbolic analysis.

The goal of MythX is to make security analysis available to all Ethereum developers — even those who are not security-savvy. In the ongoing Hackathon we award prizes in five categories. For more details on the requirements and prizes check out the Gitcoin issues:

How MythX works

MythX clients submit Solidity code and solc compiler artifacts to the MythX API (https://api.mythx.io) for analysis. The required imput data can be generated by compiling source code with solc or solc-js. Prerequisite for analysis is that the code compiles without errors. On submitting the request, the analysis service returns an UUID which can then be used to query the analysis status and obtain the results.

The MythX OpenAPI specification describes the API request and response format in detail. However, the easiest way to get familiar with the API is by trying it yourself.

Analysis Walkthrough

In the following walkthrough we’ll use MythX-CLI, the official command line client which is based on the PythX library (if you’re a JavaScript fan and/or Python hater, have a look at MythXJS and Sabre instead).

MythX-CLI can be installed via Pip:

$ pip3 install mythx-cli

You can show the available commands by running mythx --help .

$ mythx --help Usage: mythx [OPTIONS] COMMAND [ARGS]... Your CLI for interacting with https://mythx.io/ Options: --debug Provide additional debug output

--api-key TEXT Your MythX API key from the dashboard

--username TEXT Your MythX account's username

--password TEXT Your MythX account's password

--format [simple|json|json-pretty|table|sonar] The format to display the results in [default: table]--ci Return exit code 1 if high-severity issue is found

-y, --yes Do not prompt for any confirmations

-o, --output TEXT Output file to write the results into

--help Show this message and exit. Commands: analysis Get information on running and finished analyses.

analyze Analyze the given directory or arguments with MythX.

group Create, modify, and view analysis groups.

version Display API version information.

Adding the --debug flag enables verbose debugging output. We’ll use this to get a closer look at the low-level REST requests.

Authentication

Users authenticate with an API key that can be generated on the MythX dashboard. To get started using MythX, sign up for a free account and export your API key into an environment variable named MYTHX_API_KEY .

export MYTHX_API_KEY=[your_key]

Running an Analysis

You have to submit both the Solidity abstract syntax tree (AST) and creation bytecode to MythX in order to receive a complete result. Let’s look at an example from the MythX workshop. Download the Solidity file to a local directory, then run:

$ mythx --debug analyze fallout.sol --async

This automatically compiles the Solidity file, creates an API request according to specification and sends a POST request to the /v1/analysis endpoint. The --async flag tells MythX-CLI to terminate after submitting the analysis instead of waiting for the result (normally you’ll only want to do this when dealing with long-running analyses).

The request sent to the MythX API looks as follows (bytecodes truncated for brevity):



Authorization: Bearer [Access token]

Content-Length: 18124

Content-Type: application/json POST https://api.mythx.io/v1/analyses Authorization: Bearer [Access token]Content-Length: 18124Content-Type: application/json {

"clientToolName" : "mythx-cli-0.6.1",

"noCacheLookup" : false,

"data" : {

"contractName" : "Fallout",

"sourceList" : [

"/fallout.sol"

],

"deployedBytecode" : "6080[...]",

"version" : "v0.5.0",

"bytecode" : "6060(...)",

"deployedSourceMap" : "4023:720(...)",

"sources" : {

"fallout.sol" : {

"ast" : {

[... COMPLETE AST ...]

},

"source" : "/*

* [SOURCECODE]"

}

},

"mainSource" : "fallout.sol",

"analysisMode" : "quick",

"sourceMap" : "4023:720:(...)"

}

}

Note the configuration parameters:

analysisMode: There are three analysis modes that differ in the execution time available to the fuzzer and symbolic analyzer. “Quick” mode takes up to 120 seconds to complete while the “standard” and “deep” modes take 20 and 45 minutes, respectively. The longer modes allow the analysis engine to discover more complex bugs and should be used when checking custom security properties.

There are three analysis modes that differ in the execution time available to the fuzzer and symbolic analyzer. “Quick” mode takes up to 120 seconds to complete while the “standard” and “deep” modes take 20 and 45 minutes, respectively. The longer modes allow the analysis engine to discover more complex bugs and should be used when checking custom security properties. clientToolName: This field allows you to pick an arbitrary name for your tool. We track usage of different MythX tools for the purpose of revenue sharing.

In the response to a newly submitted analysis you will receive a job UUID (allowing you to track analysis progress) as well as some useful meta data. This includes our backend tool versions, a timestamp, the user’s ID, as well as the time the job has been queued and is running. With the status field you are able to track whether your analysis has finished.

{

"apiVersion": "v1.4.14",

"harveyVersion": "0.0.18",

"maestroVersion": "1.2.10",

"maruVersion": "0.4.4",

"mythrilVersion": "0.20.4",

"queueTime": 1488,

"runTime": 11572,

"status": "Queued",

"submittedAt": "2019-04-20T09:22:56.522Z",

"submittedBy": "5c6d656206d17300110e24d6",

"uuid": "d257381b-97b0-4fce-9832-7da2f8ca2ebb"

}

Note that initially, the analysis status is shown as “queued”. Each analysis request goes through three phases:

Queued: The job has been accepted but not yet picked up by a worker. As long as the API is not overloaded, jobs should remain in “queued” state for only a few seconds.

The job has been accepted but not yet picked up by a worker. As long as the API is not overloaded, jobs should remain in “queued” state for only a few seconds. In progress: The analysis is currently running. In “quick” mode, the analysis should take 45–90 seconds to complete.

The analysis is currently running. In “quick” mode, the analysis should take 45–90 seconds to complete. Finished: The analysis is completed and the report can be obtained.

You can check the status of your analysis with:

$ mythx analysis status <UUID>

MythX then displays the status fields in table format:

Once your job is done you will see the following entry in the status field:

"status":"Finished"

Retrieving Results

Once the job is in “finished” state you can retrieve the results with the mythx analysis report command.

$ myth analysis report d257381b-97b0–4fce-9832–7da2f8ca2ebb

This sends an authenticated request to the /analysis/UUID/report endpoint:

GET https://api.mythx.io/v1/analyses/ d257381b-97b0–4fce-9832–7da2f8ca2ebb /issues HTTP/1.1 200

Authorization: Bearer [Access token]

A list of detected security issues is returned in the response.

[

{

"sourceList" : [

"fallout.sol"

],

"sourceType" : "solidity-file",

"sourceFormat" : "text",

"meta" : {

"toolName" : "maru",

"logs" : [],

"selectedCompiler" : "Unknown",

"harveyResidualRiskEstimate" : 0,

"harveyCoveredPaths" : 20,

"harveyCoveredInstructions" : 699

},

"issues" : [

{

"swcID" : "SWC-105",

"swcTitle" : "Unprotected Ether Withdrawal",

"locations" : [

{

"sourceType" : "raw-bytecode",

"sourceList" : [

"0xb6a9b14d5a809f0420fc416f237f0a71b9de5ad6a6f5de6e056aed5fc071a41b",

"0x84c9ce0c4f781028871e8e3320adb0d636ba19bd4ab785280f04a090d04b5438"

],

"sourceFormat" : "evm-byzantium-bytecode",

"sourceMap" : "955:1:1"

},

{

"sourceType" : "solidity-file",

"sourceList" : [

"/fallout.sol"

],

"sourceMap" : "4578:42:0",

"sourceFormat" : "text"

}

],

"description" : {

"tail" : "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.",

"head" : "Anyone can withdraw ETH from the contract account."

},

"severity" : "High",

"decodedLocations" : [

[],

[

{

"line" : 159,

"column" : 4

},

{

"line" : 159,

"column" : 46

}

]

],

"extra" : {

"testCases" : [

{

"steps" : [

{

"name" : "unknown",

"address" : "",

"blockTime" : "0x5bfa4639",

"blockNumber" : "0x66e393",

"blockDifficulty" : "0xa7d7343662e26",

"gasPrice" : "0x773594000",

"origin" : "0xaffeaffeaffeaffeaffeaffeaffeaffeaffeaffe",

"blockGasLimit" : "0x7d0000",

"blockCoinbase" : "0xcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcb",

"input" : "0x6080(...)",

"calldata" : "",

"gasLimit" : "0x7d000",

"value" : "0x0"

},

{

"blockGasLimit" : "0x7d0000",

"origin" : "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",

"blockCoinbase" : "0xcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcb",

"gasPrice" : "0x773594000",

"blockNumber" : "0x66e393",

"blockDifficulty" : "0xa7d7343662e26",

"blockTime" : "0x5bfa4639",

"decodedInput" : "Fal1out()",

"gasLimit" : "0x7d000",

"value" : "0x0",

"input" : "0x6fab5ddf",

"calldata" : "0x6fab5ddf",

"address" : "0x901d12ebe1b195e5aa8748e62bd7734ae19b51f",

"name" : "Fal1out()"

},

{

"input" : "0x8aa96f38",

"calldata" : "0x8aa96f38",

"gasLimit" : "0x7d000",

"value" : "0x0",

"decodedInput" : "collectAllocations()",

"blockTime" : "0x5bfa4639",

"blockNumber" : "0x66e393",

"blockDifficulty" : "0xa7d7343662e26",

"gasPrice" : "0x773594000",

"blockCoinbase" : "0xcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcb",

"origin" : "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",

"blockGasLimit" : "0x7d0000",

"name" : "collectAllocations()",

"address" : "0x901d12ebe1b195e5aa8748e62bd7734ae19b51f"

}

],

"initialState" : {

"accounts" : {

"0xaffeaffeaffeaffeaffeaffeaffeaffeaffeaffe" : {

"nonce" : 0,

"balance" : "0x2408804ca40a445",

"storage" : "{}",

"code" : ""

},

"0x901d12ebe1b195e5aa8748e62bd7734ae19b51f" : {

"nonce" : 0,

"code" : "6080(...)",

"storage" : "{}",

"balance" : "0x128000d042c488108"

},

"0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef" : {

"nonce" : 0,

"balance" : "0x2",

"storage" : "{}",

"code" : ""

}

}

}

}

],

"toolName" : "mythril",

"discoveryTime" : 62494782924

}

},

{

"swcID" : "SWC-103",

"swcTitle" : "Floating Pragma",

"locations" : [

{

"sourceMap" : "177:23:0",

"sourceFormat" : "text",

"sourceList" : [

"fallout.sol"

],

"sourceType" : "solidity-file"

}

],

"description" : {

"tail" : "It is recommended to make a conscious choice on what version of Solidity is used for compilation. Currently multiple versions \"^0.5.0\" are allowed.",

"head" : "A floating pragma is set."

},

"severity" : "Low",

"decodedLocations" : [

[

{

"column" : 0,

"line" : 7

},

{

"column" : 23,

"line" : 7

}

]

],

"extra" : {

"toolName" : "maru",

"discoveryTime" : 911614550

}

},

{

"decodedLocations" : [

[

{

"line" : 141,

"column" : 28

},

{

"line" : 141,

"column" : 39

}

]

],

"severity" : "Low",

"description" : {

"tail" : "It is best practice to set the visibility of state variables explicitly. The default visibility for \"allocations\" is internal. Other possible visibility values are public and private.",

"head" : "The state variable visibility is not set."

},

"swcTitle" : "State Variable Default Visibility",

"locations" : [

{

"sourceMap" : "4114:11:0",

"sourceFormat" : "text",

"sourceType" : "solidity-file",

"sourceList" : [

"fallout.sol"

]

}

],

"swcID" : "SWC-108",

"extra" : {

"toolName" : "maru",

"discoveryTime" : 914576950

}

}

]

}

]

How exactly those results are presented to the end user is up to the frontend tool developer. MythX-CLI will show the results in table format by default:

Client Libraries and Tools

The MythX API is just the first step for us. We aim to build an open-source ecosystem that allows developers of varying skill levels to easily build tools specific to their needs. Security is an integral part of building a sustainable ecosystem. We practice what we preach, so we already came up with a nice little set of tools and libraries that you can get inspiration from. :)

Getting Support

Processing build artifacts and source mappings correctly can become tricky for complex Soldity projects. On way to make things easier is to re-use code of the existing projects listed above. You can also get in contact with the team and other tool devs on the Discord server.

Further links