Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cleanunicorn/karl

Monitor smart contracts deployed on blockchain and test against vulnerabilities with Mythril. It was presented at DEFCON 2019.
https://github.com/cleanunicorn/karl

blockchain defcon defcon27 ethereum security smt symbolic-execution

Last synced: about 2 months ago
JSON representation

Monitor smart contracts deployed on blockchain and test against vulnerabilities with Mythril. It was presented at DEFCON 2019.

Host: GitHub
URL: https://github.com/cleanunicorn/karl
Owner: cleanunicorn
License: mit
Created: 2018-11-20T03:57:28.000Z (almost 6 years ago)
Default Branch: master
Last Pushed: 2024-07-24T17:39:35.000Z (about 2 months ago)
Last Synced: 2024-07-24T20:25:27.684Z (about 2 months ago)
Topics: blockchain, defcon, defcon27, ethereum, security, smt, symbolic-execution
Language: Python
Homepage:
Size: 4.29 MB
Stars: 314
Watchers: 14
Forks: 79
Open Issues: 28
Metadata Files:
- Readme: Readme.md
- License: License
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        # Karl

**Obsolete, not maintained anymore, don't install it, don't use it, you were warned!**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

[![CircleCI](https://circleci.com/gh/cleanunicorn/karl/tree/master.svg?style=shield)](https://circleci.com/gh/cleanunicorn/karl)

[![Codacy Badge](https://api.codacy.com/project/badge/Grade/53bb3ba0ed50447698e775edd397baa7)](https://www.codacy.com/app/lucadanielcostin/karl)

[![PyPI](https://img.shields.io/pypi/v/karl.svg)](https://pypi.org/project/karl/)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)

[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=cleanunicorn_karl&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=cleanunicorn_karl)

A monitor for smart contracts that checks for security vulnerabilities.

![Karl Vreski](./static/karl-profile.jpg)

## Video presentation

[DefCon 27](https://www.youtube.com/watch?v=Qd9ubry-c_M)

## Install

Get latest version of Karl.

```console

$ pip install --user karl

```

Install [Ganache](https://truffleframework.com/ganache) with [npm](https://www.npmjs.com/get-npm) if you want Karl to test the found vulnerabilities in a sandbox (`--sandbox=true`, disabled by default), to reduce false positives.

```console

$ 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

```console

$ karl --help

usage: karl [-h] [--rpc https://mainnet.infura.io/v3/12312312312312312312312312312312] [--rpc-tls RPC_TLS] [--block NUMBER] [--output Can be one of: stdout, posturl, folder]

            [--posturl POSTURL] [--folder-output FOLDER_OUTPUT] [--sandbox SANDBOX] [--timeout SECONDS] [--loop-bound LOOP_BOUND] [--tx-count NUMBER]

            [--modules [MODULES [MODULES ...]]] [--onchain-storage ONCHAIN_STORAGE] [--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 https://mainnet.infura.io/v3/12312312312312312312312312312312

                        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)

  --loop-bound LOOP_BOUND

                        Maximum number of loop iterations (default: 3)

  --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)

Verbosity:

  --verbose, -v         Set verbose (default: 4)

```

## Examples

### Running against the **mainnet**

```console

$ karl --rpc https://mainnet.infura.io/

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

```console

$ karl --rpc http://localhost:8545 --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

```console

$ karl --rpc [ganache](http://localhost:8545) --output=posturl --posturl=http://localhost:8080

Posturl initialized

Running

Scraping block 5

Analyzing 0x4b8e80acaE3F0db32e5d35925EfaA97D477dBb70

```

And it will send this to the listening service

```console

$ 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

```console

$ karl --rpc karl --rpc https://mainnet.infura.io/ --output folder

```

## Demo

Running locally with a specially crafted vulnerable contract:

[![asciicast](https://asciinema.org/a/222983.svg)](https://asciinema.org/a/222983)

Running on the main net using [Infura](https://infura.io/):

[![asciicast](https://asciinema.org/a/atfMqExP6RFXPzeza5adCozpg.svg)](https://asciinema.org/a/atfMqExP6RFXPzeza5adCozpg)

## Troubleshooting

### OpenSSL

If you get this error

```error

  #include 

          ^~~~~~~~~~~~~~~

compilation terminated.

error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

```

You must install the openssl source code libraries

#### Ubuntu

```console

$ sudo apt-get install libssl-dev

```

## Credits

This tool is inspired by [Bernhard's](https://github.com/b-mueller/) initial prototyping and it heavily uses his project [Myth](https://github.com/ConsenSys/mythril-classic).