# chijinz/visfuzz architecture

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

- Interactive diagram: https://gitdiagram.com/chijinz/visfuzz
- Repository: https://github.com/chijinz/visfuzz

## Overview

##### Project Type and Purpose
- VisFuzz is an open-source, interactive visualization tool for understanding and steering fuzzing campaigns.
- It integrates three main domains:
– Fuzzing engine (AFL + LLVM instrumentation)
– Data-serving backend (Python file server)
– Client-side web visualization (HTML/CSS/JS with D3)

##### Main Components
A. Demo Targets
– demo/json and demo/re2: sample programs compiled with LLVM plugin to emit CFG/coverage data.
B. Fuzzing Engine
– visfuzz/fuzz/afl: modified AFL binaries and harness for instrumentation modes (classic, LLVM, QEMU).
– visfuzz/fuzz/llvm: LLVM plugin and driver code (plugin.cc, afl-llvm-rt.o.c) that injects tracing hooks.
C. Data Server
– open_file_server.py: Python script that watches the AFL output directory, reads coverage/JSON files, and exposes them over HTTP (e.g., GET /data/…).
D. Visualization Front End
– visfuzz/visualization: static web assets (HTML, SCSS→CSS, JS, D3 library) served by Python’s `http.server`.
– Contains templates: index.html, cfg.html, seed.html, trend.html, plus supporting CSS (sb-admin, prism) and JS (sb-admin.js, prism.js).

##### Relationships & Data Flows
1) Instrumentation/Compilation
– LLVM plugin hooks are compiled into the demo target via `compile.sh` (demo/json, demo/re2).
– Generates JSON files representing control‐flow graphs (CFG) and basic block metadata.
2) Fuzzing
– AFL engine (invoked via `afl-fuzz -i in -o out ./app @@`) feeds mutated inputs to the instrumented demo.
– As the demo executes, it emits coverage files (bitmap, trace logs) into the `out` directory.
3) Data Serving
– open_file_server.py polls/reads the `out` directory, transforms raw coverage/JSON into HTTP-ready payloads.
– Exposes REST‐like endpoints for the front end to query in real time (e.g., /blocks, /coverage, /crashes).
4) Visualization
– The browser‐based UI (HTML + D3) fetches data from open_file_server on port 6767.
– It renders interactive charts: CFG drilldown, coverage heatmaps, seed-to-trend graphs.

##### Architectural Patterns & Principles
– Modular separation:
- Build (LLVM instrumentation)
- Fuzz Execution (AFL engine)
- Data API (Python server)
- Presentation (static web app)
– Plugin‐based extensibility: the LLVM pass can be swapped or extended for other instrumentation needs.
– File‐system as a message bus: AFL’s out directory serves as the primary integration point.
– Client‐server pattern: the front end is decoupled from the fuzzer via a simple HTTP API.

– Labels: component name + key directory path (e.g., “AFL Engine (visfuzz/fuzz/afl)”).
– Ports or communication methods: HTTP:6767, HTTP:8000, file I/O.
– Data artifacts: JSON CFG files, coverage bitmap, seed inputs, crash files.
– Optional: annotate technologies (C, C++, Python3, HTML5, D3.js, SCSS).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build/Instrumentation Layer
    subgraph "Build & Instrumentation"
        direction TB
        JsonDemo["Demo Target: json"] 
        Re2Demo["Demo Target: re2"]
        LLVMPlugin["LLVM Plugin\n(visfuzz/fuzz/llvm)"] 
    end

    %% Execution/Fuzzing Layer
    subgraph "Fuzzing Engine"
        direction TB
        AFLClassic["Classic AFL\n(visfuzz/fuzz/afl)"]
        AFLLVMMode["AFL LLVM Mode\n(visfuzz/fuzz/afl/llvm_mode)"]
        AFLQEMU["AFL QEMU Mode\n(visfuzz/fuzz/afl/qemu_mode)"]
    end

    %% Storage Layer
    FS["AFL Output Directory\n(out)"]

    %% Data/API Layer
    DataServer["open_file_server.py\n(HTTP:6767)"]

    %% Client/Visualization Layer
    subgraph "Visualization Front End"
        direction TB
        HTMLTemplates["HTML Templates\n(index.html, cfg.html, seed.html, trend.html)"]
        CSS["CSS Assets\n(visfuzz/visualization/css)"]
        SCSS["SCSS Sources\n(visfuzz/visualization/scss)"]
        JS["JS Scripts\n(visfuzz/visualization/js)"]
        D3["D3 & API Docs\n(visfuzz/visualization/d3)"]
        Vendor["Vendor & Figures\n(visfuzz/visualization/vendor)"]
        Fig["Figures\n(visfuzz/visualization/fig)"]
    end

    Browser["Browser UI\n(HTML5 + D3)"]

    %% Connections
    JsonDemo -->|compile.sh uses| LLVMPlugin
    Re2Demo -->|compile.sh uses| LLVMPlugin
    LLVMPlugin -->|produces instrumented binaries| AFLClassic
    LLVMPlugin -->|produces instrumented binaries| AFLLVMMode
    LLVMPlugin -->|produces instrumented binaries| AFLQEMU
    AFLClassic -->|writes coverage & JSON| FS
    AFLLVMMode -->|writes coverage & JSON| FS
    AFLQEMU -->|writes coverage & JSON| FS
    FS -->|polls files| DataServer
    DataServer -->|HTTP endpoints| Browser
    %% Assets flow
    DataServer --> HTMLTemplates
    DataServer --> CSS
    DataServer --> SCSS
    DataServer --> JS
    DataServer --> D3
    DataServer --> Vendor
    DataServer --> Fig
    HTMLTemplates --> Browser
    CSS --> Browser
    SCSS --> Browser
    JS --> Browser
    D3 --> Browser
    Vendor --> Browser
    Fig --> Browser

    %% Click Events
    click JsonDemo "https://github.com/chijinz/visfuzz/blob/master/demo/json/compile.sh"
    click Re2Demo "https://github.com/chijinz/visfuzz/blob/master/demo/re2/compile.sh"
    click LLVMPlugin "https://github.com/chijinz/visfuzz/tree/master/visfuzz/fuzz/llvm"
    click AFLClassic "https://github.com/chijinz/visfuzz/tree/master/visfuzz/fuzz/afl"
    click AFLLVMMode "https://github.com/chijinz/visfuzz/tree/master/visfuzz/fuzz/afl/llvm_mode"
    click AFLQEMU "https://github.com/chijinz/visfuzz/tree/master/visfuzz/fuzz/afl/qemu_mode"
    click DataServer "https://github.com/chijinz/visfuzz/blob/master/visfuzz/open_file_server.py"
    click HTMLTemplates "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization"
    click CSS "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization/css"
    click SCSS "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization/scss"
    click JS "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization/js"
    click D3 "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization/d3"
    click Vendor "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization/vendor"
    click Fig "https://github.com/chijinz/visfuzz/tree/master/visfuzz/visualization/fig"

    %% Styles
    classDef buildInst fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef exec fill:#FDEBD0,stroke:#B9770E,color:#7E5109
    classDef storage fill:#F2F4F4,stroke:#616A6B,color:#1C2833
    classDef data fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef client fill:#EBDEF0,stroke:#7D3C98,color:#4A235A

    class JsonDemo,Re2Demo,LLVMPlugin buildInst
    class AFLClassic,AFLLVMMode,AFLQEMU exec
    class FS storage
    class DataServer data
    class HTMLTemplates,CSS,SCSS,JS,D3,Vendor,Fig,Browser client
```
