How yagol2020/crossfuzz works
Project Type and Purpose
• This is a command‐line, Python‐based smart‐contract fuzzing tool (“CrossFuzz”) for cross‐contract vulnerability detection on EVM (Ethereum Virtual Machine).
• It compiles Solidity contracts with solc, generates transaction sequences (including cross-contract calls), executes them in an EVM emulator, applies symbolic and taint analyses, and runs vulnerability detectors.
High-Level Architecture Components
a. CLI / Entrypoint
• CrossFuzz.py
• Parses user arguments, sets up configuration (config.py), and dispatches to either test_run() or cli() which invoke fuzzer/main.py.
b. Fuzzer Core
• fuzzer/main.py: initializes Fuzzer class (in fuzzer/engine/engine.py), orchestrates the fuzzing life-cycle
• Configuration & Compiler wrapper (comp.py): locates and invokes solc to compile contracts to bytecode and ABI
c. Fuzzing Engine (Plugin-Based)
• Components (generator, individual, population)
• Operators (mutation, crossover, selection) under fuzzer/engine/operators/
• Plugin interfaces for analysis and operators (fuzzer/engine/plugin_interfaces/)
• Fitness and Environment modules
d. EVM Execution & Analysis
• EVM emulator & block fixtures (fuzzer/evm/): loads sample block files, emulates storage, encodes inputs
• Execution-trace analysis (execution_trace_analysis.py) and symbolic taint analysis (symbolic_taint_analysis.py) under fuzzer/engine/analysis/
e. Vulnerability Detectors
• Each detector lives in fuzzer/detectors/ (e.g., integer_overflow, reentrancy, unprotected_selfdestruct)
• Pluggable: implements a common interface to inspect traces/analysis results and flag issues
f. Result Storage & Reporting
• Outputs JSON result files under fuzzer/result/
• Prints coverage, generation stats, and vulnerability reports to console
Relationships and Data Flows
• The CLI invokes the Fuzzer Core.
• Fuzzer Core uses Compiler Wrapper to compile contracts.
• Compiled bytecode & ABI feed into the EVM Emulator.
• The Engine’s Generator/Operators produce candidate transaction sequences.
• For each sequence:
→ EVM executes transactions → produces execution trace
→ Analysis plugins consume trace (symbolic / taint) → produce metadata
→ Detectors consume metadata and trace → emit vulnerability findings
→ Fitness module scores sequences → feed back into selection/mutation for next generation
• At fuzz‐time expiry or generation limit, results are aggregated and written to JSON
Architectural Patterns & Principles
• Plugin architecture for detectors and operators → extensibility
• Genetic-algorithm style loop (population, fitness, selection, mutation, crossover)
• Clear separation of concerns: CLI, compilation, execution, analysis, detection
• Configuration‐driven (config.py) to support different solc versions and EVM modes