Legions: A Tool for Ethereum Security Researchers

Legions is a handy toolkit for researchers poking around EVM nodes and smart contracts.

Consensys

Published in

ConsenSys Media

3 min readJun 9, 2020

By Shayan Eskandari, Security Engineer at ConsenSys Diligence

Have ever thought about doing one of the following things from your terminal?

Poke around a public Ethereum node JSON RPC endpoints?
See if an Ethereum node is mining or not?
Read the storage of a smart contract? And maybe see how the storage changed between different block numbers?
Get the bytecode of a smart contract without going to etherscan?
List all ENS domains names owned by an address and their expiry dates?
List all the subdomains of an ENS domain name?

If so I have a tool for you, and it goes way beyond this functionality.

Legions

During a recent client engagement we felt the need for a tool to help us poke around some forks of Geth Nodes, and we realized there were no tools available to easily connect and query common endpoints for such nodes. Even though you can manage this with libraries like web3.js, they are more like a hammer, when what we needed was a scalpel.

I suppose it is tempting, if the only tool you have is a hammer, to treat everything as if it were a nail. (Law of the instrument)
-Abraham H. Maslow (1966). The Psychology of Science

So I began building a tool for that specific engagement. As the engagement went on, certain other tasks kept cropping up, such as simple Wei to Eth conversion, or more challenging tasks like reading the storage of a smart contract.

Is there anything better than a cool command-line interface?

Legions is now open-source and also available on Pypi Package manager.

Simply install the package for python 3.6+ and everything else should be easy to find with the interactive interface:

pip install legions

A few of my favorite features are as follow:

Node detection (getnodeinfo)

Detect the type of the Node, Chain, and Network
Peer Count, Listening, Synching, and Mining status

Web3 API enumeration (investigate)

Accounts. Read coinbase, and exposed accounts of the node.
Admin. Enumerates web3.admin endpoints.

ENS Queries (ens)

List Names owned by an address
List Subdomains of an address
Query individual names

Query at latest/specific block number (query)

Balance of an address
Block details
Bytecode of the smart contract
Read storage of the smart contract (default count=10 reads the first 10 slots)

Conversions (toWei, fromWei, keccak, toChecksumAddress, etc)

ENS tools

The best interface I’ve found to poke around Ethereum Name Service registrars is the app at app.ens.domains. But, I also wanted something in my terminal, and the ability to quickly look up which domains an address owns, when they expire (😈), and other details. Legion provides an easy interface to fetch this information:

What’s next

I would like to get feedback of the community:

What is the best and worst feature of Legions?
What feature do you wish Legions had? [File a feature request]
Report any bugs or issues

Thinking about smart contract security? ConsenSys Diligence provides training, security spot checks, and smart contract auditing. Contact us.