USCHunt is a tool for detecting, characterizing and classifying upgradeable smart contracts (USCs) for Ethereum-based blockchains. It is an augmented version of Slither, with a completely overhauled upgradeable proxy detection mechanism (found in the Contract class) as well as an all-new Slither detector.

This repository is made anonymously in support of the judging process for our paper submission to USENIX '23.

• Overhauled Contract.is_upgradeable_proxy method drastically reduces false positives by not only searching for delegatecall in the fallback function, but also extracting the target address variable and performing dataflow analysis (across multiple contracts when necessary) to locate the function that sets the implementation address.
• New proxy-patterns detector class performs rigorous classification of proxy patterns according to the thorough taxonomy presented in the paper, using a custom ProxyFeatureExtraction wrapper class for Contract objects in Slither.
• A handmade collection of unique upgradeable proxies for testing, found in the /tests/proxies/ directory.

The following tools/scripts located in the /study/scripts/ directory were used to aid our large scale analysis and evaluate its results.

• The shell script sortbyversion.sh can be used to prepare the dataset (see below) for large scale analysis by extracting the pragma solidity compiler version from the source code and sorting the files accordingly, which is necessary to tell solc-select which version to use before running Slither.
• The shell script script.sh is used for running the large scale analysis on the dataset, and time-script.sh outputs the running time of each run of USCHunt detection to a text file for analyzing the average run time of our tool.
• Several custom Python scripts were used to fix common compilation errors, often caused by the source code flattening process performed during verification.
• A handful of custom Python scripts are used for retrieving both the current and previous implementation source code for a proxy. Because this relies on the contract being confirmed to be a proxy on Etherscan, we also provide check_implementations.py to perform this confirmation on all proxies for which an implementation could not be retrieved.
• A Scrapy web scraper located in the /contract_crawl/ directory, with the spider implemented in /contract_crawl/sipders/scrapy_spider.py, can be used to scrape both the native balance (e.g., ETH for Ethereum) and total ERC-20 token balance of each proxy found in the dataset, and the compute_total_value_upgradeable.py script computes the total value held by those which USCHunt reported as upgradeable.
• Several custom Python scripts are provided for retrieving the deploy dates of contracts in the dataset and graphing the number of deployed proxies over time.
• proxy_stats.py processes the results of the large scale analysis to count how many proxies have each of the features defined in our taxonomy.
• analyze_upgradeability_checks.py processes the results of running Slither's slither-check-upgradeability tool, with our augmented upgradeability detection, on the upgradeable proxies detected in our initial analysis in order to count the number of storage layout clashes and function selector collisions detected.
• check_compatibility_checks.py and categorize_compatibility_checks.py process the results of our large scale analysis to extract the checks performed in the upgrade function and classify them according to the categories listed in Table 8 of the paper.

Our study makes use of the tintinweb/smart-contract-sanctuary repository, which contains a constantly-updated collection of all publicly verified smart contract source code published to Etherscan or its sister sites. Furthermore, for contracts that are initially reported as proxies but for which upgradeability cannot be performed, we use the custom scripts provided to fetch the current implementation from the respective block explorer, as well as the previous implementation if one exists in order to detect storage layout clashes between the two implementations. We provide the subset of our dataset (already sorted by version) which were identified as proxies (upgradeable or not) in the /study/data/ directory for the sake of reproducing our results.

Slither is a Solidity static analysis framework written in Python 3. It runs a suite of vulnerability detectors, prints visual information about contract details, and provides an API to easily write custom analyses. Slither enables developers to find vulnerabilities, enhance their code comprehension, and quickly prototype custom analyses.

• Features
• Bugs and Optimizations Detection
• Printers
• Tools
• How to Install
• Getting Help
• FAQ
• Publications

• Detects vulnerable Solidity code with low false positives (see the list of trophies)
• Identifies where the error condition occurs in the source code
• Easily integrates into continuous integration and Truffle builds
• Built-in 'printers' quickly report crucial contract information
• Detector API to write custom analyses in Python
• Ability to analyze contracts written with Solidity >= 0.4
• Intermediate representation (SlithIR) enables simple, high-precision analyses
• Correctly parses 99.9% of all public Solidity code
• Average execution time of less than 1 second per contract

Run Slither on a Truffle/Embark/Dapp/Etherlime/Hardhat application:

slither .

Run Slither on a single file:

slither tests/uninitialized.sol

• For GitHub action integration, use slither-action.
• To generate a Markdown report, use slither [target] --checklist.
• To generate a Markdown with GitHub source code highlighting, use slither [target] --checklist --markdown-root https://github.com/ORG/REPO/blob/COMMIT/ (replace ORG, REPO, COMMIT)

Use solc-select if your contracts require older versions of solc. For additional configuration, see the usage documentation.

For more information, see

• The Detector Documentation for details on each detector
• The Detection Selection to run only selected detectors. By default, all the detectors are run.
• The Triage Mode to filter individual results

• human-summary: Print a human-readable summary of the contracts
• inheritance-graph: Export the inheritance graph of each contract to a dot file
• contract-summary: Print a summary of the contracts

• call-graph: Export the call-graph of the contracts to a dot file
• cfg: Export the CFG of each functions
• function-summary: Print a summary of the functions
• vars-and-auth: Print the state variables written and the authorization of the functions
• when-not-paused: Print functions that do not use whenNotPaused modifier.

To run a printer, use --print and a comma-separated list of printers.

See the Printer documentation for the complete lists.

• slither-check-upgradeability: Review delegatecall-based upgradeability
• slither-prop: Automatic unit test and property generation
• slither-flat: Flatten a codebase
• slither-check-erc: Check the ERC's conformance
• slither-format: Automatic patch generation
• slither-read-storage: Read storage values from contracts

See the Tool documentation for additional tools.

Contact us to get help on building custom tools.

Slither requires Python 3.8+ and solc, the Solidity compiler.

pip3 install slither-analyzer

git clone https://github.com/crytic/slither.git && cd slither
python3 setup.py install

We recommend using a Python virtual environment, as detailed in the Developer Installation Instructions, if you prefer to install Slither via git.

Use the eth-security-toolbox docker image. It includes all of our security tools and every major version of Solidity in a single image. /home/share will be mounted to /share in the container.

docker pull trailofbits/eth-security-toolbox

To share a directory in the container:

docker run -it -v /home/share:/share trailofbits/eth-security-toolbox

Feel free to stop by our Slack channel (#ethereum) for help using or extending Slither.

• The Printer documentation describes the information Slither is capable of visualizing for each contract.

• The Detector documentation describes how to write a new vulnerability analyses.

• The API documentation describes the methods and objects available for custom analyses.

• The SlithIR documentation describes the SlithIR intermediate representation.

How do I exclude mocks or tests?

• View our documentation on path filtering.

How do I fix "unknown file" or compilation issues?

• Because slither requires the solc AST, it must have all dependencies available. If a contract has dependencies, slither contract.sol will fail. Instead, use slither . in the parent directory of contracts/ (you should see contracts/ when you run ls). If you have a node_modules/ folder, it must be in the same directory as contracts/. To verify that this issue is related to slither, run the compilation command for the framework you are using e.g npx hardhat compile. That must work successfully; otherwise, slither's compilation engine, crytic-compile, cannot generate the AST.

Slither is licensed and distributed under the AGPLv3 license. Contact us if you're looking for an exception to the terms.

• Slither: A Static Analysis Framework For Smart Contracts, Josselin Feist, Gustavo Grieco, Alex Groce - WETSEB '19

If you are using Slither on an academic work, consider applying to the Crytic $10k Research Prize.