# yagol2020/crossfuzz architecture

> Architecture diagram of the GitHub repository yagol2020/crossfuzz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yagol2020/crossfuzz
- Repository: https://github.com/yagol2020/crossfuzz

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI / Entrypoint"
        CF["CrossFuzz.py"]:::external
        CFG["config.py"]:::core
    end

    %% Fuzzer Core
    subgraph "Fuzzer Core"
        FM["fuzzer/main.py"]:::core
        COMP["comp.py"]:::core
        EC["engine.py"]:::core
    end

    %% Engine Components & Plugins
    subgraph "Fuzzing Engine" 
        direction TB
        subgraph "Components" 
            GEN["generator.py"]:::core
            IND["individual.py"]:::core
            POP["population.py"]:::core
        end
        subgraph "Operators" 
            direction TB
            O_CO_IF["crossover.py"]:::plugin
            O_CO_DD["data_dependency_crossover.py"]:::plugin
            O_MUT_IF["mutation.py"]:::plugin
            O_SEL_LR["linear_ranking_selection.py"]:::plugin
            O_SEL_DD["data_dependency_linear_ranking_selection.py"]:::plugin
        end
        subgraph "Plugin Interfaces" 
            direction TB
            PI_AN["analysis.py"]:::plugin
            PI_META["metaclasses.py"]:::plugin
            PI_OP_CO["operators/crossover.py"]:::plugin
            PI_OP_MUT["operators/mutation.py"]:::plugin
            PI_OP_SEL["operators/selection.py"]:::plugin
        end
        FIT["Fitness Module"]:::core
    end

    %% EVM Execution & Analysis
    subgraph "EVM Execution & Analysis"
        direction TB
        EMU["fuzzer/evm/"]:::external
        STOR["storage_emulation.py"]:::core
        subgraph "Analysis Plugins"
            ETA["execution_trace_analysis.py"]:::plugin
            STA["symbolic_taint_analysis.py"]:::plugin
        end
    end

    %% Vulnerability Detectors
    subgraph "Vulnerability Detectors"
        DET["fuzzer/detectors/"]:::plugin
    end

    %% Results & Reporting
    subgraph "Results & Reporting"
        RS["JSON Results"]:::datastore
        CON["Console Output"]:::external
    end

    %% External Tools
    SOLC["solc Compiler"]:::external
    PYENV["Python Environment"]:::external
    FS["File System"]:::external

    %% Data Flows
    CF -->|"args & dispatch"| FM
    CF -->|"read config"| CFG
    FM -->|"init engine"| EC
    FM -->|"compile request"| COMP
    SOLC -->|"compilation"| COMP
    FS -->|"contracts"| COMP
    COMP -->|"bytecode+ABI"| EMU
    COMP -->|"bytecode+ABI"| EC
    FS -->|"blocks"| EMU
    EC -->|"generate seq"| GEN
    GEN -->|"individuals"| IND
    IND -->|"population"| POP
    POP -->|"apply operators"| O_CO_IF & O_MUT_IF & O_SEL_LR
    O_CO_IF -->|"crossover impl"| O_CO_DD
    O_SEL_LR -->|"selection impl"| O_SEL_DD
    EC -->|"seq"| EMU
    EMU -->|"exec trace"| ETA
    EMU -->|"exec trace"| STA
    ETA -->|"metadata"| DET
    STA -->|"metadata"| DET
    DET -->|"findings"| EC
    EC -->|"fitness scores"| FIT
    FIT -->|"feedback"| POP
    EC -->|"final results"| RS
    EC -->|"console stats"| CON
    CFG -->|"settings"| EC

    %% Click Events
    click CF "https://github.com/yagol2020/crossfuzz/blob/dev/CrossFuzz.py"
    click CFG "https://github.com/yagol2020/crossfuzz/blob/dev/config.py"
    click FM "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/main.py"
    click EC "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/engine.py"
    click GEN "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/components/generator.py"
    click IND "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/components/individual.py"
    click POP "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/components/population.py"
    click O_CO_IF "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/operators/crossover/crossover.py"
    click O_CO_DD "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/operators/crossover/data_dependency_crossover.py"
    click O_MUT_IF "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/operators/mutation/mutation.py"
    click O_SEL_LR "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/operators/selection/linear_ranking_selection.py"
    click O_SEL_DD "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/operators/selection/data_dependency_linear_ranking_selection.py"
    click PI_AN "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/plugin_interfaces/analysis.py"
    click PI_META "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/plugin_interfaces/metaclasses.py"
    click PI_OP_CO "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/plugin_interfaces/operators/crossover.py"
    click PI_OP_MUT "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/plugin_interfaces/operators/mutation.py"
    click PI_OP_SEL "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/plugin_interfaces/operators/selection.py"
    click EMU "https://github.com/yagol2020/crossfuzz/tree/dev/fuzzer/evm/"
    click STOR "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/evm/storage_emulation.py"
    click ETA "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/analysis/execution_trace_analysis.py"
    click STA "https://github.com/yagol2020/crossfuzz/blob/dev/fuzzer/engine/analysis/symbolic_taint_analysis.py"
    click DET "https://github.com/yagol2020/crossfuzz/tree/dev/fuzzer/detectors/"
    click RS "https://github.com/yagol2020/crossfuzz/tree/dev/fuzzer/result/"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef plugin fill:#DFFFD0,stroke:#000,stroke-width:1px
    classDef external fill:#FFD0A4,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFF2A8,stroke:#000,stroke-width:1px
```
