x-ray

README

X-Ray: Solana Programs Static Analysis Tool

Introduction

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.

Built-in Rules for Solana Smart Contracts

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.

Installation

Using Prebuilt Binaries

Download binaries from the releases page. Unzip the tarball and add /path/to/extracted/bin to your PATH.

Using Prebuilt Container Images

Find the available container images on GitHub packages page.

Building From Source

For developers who wish to build X-Ray from source, please refer to Building from Source for detailed instructions.

Usage

Prepare a Target Repository

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-helloworld

Start a scan

docker run --rm -v $(pwd)/workspace:/workspace \
  ghcr.io/sec3-product/x-ray:latest \
  /workspace/example-helloworld

Alternatively you can use the installed native binary:

/path/to/extracted/bin/xray workspace/example-helloworld

Example Output

X-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).

Developer Guide

Please refer to Developer Guide for detailed instructions.