fuzzinglabs / cairo-fuzzer

Cairo/Starknet smart contract fuzzer

Cairo-Fuzzer -- Cairo Smart Contract Fuzzer

Release version 1.2 Developped and maintained by @FuzzingLabs

Description:

Cairo-fuzzer is a tool designed for smart contract developers to test the security. It can be used as an independent tool or as a library.

Features:

• Run Starknet contract
• Replayer of fuzzing corpus
• Minimizer of fuzzing corpus
• Load old corpus
• Handle multiple arguments
• Workspace architecture
• Import dictionnary
• Use Cairo-fuzzer as a library

Usage:

	cargo run --release -- --cores 10 --contract ./tests1.0/fuzzinglabs.json --casm ./tests1.0/fuzzinglabs.casm --function "Fuzz_symbolic_execution"

For more usage information, follow our tutorial

CMDLINE (--help):

Usage: cairo-fuzzer [OPTIONS]

Options:
      --cores <CORES>              Set the number of threads to run [default: 1]
      --contract <CONTRACT>        Set the path of the JSON artifact to load [default: ]
      --casm <CASM>                Set the path of the JSON CASM artifact to load [default: ]
      --function <FUNCTION>        Set the function to fuzz [default: ]
      --workspace <WORKSPACE>      Workspace of the fuzzer [default: fuzzer_workspace]
      --inputfolder <INPUTFOLDER>  Path to the inputs folder to load [default: ]
      --crashfolder <CRASHFOLDER>  Path to the crashes folder to load [default: ]
      --inputfile <INPUTFILE>      Path to the inputs file to load [default: ]
      --crashfile <CRASHFILE>      Path to the crashes file to load [default: ]
      --dict <DICT>                Path to the dictionnary file to load [default: ]
      --logs                       Enable fuzzer logs in file
      --seed <SEED>                Set a custom seed (only applicable for 1 core run)
      --run-time <RUN_TIME>        Number of seconds this fuzzing session will last
      --config <CONFIG>            Load config file
      --replay                     Replay the corpus folder
      --minimizer                  Minimize Corpora
      --proptesting                Property Testing
      --analyze                    Dump functions prototypes
      --iter <ITER>                Iteration Number [default: -1]
  -h, --help                       Print help

F.A.Q

How to find a Cairo/Starknet compilation artifact (json file)?

Cairo-Fuzzer supports starknet compilation artifact (json and casm files) generated after compilation using starknet-compile and starknet-sierra-compile. Cairo-Fuzzer does not support Cairo2.0 and pure cairo contract.

How to run the tests?

cargo test

License

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

cairo-fuzzer's Issues

feature: generation of sequence of txs

• list all callable functions and arguments
• generate a sequence of transactions/function calls
• run them on the same VM with internal context that change over time

feature: Add custom seed

Add custom seed to the mutator generation so we can reproduce the execution of a fuzzer.

Create proper cli tool

• args: file
• args: core
• args: out folder
• args: number exec

Cairo-rs and starknet transaction

how does cairo-rs can handle transactions?

Update - Add support of cairo1.0

Add support of cairo1.0 and deserialization of SIerra program.

feature: add a FuzzingConfig object to simplify usage as library

A config object will simplify the usage of the fuzzer by other libraries and even internally it will make it more easy to extend, some idea of stuff that can be inside:

• debug
• minimize
• printable/only_ascii
• ignore errors
• timeout
• runs
• seed
• input/output folder

For the flags/options, we can take a look at libfuzzer options as inspirations.

JFYI: for example wasmtime is using this design with a config file: https://github.com/bytecodealliance/wasmtime/blob/2afaac5181f4b73e86fac39d095c84a9b8e59129/crates/fuzzing/src/generators/config.rs#L370

Feature - Dictionnary

• Add usage of dictionnary for fuzzing

feature: function inputs generation

• how does cairo-rs can handle transactions?
• how to detect function's arguments? (json?)
• how to create an argument's value that's fits with expected typing? (mayberelocatable macro?)
• can we generate them automatically and how?

feature : input mutator

Create or use a mutator with those features:

• mutate every byte (no restriction if printable or not)
• does not change the size of the initial input

Run local cairo json artifact with cairo-rs

Feature : Handle starknet contract / txs

How can we execute starknet contract

feature: coverage report of fuzzed cairo contract

similar to echidna: https://github.com/crytic/echidna/releases/tag/v2.0.4

Feature : Corpus replay

Add a comment to replay the corpus folder.

Feature : Corpus minimization

Add a minimizer for the input folder.

Feature : Handle Starknet contract

Fuzzing starknet contract is kind of complex and not optimized yet.
Here is a description of the workflow with the essential links :

How to use starknet-devnet and interact with starknet-contract

• Run Starknet-Devnet using rust VM
  STARKNET_DEVNET_CAIRO_VM=rust starknet-devnet
• To deploy a contract, here is a quick tutorial
• To call the contract, follow the steps here
• Load / Dump Devnet state tutorial

The fuzzer

• The fuzzer will need to run a starknet-devnet session
• Once the Devnet is setup the fuzzer will deploy the contract and save the address of the contract
• After each interaction with the devnet the fuzzer should check the TX_STATUS before doing something else.
• Sometimes, the fuzzer will need to use the mint script to fund account

Constraints

• Lot of automatization to do
• Lot of parsing to do
• No traces

add --address CLI

add --address command line that allows the user to fuzz a deployed contract by scrapping it localy

bug/crash detection mechanism

• which kind of vm halt can we have?
• how assertion are detected by cairo-rs VM?

Issue: Fuzzer does not iterate when using N number of execution

When using the fuzz_loop_for function, the fuzzer freezes and does not iterate anymore

cairo-fuzzer/cairo-libafl/src/basic_fuzzer_multithread.rs

Line 237 in 1272749

.fuzz_loop_for(

Refacto : Refacto corpus format

Refacto corpus format to a json format like the example bellow :

• For each function create a file
• The file contains a key : function_name(arg1:type , arg2:type ...)
• The key contains the input values.

{
  "function_name": "function_toto",
  "function_args": [
    "felt",
    "felt",
    "felt"
  ],
  "inputs": [
    [
      "00",
      "01",
      "02"
    ],
    [
      "00",
      "01",
      "02"
    ],
    [
      "00",
      "01",
      "02"
    ]
  ]
}

We will also need to update te minimizer and the replayer.

feature: integration of thoth

• use thoth to get interesting variable/constant
• use thoth exec symbolic to generate inputs

Use libafl to get multi-threading speed

Create cargo package

needed for integration into cairo-foundry, protostar?

Fails to build.

Currently getting these errors when trying to build the project:

error[E0412]: cannot find type `Program` in module `starknet_api::state`
   --> /home/amanusk/.cargo/git/checkouts/starknet_in_rust-5ed3fb606db6f862/87da5fb/src/services/api/contract_class.rs:204:36
    |
204 |     program: &starknet_api::state::Program,
    |                                    ^^^^^^^ not found in `starknet_api::state`
    |
help: consider importing one of these items
    |
1   + use cairo_rs::types::program::Program;
    |
1   + use starknet_api::deprecated_contract_class::Program;
    |
help: if you import `Program`, refer to it directly
    |
204 -     program: &starknet_api::state::Program,
204 +     program: &Program,
    |

error[E0609]: no field `program` on type `starknet_api::state::ContractClass`
   --> /home/amanusk/.cargo/git/checkouts/starknet_in_rust-5ed3fb606db6f862/87da5fb/src/services/api/contract_class.rs:136:63
    |
136 | ...m(&contract_class.program).unwrap();
    |                      ^^^^^^^ unknown field
    |
    = note: available fields are: `sierra_program`, `entry_point_by_type`, `abi`

error[E0609]: no field `entry_points_by_type` on type `starknet_api::state::ContractClass`
   --> /home/amanusk/.cargo/git/checkouts/starknet_in_rust-5ed3fb606db6f862/87da5fb/src/services/api/contract_class.rs:137:72
    |
137 | ...contract_class.entry_points_by_type);
    |                   ^^^^^^^^^^^^^^^^^^^^ help: a field with a similar name exists: `entry_point_by_type`

error[E0609]: no field `offset` on type `starknet_api::state::EntryPoint`
   --> /home/amanusk/.cargo/git/checkouts/starknet_in_rust-5ed3fb606db6f862/87da5fb/src/services/api/contract_class.rs:192:32
    |
192 |                 let offset = e.offset.0;
    |                                ^^^^^^ unknown field
    |
    = note: available fields are: `function_idx`, `selector`

Some errors have detailed explanations: E0412, E0609.
For more information about an error, try `rustc --explain E0412`.
error: could not compile `starknet-rs` (lib) due to 4 previous errors
warning: build failed, waiting for other jobs to finish...

Maybe we should consider adding a lock file

Feature - Add support of starknet worker with the replay/minimization function

• Verify if everything works well with the replayer function
• Add support of the starknet worker

feature: feedback mechanism

• Does cairo-rs can provide us feedback about the execution?
• should we rely on ap, fp, trace or other infos?
• How to integrate that with libafl?

Fix - Fix load corpora/crash from folder

fix pub fn load_from_folder(foldername: &String, workspace: &String) functions

Feature : Handle multiple implicit argument

For now we handle only one implicit argument (output_ptr for example)
But what if we have multiple implicit args ?

test: try to find a bug in a contract

• create a simple contract that panic/assert if the argument is a specific value (42, 123, etc.)
• give that to the fuzzer
• detect the crash
• show the result and dump the file locally

feature : Execute in same context

Is it possible to execute in the same context ?