Metadata-Version: 2.1
Name: karl
Version: 0.8.2
Summary: UNKNOWN
Home-page: UNKNOWN
Author: Daniel Luca
Author-email: daniel.luca@consensys.net
License: MIT
Description: # Karl
        
        [![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)-->
        
        ## 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 <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
        
        ```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).
Platform: UNKNOWN
Description-Content-Type: text/markdown
