The X-Ray Toolchain, developed by sec3.dev, is an open-source, cross-platform command-line interface (CLI) tool designed for static analysis of Solana programs and smart contracts written in Rust. The tool parses Rust programs, generates an Abstract Syntax Tree (AST), converts the AST to an LLVM Intermediate Representation (LLVM-IR) format, and applies static analysis over the LLVM-IR to capture potential issues.
One of the primary goals of this project is to provide a general and extensible platform for Solana smart contracts code parsing and analysis. During the analysis process, it tracks and monitors relevant instructions and accounts information, facilitating detailed analysis and verification of smart contracts.
In this open-source version, we have compiled and provided several built-in common rules as examples. These rules are ready to use in analyzing your programs and serve as references for extending your own custom rules. You can define additional bug/security-related rules to suit your specific needs.
Additionally, we offer a production version of the tool, which includes a more comprehensive set of rules for scanning and analysis. We invite you to try it out for even deeper insights and broader coverage.
The X-Ray toolchain provides several built-in rules designed to detect common vulnerabilities and issues in Solana smart contracts. Below is a summary of these rules, including their descriptions and related references.
| Rule ID | Rule Name | Description | Reference |
|---|---|---|---|
| 1004 | IntegerUnderflow | Detects potential underflows in operations that could lead to erroneous behavior. | Understanding Arithmetic Overflow/Underflows in Rust and Solana |
| 1003-1006 | IntegerOverflow | Identifies add, mul and div operations that may result in overflows, causing unexpected outcomes or incorrect calculations. | Understanding Arithmetic Overflow/Underflows in Rust and Solana |
| 1007 | UnverifiedParsedAccount | Detects cases where account data is parsed without prior validation, which could lead to misuse. | Account Data Matching in Solana |
| 1010 | TypeFullCosplay | Detects type confusion vulnerabilities where fully compatible data types can be exploited. | Type Confusion Attacks in Solana |
| 1011 | TypePartialCosplay | Identifies partial type confusion vulnerabilities that might be exploited in attacks. | Type Confusion Attacks in Solana |
| 1014 | BumpSeedNotValidated | Identifies situations where the bump seed of a program address is not validated, risking misuse. | Bump Seed Canonicalization Attacks |
| 1015 | InsecurePDASharing | Warns against insecure sharing of program-derived addresses (PDA) which might be exploited. | PDA Sharing Vulnerabilities |
| 1017 | MaliciousSimulation | Detects potentially malicious code that simulates transactions, posing security risks. | Detecting Transaction Simulation |
| 2001-2005 | IncorrectLogic | Flags incorrect logic in smart contracts, such as flawed condition checks and calculations. | Various links for each specific issue: Incorrect Loop Break Logic, Incorrect Condition Check, Exponential Calculation, Incorrect Division Logic, Incorrect Token Calculation |
A full list of the supported bug patterns for Solana contracts is saved in xray.json.
- x86 and ARM64 platforms (e.g. Linux, Windows, macOS): You can run the X-Ray container version directly on these platforms. We recommend using the container version for a quick and easy start with scanning.
- x86-based Linux platforms (native or via WSL): In addition to the container version, you can download and run our precompiled binary executables.
- Other platforms: If you’re using other platforms or wish to customize or modify the code, you can build the project from source. Please refer to the Building from Source section for detailed instructions.
Find the available container images on GitHub packages page.
You can run a sanity check by running the following command to display the version:
docker run --rm ghcr.io/sec3-product/x-ray:latest -versionDownload binaries from the
releases page. Unzip the
tarball and add /path/to/extracted/bin to your PATH.
After extracting the binaries, perform a quick sanity check to verify the installation by running the following command to display the version:
/path/to/extracted/bin/xray -versionFor developers who wish to build X-Ray from source, please refer to Building from Source for detailed instructions.
To scan a target repository, simply clone it and run the container or binary CLI, providing the path to the project's root directory -- there's no need to locate the specific source code files.
For example, we will use Solana Labs' Helloworld repository. First, clone the repository to your local workspace.
mkdir -p workspace
git clone https://github.com/solana-labs/example-helloworld.git workspace/example-helloworlddocker run --rm --volume "$(pwd)/workspace:/workspace" \
ghcr.io/sec3-product/x-ray:latest \
/workspace/example-helloworldAlternatively you can use the installed native binary:
/path/to/extracted/bin/xray workspace/example-helloworldX-Ray will report each detected potential issues along with its code snippet. At the end of the output, X-Ray will provide a summary.
Analyzing /home/sec3/x-ray-toolchain/workspace/program-rust/workspace_program-rust.ll ...
Detecting Vulnerabilities
==============VULNERABLE: IntegerAddOverflow!============
Found a potential vulnerability at line 43, column 29 in workspace/program-rust/src/lib.rs
The add operation may result in overflows:
37| msg!("Greeted account does not have the correct program id");
38| return Err(ProgramError::IncorrectProgramId);
39| }
40|
41| // Increment and store the number of times the account has been greeted
42| let mut greeting_account = GreetingAccount::try_from_slice(&account.data.borrow())?;
>43| greeting_account.counter += 1;
44| greeting_account.serialize(&mut &mut account.data.borrow_mut()[..])?;
45|
46| msg!("Greeted {} time(s)!", greeting_account.counter);
47|
48| Ok(())
49|}
>>>Stack Trace:
>>>sol.process_instruction [workspace/program-rust/src/lib.rs:19]
For more info, see https://www.sec3.dev/blog/understanding-arithmetic-overflow-underflows-in-rust-and-solana-smart-contracts
--------The summary of potential vulnerabilities in workspace_program-rust.ll--------
1 unsafe operation issues
You can also find the JSON report in the .xray directory (or
workspace/.xray if using container version).
Please refer to Developer Guide for detailed instructions.