Skip to content
Monitor smart contracts deployed on blockchain and test against vulnerabilities with Mythril
Python Other
  1. Python 98.8%
  2. Other 1.2%
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
karl
scripts Fix real upload script Nov 26, 2018
static
.flake8
.gitignore Output validated vulnerabilites. Jul 1, 2019
.stickler.yml Specify black linter Dec 3, 2018
License
MANIFEST.in
Makefile Add makefile, requirements Nov 20, 2018
Readme.md
karl.py
requirements.txt Update mythril from 0.21.12 to 0.21.15 (#59) Aug 15, 2019
setup.py Add version cli output (#26) Feb 1, 2019

Readme.md

Karl

License: MIT CircleCI Codacy Badge PyPI Code style: black Maintainability Rating

A monitor for smart contracts that checks for security vulnerabilities.

Install

Get latest version of Karl.

$ pip install --user karl

Install Ganache with npm if you want Karl to test the found vulnerabilities in a sandbox (--sandbox=true, disabled by default), to reduce false positives.

$ npm i -g ganache-cli

Description

Karl will allow you to monitor a blockchain for vulnerable smart contracts that are being deployed.

It connects to the blockchain, monitors for new blocks and runs mythril for every new smart contract deployed.

The output can be displayed in the console, saved in files in a folder or POSTed to a URL.

Output can be:

  • stdout just posting the results to standard output
  • folder create a file for each vulnerable contract in a folder
  • posturl POST the results to an http endpoint

Help message

$ karl --help
usage: karl.py [-h]
               [--rpc HOST:PORT / ganache / infura-{mainnet, rinkeby, kovan, ropsten}]
               [--rpc-tls RPC_TLS] [--block NUMBER]
               [--output Can be one of: stdout, posturl, folder]
               [--posturl POSTURL] [--folder-output FOLDER_OUTPUT]
               [--sandbox SANDBOX] [--timeout SECONDS] [--tx-count NUMBER]
               [--modules [MODULES [MODULES ...]]]
               [--onchain-storage ONCHAIN_STORAGE]
               [--loop bound LOOP_BOUND] [--verbose] [--version]

Smart contract monitor using Mythril to find exploits

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

RPC options:
  --rpc HOST:PORT / ganache / infura-{mainnet, rinkeby, kovan, ropsten}
                        Custom RPC settings (default: None)
  --rpc-tls RPC_TLS     RPC connection over TLS (default: False)
  --block NUMBER        Start from this block, otherwise start from latest
                        (default: None)

Output:
  --output Can be one of: stdout, posturl, folder
                        Where to send results (default: stdout)
  --posturl POSTURL     Send results to a RESTful url [when using `--output
                        posturl`] (default: None)
  --folder-output FOLDER_OUTPUT
                        Save files to this folder [when using `--output
                        folder`] (default: None)

Sandbox:
  --sandbox SANDBOX     Test found transactions in a Ganache sandbox (default:
                        False)

Scan options:
  --timeout SECONDS     Scan timeout per contract (default: 600)
  --tx-count NUMBER     Maximum number of transactions (default: 3)
  --modules [MODULES [MODULES ...]]
                        Modules to use for scanning (default: ['ether_thief',
                        'suicide'])
  --onchain-storage ONCHAIN_STORAGE
                        Whether onchain access should be done or not (default:
                        True)
  --loop-bound LOOP_BOUND
                        Bound on number of loop iterations
Verbosity:
  --verbose, -v         Set verbose (default: 4)

Examples

Running against the mainnet

$ karl --rpc infura-mainnet --rpc-tls true
Stdout initialized
Running
Scraping block 6745471
Scraping block 6745472
Scraping block 6745473
Analyzing 0xf8c065bB1DafC99eE5476a2b675FAC4a036a4B07
Scraping block 6745474
Analyzing 0xC9e044D76f211E84bA651b30BBA86758ca8017c7
Scraping block 6745475
Scraping block 6745476
Scraping block 6745477
Analyzing 0x19427b8FD32dfEc78393517Da416bC5C583E6065

Running against ganache with stdout enabled

$ karl --rpc ganache --output=stdout
INFO:mythril.mythril:Using RPC settings: ('localhost', 8545, False)
INFO:mythril.analysis.modules.suicide:Suicide module: Analyzing suicide instruction
POSSIBLE VULNERABILITY!
Initial balance = 100000000000000000000, final balance = 100999999999999985722

Type = VulnerabilityType.KILL_AND_WITHDRAW
Description = Looks line anyone can kill this contract and steal its balance.
Transactions = [{'from': '0x1dF62f291b2E969fB0849d99D9Ce41e2F137006e', 'to': '0x2F2B2FE9C08d39b1F1C22940a9850e2851F40f99', 'data': '0xcbf0b0c0bebebebebebebebebebebebe1dF62f291b2E969fB0849d99D9Ce41e2F137006e', 'value': 0}]

Running against ganache with posturl enabled

$ karl --rpc ganache --output=posturl --posturl=http://localhost:8080
Posturl initialized
Running
Scraping block 5
Analyzing 0x4b8e80acaE3F0db32e5d35925EfaA97D477dBb70

And it will send this to the listening service

$ nc -l 8080
POST / HTTP/1.1
Accept-Encoding: identity
Content-Type: application/x-www-form-urlencoded
Content-Length: 725
Host: localhost:8080
User-Agent: Python-urllib/3.7
Connection: close

{
    "error": null,
    "issues": [{
        "address": 722,
        "contract": "0x4b8e80acaE3F0db32e5d35925EfaA97D477dBb70",
        "debug": "Transaction Sequence: {'1': {'calldata': '0x56885cd8', 'call_value': '0x0', 'caller': '0xaaaaaaaabbbbbbbbbcccccccddddddddeeeeeeee'}, '4': {'calldata': '0x6c343ffe', 'call_value': '0x0', 'caller': '0xaaaaaaaabbbbbbbbbcccccccddddddddeeeeeeee'}}",
        "description": "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.",
        "function": "withdrawfunds()",
        "max_gas_used": 1749,
        "min_gas_used": 1138,
        "swc-id": "105",
        "title": "Ether thief",
        "type": "Warning"
    }],
    "success": true
}

Running against the mainnet with folder output enabled

$ karl --rpc infura-mainnet --output folder

Demo

Running locally with a specially crafted vulnerable contract:

asciicast

Running on the main net using Infura:

asciicast

Troubleshooting

OpenSSL

If you get this error

  #include <openssl/aes.h>
          ^~~~~~~~~~~~~~~
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

You must install the openssl source code libraries

Ubuntu

$ sudo apt-get install libssl-dev

Credits

This tool is inspired by Bernhard's initial prototyping and it heavily uses his project Myth.

You can’t perform that action at this time.