This repository provides OrAudit, the tool introduced in paper "Towards Secure Oracle Usage: Understanding and Detecting the Vulnerabilities in Oracle Contracts on the Blockchain".
OrAudit is a static analysis tool designed to detect Oracle Consumer Contract Vulnerabilities (OCCVs). It is an extension built on top of Slither, a widely-used static analysis framework for Solidity.
Specifically, OrAudit extends Slither by implementing three custom detectors:
These detectors are designed to detect the following types of vulnerabilities:
| Phase | ID | Vulnerability |
|---|---|---|
| Request Handling | OCCV-1 | Missing request cancellation interface |
| OCCV-2 | Missing withdrawal after payment | |
| OCCV-3 | Missing request access control | |
| OCCV-4 | Missing request circuit breaker | |
| OCCV-5 | Missing request upgrade mechanism | |
| OCCV-6 | Improper request error handling | |
| OCCV-7 | Revert in oracle request fulfillment | |
| OCCV-8 | Insecure oracle interface usage | |
| OCCV-9 | Excessive request gas usage | |
| Data Processing | OCCV-10 | Insufficient data availability checks |
| OCCV-11 | Insufficient data integrity checks | |
| OCCV-12 | Improper modification of oracle data |
For detailed descriptions of these vulnerabilities, please refer to the Section.4 of the paper "Towards Secure Oracle Usage: Understanding and Detecting the Vulnerabilities in Oracle Contracts on the Blockchain".
Currently, OrAudit supports the detection of source code for oracle consumer contracts from four major oracle providers. The supported oracle services are as follows:
| Index | Provider | Service | Dependency |
|---|---|---|---|
| 1 | Chainlink | Data Feed | AggregatorV3Interface, AccessControlledOffchainAggregator |
| 2 | Chainlink | Data Stream | StreamsLookupCompatibleInterface |
| 3 | Chainlink | Any API | ChainlinkClient |
| 4 | Chainlink | Functions | FunctionsClient |
| 5 | Chainlink | VRF | VRFConsumerBaseV2, VRFV2WrapperConsumerBase, VRFConsumerBaseV2Plus, VRFV2PlusWrapperConsumerBase |
| 6 | Pyth | Data Feed | IPyth |
| 7 | Pyth | Data Stream | PythLazer |
| 8 | Pyth | VRF | IEntropyConsumer |
| 9 | Chronicle | Data Feed | IChronicle |
| 10 | Redstone | Data Feed | RedstoneConsumerBase |
Slither requires Python 3.8+ and solc, the Solidity compiler. We recommend using solc-select to conveniently switch between solc versions according to the detected contracts.
After cloning the repository, execute the following commands in the root directory of the repository:
python3 -m pip install .For local contracts, please use the following command:
slither --detect oracle-data-check,oracle-interface-check,oracle-protection-check YourContractPathFor deployed contracts on Etherscan, please use the following command:
slither --detect oracle-data-check,oracle-interface-check,oracle-protection-check ContractAddreess --etherscan-apikey YourApiKeyYou can obtain YourApiKey by visiting https://etherscan.io/apidashboard. For contracts deployed on other blockchains, please refer to Etherscan options and replace with the corresponding APIKEY.
The dataset directory contains all datasets referenced in this paper, including raw data, intermediate/process data, and result data.
- Dataset_120.xlsx: The experimental dataset containing 120 sampled contracts, manually annotated with OCCVs.
- EvaluationResults.xlsx: Contains all experimental process data, including: basic information of experimental dataset, statistics on analysis success rates, statistics on analysis time consumption, data used for calculating accuracy and recall.
- analyze.py: Script to run OrAudit on a specified
contracts.xlsxfile and record the analysis results. - analyze_compare.py: Script to run Slither's built-in detectors on
Dataset_120.xlsxand record the analysis results. - compare_summary.xlsx: Records the OCCVs detected by Slither's built-in detectors for the contract addresses listed in
Dataset_120.xlsx. - compare_output.log: Contains the complete output generated by Slither's built-in detectors for the contract addresses listed in
Dataset_120.xlsx.
OracleAttacks.xlsx records the results of the empirical study on oracle attacks described in Section 3 of the paper. It contains data on 52 attacks with the following columns:
- Time: The timestamp of the attack.
- Program: The affected program.
- Type: The category of the attack.
- Loss: The financial loss caused by the attack.
- Cause: The underlying cause.
- Description: A brief description of the attack.
- Recommendation: Suggested mitigation or countermeasures.
- Reference: Source or reference for the attack information.
This directory contains datasets for 13 oracle services and a crawling script. Each dataset includes the following files:
- HTML files: Raw pages retrieved from Etherscan.
- contracts.xlsx: Contract data extracted from the HTML files by dataset/contracts/get_address.py.
- analysis_summary.xlsx: Records the OCCVs detected by OrAudit for the contract addresses listed in
contracts.xlsx. - output/: Contains the complete output generated by OrAudit when analyzing the contract addresses in
contracts.xlsx.
First, please follow the instructions to install OrAudit and solc-select.
Next, run the following command to perform OCCV detection on the specified set of contracts (In analyze.py, replace the INPUT_FILE with the path to your target file) before running the script.):
python3 dataset/analyze.py
The detection results will be saved in the OUTPUT_LOG, SUMMARY_FILE.
OrAudit, built on top of Slither, also follows the AGPLv3 license.