{ "info": { "author": "Daniel Luca", "author_email": "daniel.luca@consensys.net", "bugtrack_url": null, "classifiers": [], "description": "# Theo\n\n![License](https://img.shields.io/github/license/cleanunicorn/theo.svg)\n[![CircleCI](https://circleci.com/gh/cleanunicorn/theo/tree/master.svg?style=shield)](https://circleci.com/gh/cleanunicorn/theo)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/71da66211eff42f298062a883b7fa5e9)](https://www.codacy.com/app/lucadanielcostin/theo)\n[![PyPI](https://img.shields.io/pypi/v/theo.svg)](https://pypi.org/project/theo/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\nTheo aims to be an exploitation framework and a blockchain recon and interaction tool.\n\nFeatures:\n\n- Automatic smart contract scanning which generates a list of possible exploits.\n- Sending transactions to exploit a smart contract.\n- Transaction pool monitor.\n- Web3 console\n- Frontrunning and backrunning transactions.\n- Waiting for a list of transactions and sending out others.\n- Estimating gas for transactions means only successful transactions are sent.\n- Disabling gas estimation will send transactions with a fixed gas quantity.\n\n\n\nHe knows [Karl](https://github.com/cleanunicorn/karl) from work.\n\nTheo's purpose is to fight script kiddies that try to be leet hackers. He can listen to them trying to exploit his honeypots and make them lose their funds, for his own gain.\n\n> \"You didn't bring me along for my charming personality.\"\n\n## Install\n\nTheo is available as a PyPI package:\n\n```console\n$ pip install theo\n$ theo --help\nusage: theo [-h] [--rpc-http RPC_HTTP] [--rpc-ws RPC_WS] [--rpc-ipc RPC_IPC]\n [--account-pk ACCOUNT_PK] [--contract ADDRESS]\n [--skip-mythril SKIP_MYTHRIL] [--load-file LOAD_FILE] [--version]\n\nMonitor contracts for balance changes or tx pool.\n\noptional arguments:\n -h, --help show this help message and exit\n --rpc-http RPC_HTTP Connect to this HTTP RPC (default:\n http://127.0.0.1:8545)\n --account-pk ACCOUNT_PK\n The account's private key (default: None)\n --contract ADDRESS Contract to monitor (default: None)\n --skip-mythril SKIP_MYTHRIL\n Don't try to find exploits with Mythril (default:\n False)\n --load-file LOAD_FILE\n Load exploit from file (default: )\n --version show program's version number and exit\n\nRPC connections:\n --rpc-ws RPC_WS Connect to this WebSockets RPC (default: None)\n --rpc-ipc RPC_IPC Connect to this IPC RPC (default: None)\n```\n\nInstall from sources\n\n```console\n$ git clone https://github.com/cleanunicorn/theo\n$ cd theo\n$ virtualenv ./venv\n$ . ./venv/bin/activate\n$ pip install -r requirements.txt\n$ pip install -e .\n$ theo --help\n```\n\nRequirements: \n\n- Python 3.5 or higher.\n- An Ethereum node with RPC available. [Ganache](https://github.com/trufflesuite/ganache-cli) works really well for testing or for validating exploits.\n\n## Demos\n\n### Find exploit and execute it\n\nScan a smart contract, find exploits, exploit it:\n\n- Start Ganache as our local Ethereum node\n- Deploy the vulnerable contract (happens in a different window)\n- Scan for exploits\n- Run exploit\n\n[![asciicast](https://asciinema.org/a/CgTH8tIAoGsgEYsd7XN65tJSp.svg)](https://asciinema.org/a/CgTH8tIAoGsgEYsd7XN65tJSp?speed=2)\n\n### Frontrun victim\n\nSetup a honeypot, deploy honeypot, wait for attacker, frontrun:\n\n- Start geth as our local Ethereum node\n- Start mining\n- Deploy the honeypot\n- Start Theo and scan the mem pool for transactions\n- Frontrun the attacker and steal his ether\n\n[![asciicast](https://asciinema.org/a/n2HnSJvgopf8AKCoSfEJVgvxU.svg)](https://asciinema.org/a/n2HnSJvgopf8AKCoSfEJVgvxU?speed=2)\n\n## Usage\n\n### Help screen\n\nIt's a good idea to check the help screen first.\n\n```console\n$ theo --help\nusage: theo [-h] [--rpc-http RPC_HTTP] [--rpc-ws RPC_WS] [--rpc-ipc RPC_IPC]\n [--account-pk ACCOUNT_PK] [--contract ADDRESS] [--skip-mythril]\n [--load-file LOAD_FILE] [--version]\n\nMonitor contracts for balance changes or tx pool.\n\noptional arguments:\n -h, --help show this help message and exit\n --rpc-http RPC_HTTP Connect to this HTTP RPC (default:\n http://127.0.0.1:8545)\n --account-pk ACCOUNT_PK\n The account's private key (default: None)\n --contract ADDRESS Contract to interact with (default: None)\n --skip-mythril Skip scanning the contract with Mythril (default:\n False)\n --load-file LOAD_FILE\n Load exploit from file (default: )\n --version show program's version number and exit\n\nRPC connections:\n --rpc-ws RPC_WS Connect to this WebSockets RPC (default: None)\n --rpc-ipc RPC_IPC Connect to this IPC RPC (default: None)\n```\n\n### Symbolic execution\n\nA list of exploits is automatically identified using [mythril](https://github.com/ConsenSys/mythril).\n\nStart a session by running:\n\n```console\n$ theo --contract= --account-pk=\nScanning for exploits in contract: 0xa586074fa4fe3e546a132a16238abe37951d41fe\nConnecting to HTTP: http://127.0.0.1:8545.\nFound exploits(s):\n [Exploit: (txs=[Transaction {Data: 0xcf7a8965, Value: 1000000000000000000}])]\n\nA few objects are available in the console:\n- `exploits` is an array of loaded exploits found by Mythril or read from a file\n- `w3` an initialized instance of web3py for the provided HTTP RPC endpoint\n\nCheck the readme for more info:\nhttps://github.com/cleanunicorn/theo\n\n>>> \n```\n\nIt will analyze the contract and will find a list of available exploits.\n\nYou can see the available exploits found. In this case one exploit was found. Each exploit is an [Exploit](https://github.com/cleanunicorn/theo/blob/master/theo/exploit/exploit.py) object.\n\n```console\n>>> exploits[0]\nExploit: (txs=[Transaction: {'input': '0xcf7a8965', 'value': '0xde0b6b3a7640000'}])\n```\n\n### Running exploits\n\nThe exploit steps can be run by calling `.execute()` on the exploit object. The transactions will be signed and sent to the node you're connected to.\n\n```console\n>>> exploits[0].execute()\n2019-07-22 11:26:12,196 - Sending tx: {'to': '0xA586074FA4Fe3E546A132a16238abe37951D41fE', 'gasPrice': 1, 'gas': 30521, 'value': 1000000000000000000, 'data': '0xcf7a8965', 'nonce': 47} \n2019-07-22 11:26:12,200 - Waiting for 0x41b489c78f654cab0b0451fc573010ddb20ee6437cdbf5098b6b03ee1936c33c to be mined... \n2019-07-22 11:26:16,337 - Mined \n2019-07-22 11:26:16,341 - Initial balance: 1155999450759997797167 (1156.00 ether) \n2019-07-22 11:26:16,342 - Final balance: 1156999450759997768901 (1157.00 ether) \n```\n\n### Frontrunning\n\nYou can start the frontrunning monitor to listen for other hackers trying to exploit the honeypot.\n\nUse `.frontrun()` to start listening for the exploit and when found, send a transaction with a higher gas price.\n\n```console\n>>> exploits[0].frontrun()\n2019-07-22 11:22:26,285 - Scanning the mem pool for transactions... \n2019-07-22 11:22:45,369 - Found tx: 0xf6041abe6e547cea93e80a451fdf53e6bdae67820244246fde44098f91ce1c20 \n2019-07-22 11:22:45,375 - Sending tx: {'to': '0xA586074FA4Fe3E546A132a16238abe37951D41fE', 'gasPrice': '0x2', 'data': '0xcf7a8965', 'gas': 30522, 'value': 1000000000000000000, 'nonce': 45} \n2019-07-22 11:22:45,380 - Waiting for 0xa73316daf806e7eef83d09e467c32ce5faa239c6eda3a270a8ce7a7aae48fb7e to be mined... \n2019-07-22 11:22:56,852 - Mined \n```\n\n> \"Oh, my God! The quarterback is toast!\"\n\nThis works very well for some specially crafted [contracts](./contracts/) or some other vulnerable contracts, as long as you make sure frontrunning is in your favor.\n\n### Load transactions from file\n\nInstead of identifying the exploits with mythril, you can specify the list of exploits yourself.\n\nCreate a file that looks like this [exploits.json](./test/input-tx.json):\n\n```json\n[\n [\n {\n \"name\": \"claimOwnership()\",\n \"input\": \"0x4e71e0c8\",\n \"value\": \"0xde0b6b3a7640000\"\n },\n {\n \"name\": \"retrieve()\",\n \"input\": \"0x2e64cec1\",\n \"value\": \"0x0\"\n }\n ],\n [\n {\n \"name\": \"claimOwnership()\",\n \"input\": \"0x4e71e0c8\",\n \"value\": \"0xde0b6b3a7640000\"\n }\n ]\n]\n```\n\nThis one defines 2 exploits, the first one has 2 transactions and the second one only has 1 transaction. \n\nYou can load it with: \n\n```console\n$ theo --load-file=./exploits.json\n```\n\n# Troubleshooting\n\n## openssl/aes.h: No such file or directory\n\nIf you get this error, you need the libssl source libraries:\n\n```\n scrypt-1.2.1/libcperciva/crypto/crypto_aes.c:6:10: fatal error: openssl/aes.h: No such file or directory\n #include \n ^~~~~~~~~~~~~~~\n compilation terminated.\n error: command 'x86_64-linux-gnu-gcc' failed with exit status 1\n \n ----------------------------------------\nCommand \"/usr/bin/python3 -u -c \"import setuptools, tokenize;__file__='/tmp/pip-build-5rl4ep94/scrypt/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\\r\\n', '\\n');f.close();exec(compile(code, __file__, 'exec'))\" install --record /tmp/pip-mnbzx9qe-record/install-record.txt --single-version-externally-managed --compile\" failed with error code 1 in /tmp/pip-build-5rl4ep94/scrypt/\n```\n\nOn Ubuntu you can install them with:\n```console\n$ sudo apt install libssl-dev\n```", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/cleanunicorn/theo", "keywords": "", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "theo", "package_url": "https://pypi.org/project/theo/", "platform": "", "project_url": "https://pypi.org/project/theo/", "project_urls": { "Homepage": "https://github.com/cleanunicorn/theo" }, "release_url": "https://pypi.org/project/theo/0.8.2/", "requires_dist": null, "requires_python": "", "summary": "", "version": "0.8.2" }, "last_serial": 5660516, "releases": { "0.2.1": [ { "comment_text": "", "digests": { "md5": "aba89752caf701a11b23a299babea4b1", "sha256": "11c52daaf500961c9d848c2080ef12e45cb6c3517cc0c223477ce2d427f57cba" }, "downloads": -1, "filename": "theo-0.2.1.tar.gz", "has_sig": false, "md5_digest": "aba89752caf701a11b23a299babea4b1", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10623, "upload_time": "2019-07-20T20:40:23", "url": "https://files.pythonhosted.org/packages/4a/f6/06213089f71c690e9f1f2381b3f197836b1effc85bb8867faf655e8c00a4/theo-0.2.1.tar.gz" } ], "0.2.3": [ { "comment_text": "", "digests": { "md5": "30f2db541b814debcb7f674c3471541f", "sha256": "b17b718b9461b2a0de1c6722b80137287d9a4e539ac104b33447c34804d77308" }, "downloads": -1, "filename": "theo-0.2.3.tar.gz", "has_sig": false, "md5_digest": "30f2db541b814debcb7f674c3471541f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10846, "upload_time": "2019-07-20T20:49:35", "url": "https://files.pythonhosted.org/packages/3c/89/45ee6cb3c8a99d37112e662c63c0ad3805f156627b4bfc89b67988a0de01/theo-0.2.3.tar.gz" } ], "0.3.2": [ { "comment_text": "", "digests": { "md5": "fa9964fb2182b93e80e04c0a2943a3be", "sha256": "e462642a47a93d5ebb8a54deaf59b8cda3253aa739dbde40b4a6827aaa554a2d" }, "downloads": -1, "filename": "theo-0.3.2.tar.gz", "has_sig": false, "md5_digest": "fa9964fb2182b93e80e04c0a2943a3be", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10874, "upload_time": "2019-07-20T22:03:02", "url": "https://files.pythonhosted.org/packages/b4/c8/8e7b6fc98ae462bc5ed13aadb10639f7bb16f4faf4ce87b1c3e7ee2664b7/theo-0.3.2.tar.gz" } ], "0.3.3": [ { "comment_text": "", "digests": { "md5": "218667bdcfb8bb7b4cde80b6b0952c6f", "sha256": "e7482f0e697664b4d05a08fe7152f8b2fde0bb612272dcd32f8809350b352a2c" }, "downloads": -1, "filename": "theo-0.3.3.tar.gz", "has_sig": false, "md5_digest": "218667bdcfb8bb7b4cde80b6b0952c6f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10875, "upload_time": "2019-07-20T23:00:53", "url": "https://files.pythonhosted.org/packages/72/97/5eb40d97401005196cea95ed1710d07345ed396d97a943592c3fdf5e6e3c/theo-0.3.3.tar.gz" } ], "0.4.0": [ { "comment_text": "", "digests": { "md5": "b863482417153c07907225b778ad156b", "sha256": "fe5838abd83f9317ab6a3b1e2b5f525ae4e787be7493e395f343d0dbcda37469" }, "downloads": -1, "filename": "theo-0.4.0.tar.gz", "has_sig": false, "md5_digest": "b863482417153c07907225b778ad156b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12371, "upload_time": "2019-07-22T08:57:26", "url": "https://files.pythonhosted.org/packages/d7/5e/d6532f230bfdbd6f5ae1a68940fd3031082113e67f639cc20424b365a3ad/theo-0.4.0.tar.gz" } ], "0.4.1": [ { "comment_text": "", "digests": { "md5": "619932c868d34d4c297ac46a58bb606c", "sha256": "ad294130137c1d13df66a22cba9b928912b8872f4ff4d74a27acb6fa9dd84ea0" }, "downloads": -1, "filename": "theo-0.4.1.tar.gz", "has_sig": false, "md5_digest": "619932c868d34d4c297ac46a58bb606c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12363, "upload_time": "2019-07-22T10:17:03", "url": "https://files.pythonhosted.org/packages/66/6d/14729450a54454cfe3075bf1da2bf157c6646ff8fcc84ee081e866ba4d6e/theo-0.4.1.tar.gz" } ], "0.4.3": [ { "comment_text": "", "digests": { "md5": "f8956f4d4210707cb260cf5841288db0", "sha256": "e1390e1155c832c718cb530222a69b8b4b2e1fdacee59b49a6d583c8a9fafe3a" }, "downloads": -1, "filename": "theo-0.4.3.tar.gz", "has_sig": false, "md5_digest": "f8956f4d4210707cb260cf5841288db0", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12387, "upload_time": "2019-07-22T15:11:50", "url": "https://files.pythonhosted.org/packages/e0/58/c8a8076a3ab991a7a02d1e607a57d8d19d602e13cbd05d453da0f7a29cbf/theo-0.4.3.tar.gz" } ], "0.4.4": [ { "comment_text": "", "digests": { "md5": "3a050dca3760f75031563299ef904dcf", "sha256": "400cb3f2c02dc3a32897fb46796d89799020960a35132998a5983553731cd1b1" }, "downloads": -1, "filename": "theo-0.4.4.tar.gz", "has_sig": false, "md5_digest": "3a050dca3760f75031563299ef904dcf", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12424, "upload_time": "2019-07-22T19:20:29", "url": "https://files.pythonhosted.org/packages/07/b1/d52a2132ab062e1dc9e715ac1bda2b549759d5871bc6180eb7df6d3ec9a4/theo-0.4.4.tar.gz" } ], "0.5.6": [ { "comment_text": "", "digests": { "md5": "4cd81f19ed86fc297fb9a74f804542df", "sha256": "c6236db4ebc4359979ac8cf476928f67a6190e0c9b38ca3e2d50fd2f34085aef" }, "downloads": -1, "filename": "theo-0.5.6.tar.gz", "has_sig": false, "md5_digest": "4cd81f19ed86fc297fb9a74f804542df", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12689, "upload_time": "2019-07-23T13:19:11", "url": "https://files.pythonhosted.org/packages/da/ba/8669d0fe4407cc3e3f37ee8f77d03ede0fd661a5b458af385be01307e804/theo-0.5.6.tar.gz" } ], "0.7.0": [ { "comment_text": "", "digests": { "md5": "10c04a64600b8a3c0b24780ccbf42284", "sha256": "3d8ef12d610b4dfcf16b0316f3de93ee3ba982c0e3a1226a4b308bd0b3609f1e" }, "downloads": -1, "filename": "theo-0.7.0.tar.gz", "has_sig": false, "md5_digest": "10c04a64600b8a3c0b24780ccbf42284", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13566, "upload_time": "2019-07-24T07:31:00", "url": "https://files.pythonhosted.org/packages/4d/08/aa9e9f5179f69b61661097c598442490277955bead3a172b2a12d12f8bb2/theo-0.7.0.tar.gz" } ], "0.7.1": [ { "comment_text": "", "digests": { "md5": "85668234704f9c9613b2d9ebd225f7d3", "sha256": "84652196fd12e88184e9262cd07d8348fb8f3bcc7eda124d00244bf57f5f0604" }, "downloads": -1, "filename": "theo-0.7.1.tar.gz", "has_sig": false, "md5_digest": "85668234704f9c9613b2d9ebd225f7d3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14814, "upload_time": "2019-07-24T20:23:53", "url": "https://files.pythonhosted.org/packages/62/a2/76e0dc52781dc210fd72305ba89f6561b6e869ffc30848f782224fc0137e/theo-0.7.1.tar.gz" } ], "0.7.3": [ { "comment_text": "", "digests": { "md5": "d05d52842fd462ec600cac68e4c9037f", "sha256": "69df81239873c700fc9f3f6aa0a89148c3182b4a9548b9b47f24c1c8d8024942" }, "downloads": -1, "filename": "theo-0.7.3.tar.gz", "has_sig": false, "md5_digest": "d05d52842fd462ec600cac68e4c9037f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14799, "upload_time": "2019-07-24T21:48:06", "url": "https://files.pythonhosted.org/packages/90/3a/4d6bb44f01119476b2c4445ad9116fd307f894b68e7e152b3ce2e4677d66/theo-0.7.3.tar.gz" } ], "0.7.4": [ { "comment_text": "", "digests": { "md5": "83e044bb40fe7c26265fca5156c87bc7", "sha256": "9a20181b47f3e826a8c5c74de8fb65736c925e4e1523a06821fa5174ce8e71bb" }, "downloads": -1, "filename": "theo-0.7.4.tar.gz", "has_sig": false, "md5_digest": "83e044bb40fe7c26265fca5156c87bc7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14819, "upload_time": "2019-07-25T09:59:30", "url": "https://files.pythonhosted.org/packages/d7/d2/442fed47c573c8a0859ca49643801cb38d85775ba7084feb43f69323ed5f/theo-0.7.4.tar.gz" } ], "0.8.1": [ { "comment_text": "", "digests": { "md5": "e0a24055c5485f2e44054ca3c8b95222", "sha256": "99dc36334658abfe8f3a2db2794c8f4dd748aebe1160fbb2a656e87fc0906a37" }, "downloads": -1, "filename": "theo-0.8.1.tar.gz", "has_sig": false, "md5_digest": "e0a24055c5485f2e44054ca3c8b95222", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14842, "upload_time": "2019-07-27T16:46:33", "url": "https://files.pythonhosted.org/packages/cb/a1/df7b6faf7f9c835b59854cb0d7c94401c37cb22eae023838895393c23d03/theo-0.8.1.tar.gz" } ], "0.8.2": [ { "comment_text": "", "digests": { "md5": "5e093f207f7a44e28f350c3484694fa8", "sha256": "4f491feae6636dc779e8f08adec78d0b9c4ccee8fcb2c7a4147a00d78b774fb4" }, "downloads": -1, "filename": "theo-0.8.2.tar.gz", "has_sig": false, "md5_digest": "5e093f207f7a44e28f350c3484694fa8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14849, "upload_time": "2019-08-10T23:06:34", "url": "https://files.pythonhosted.org/packages/b2/3b/e7b02b0a8a2946ae05e8f47f8dcfb83b666b2aaf88de3db156abf8365ac8/theo-0.8.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "5e093f207f7a44e28f350c3484694fa8", "sha256": "4f491feae6636dc779e8f08adec78d0b9c4ccee8fcb2c7a4147a00d78b774fb4" }, "downloads": -1, "filename": "theo-0.8.2.tar.gz", "has_sig": false, "md5_digest": "5e093f207f7a44e28f350c3484694fa8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14849, "upload_time": "2019-08-10T23:06:34", "url": "https://files.pythonhosted.org/packages/b2/3b/e7b02b0a8a2946ae05e8f47f8dcfb83b666b2aaf88de3db156abf8365ac8/theo-0.8.2.tar.gz" } ] }