How chijinz/visfuzz works
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).