# banditfuzz/banditfuzz_public architecture

> Architecture diagram of the GitHub repository banditfuzz/banditfuzz_public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/banditfuzz/banditfuzz_public
- Repository: https://github.com/banditfuzz/banditfuzz_public

## Overview

##### Main components
- CLI Layer
– bin/smtfuzz (SMT input generator)
– bin/banditfuzz (performance fuzzer)
- Parser
– banditfuzz/parser/parser.py
– banditfuzz/parser/settings.py
- Fuzzing Engine
– banditfuzz/fuzzers (the generic Fuzzer base class and per‐theory modules)
– banditfuzz/fuzzers/core, int, bv, fp, real, str, array_test
- Bandit Agents
– banditfuzz/agents (ε‐greedy, UCB, Thompson, Random)
- Solver Runner & Killer
– banditfuzz/solvers/runner.py
– banditfuzz/solvers/killer.sh
- Utilities
– banditfuzz/util (logger, coverage JSON parser, generic utilities)
- External SMT Solvers
– e.g. Z3, CVC4, MathSAT
- Packaging
– setup.py

##### Relationships & data flows
1. User invokes CLI (smtfuzz or banditfuzz).
2. CLI parses arguments & settings (parser module).
3. For each test iteration:
a. Fuzzing Engine selects a theory‐specific fuzzer.
b. Agent module picks a generation strategy (bandit choice).
c. Fuzzer module (literal, variable, constructs) emits an SMT script.
d. Solver Runner invokes an external SMT solver on the script.
e. Solver Runner captures performance metrics, pass/fail, timeouts.
f. Results feed back to Agent (update rewards) and Utilities (log, coverage).
4. Loop until budget or stopping condition.
5. Produce report (logger output, coverage.json).

##### Architectural patterns
- Modular plugin pattern for theory fuzzers (one folder per logic).
- Strategy pattern for bandit agents.
- Layered CLI → Parser → Core Engine → Agent → Solver
- Separation of concerns: generation, decision‐making, execution, reporting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI1["smtfuzz"]:::cli
        CLI2["banditfuzz"]:::cli
        CLI3["driver.py"]:::cli
    end

    subgraph "Parser"
        Parser1["parser.py"]:::parser
        Parser2["settings.py"]:::parser
    end

    subgraph "Fuzzing Engine"
        FE_base["fuzzer.py"]:::fuzzer
        FE_construct["construct.py"]:::fuzzer
        FE_literal["literal.py"]:::fuzzer
        FE_variable["variable.py"]:::fuzzer
        FE_node["node.py"]:::fuzzer
        subgraph "Core"
            FC_cons["constructs.py"]:::fuzzer
            FC_lit["literal.py"]:::fuzzer
            FC_quant["quantifiers.py"]:::fuzzer
            FC_var["variable.py"]:::fuzzer
        end
        subgraph "Int"
            FI_cons["constructs.py"]:::fuzzer
            FI_lit["literal.py"]:::fuzzer
            FI_var["variable.py"]:::fuzzer
        end
        subgraph "BV"
            FBV_cons["constructs.py"]:::fuzzer
            FBV_lit["literal.py"]:::fuzzer
            FBV_var["variable.py"]:::fuzzer
        end
        subgraph "FP"
            FFP_cons["constructs.py"]:::fuzzer
            FFP_lit["literal.py"]:::fuzzer
            FFP_var["variable.py"]:::fuzzer
        end
        subgraph "Real"
            FR_cons["constructs.py"]:::fuzzer
            FR_lit["literal.py"]:::fuzzer
            FR_var["variable.py"]:::fuzzer
        end
        subgraph "Str"
            FS_cons["constructs.py"]:::fuzzer
            FS_lit["literal.py"]:::fuzzer
            FS_var["variable.py"]:::fuzzer
        end
        subgraph "ArrayTest"
            FAT_cons["constructs.py"]:::fuzzer
            FAT_lit["literal.py"]:::fuzzer
            FAT_var["variable.py"]:::fuzzer
            FAT_t1["test_case_1.py"]:::fuzzer
            FAT_t2["test_case_2.py"]:::fuzzer
        end
        FE_bench["benchmark.py"]:::fuzzer
    end

    subgraph "Agents"
        A_eps["epsilon.py"]:::agent
        A_ucb["ucb.py"]:::agent
        A_thom["thompson.py"]:::agent
        A_rand["random.py"]:::agent
    end

    subgraph "Solver Runner & Killer"
        SR_runner["runner.py"]:::solver
        SR_killer["killer.sh"]:::solver
    end

    subgraph "Utilities"
        U_log["logger.py"]:::util
        U_covparser["coverage_json_parser.py"]:::util
        U_util["util.py"]:::util
        U_covfile["coverage.json"]:::util
    end

    subgraph "External SMT Solvers"
        ES1["Z3"]:::external
        ES2["CVC4"]:::external
        ES3["MathSAT"]:::external
    end

    Packaging["setup.py"]:::pack

    CLI1 -->|"args"| Parser1
    CLI2 -->|"args"| Parser1
    CLI3 -->|"invokes"| Parser1
    Parser1 -->|"config"| FE_base
    FE_base -->|"choose strategy"| A_eps
    FE_base -->|"choose strategy"| A_ucb
    FE_base -->|"choose strategy"| A_thom
    FE_base -->|"choose strategy"| A_rand
    A_eps -->|"reward"| FE_base
    A_ucb -->|"reward"| FE_base
    A_thom -->|"reward"| FE_base
    A_rand -->|"reward"| FE_base
    FE_base -->|"SMT script"| SR_runner
    SR_runner -->|"run"| ES1
    SR_runner -->|"run"| ES2
    SR_runner -->|"run"| ES3
    SR_runner -->|"metrics"| U_log
    SR_runner -->|"metrics"| U_covparser
    U_log -->|"feedback"| A_eps
    U_log -->|"report"| CLI1
    U_covfile -->|"data"| CLI2
    Packaging -.-> CLI1

    click CLI1 "https://github.com/banditfuzz/banditfuzz_public/tree/main/bin/smtfuzz"
    click CLI2 "https://github.com/banditfuzz/banditfuzz_public/tree/main/bin/banditfuzz"
    click CLI3 "https://github.com/banditfuzz/banditfuzz_public/blob/main/bin/driver.py"
    click Parser1 "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/parser/parser.py"
    click Parser2 "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/parser/settings.py"
    click FE_base "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/fuzzer.py"
    click FE_construct "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/construct.py"
    click FE_literal "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/literal.py"
    click FE_variable "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/variable.py"
    click FE_node "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/node.py"
    click FC_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/core/constructs.py"
    click FC_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/core/literal.py"
    click FC_quant "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/core/quantifiers.py"
    click FC_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/core/variable.py"
    click FI_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/int/constructs.py"
    click FI_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/int/literal.py"
    click FI_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/int/variable.py"
    click FBV_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/bv/constructs.py"
    click FBV_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/bv/literal.py"
    click FBV_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/bv/variable.py"
    click FFP_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/fp/constructs.py"
    click FFP_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/fp/literal.py"
    click FFP_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/fp/variable.py"
    click FR_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/real/constructs.py"
    click FR_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/real/literal.py"
    click FR_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/real/variable.py"
    click FS_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/str/constructs.py"
    click FS_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/str/literal.py"
    click FS_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/str/variable.py"
    click FAT_cons "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/array_test/constructs.py"
    click FAT_lit "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/array_test/literal.py"
    click FAT_var "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/array_test/variable.py"
    click FAT_t1 "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/array_test/test_case_1.py"
    click FAT_t2 "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/array_test/test_case_2.py"
    click FE_bench "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/fuzzers/benchmark.py"
    click A_eps "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/agents/epsilon.py"
    click A_ucb "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/agents/ucb.py"
    click A_thom "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/agents/thompson.py"
    click A_rand "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/agents/random.py"
    click SR_runner "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/solvers/runner.py"
    click SR_killer "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/solvers/killer.sh"
    click U_log "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/util/logger.py"
    click U_covparser "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/util/coverage_json_parser.py"
    click U_util "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/util/util.py"
    click U_covfile "https://github.com/banditfuzz/banditfuzz_public/blob/main/banditfuzz/util/coverage.json"
    click Packaging "https://github.com/banditfuzz/banditfuzz_public/blob/main/setup.py"

    classDef cli fill:#9f6,stroke:#333
    classDef parser fill:#b19cd9,stroke:#333
    classDef fuzzer fill:#1f77b4,stroke:#333
    classDef agent fill:#ffdd57,stroke:#333
    classDef solver fill:#ff7f0e,stroke:#333
    classDef util fill:#7f7f7f,stroke:#333
    classDef external fill:#ffffff,stroke:#333,stroke-dasharray: 5 5
    classDef pack fill:#e377c2,stroke:#333
```
