Understanding the Fuzzer UI

Relevant source files

The following files were used as context for generating this wiki page:

• src/afl-fuzz.c
• src/afl-fuzz-stats.c
• include/afl-fuzz.h
• include/config.h
• README.md
• frida_mode/Scripting.md

The AFL++ Fuzzer UI is a terminal-based status screen that provides a real-time overview of a fuzzing job's progress and performance. It is the primary interface for monitoring key statistics, including execution speed, coverage discovery, crash counts, and the current fuzzing strategy. The UI is rendered by the show_stats function and its variants, which draw data directly from the main afl_state_t structure.

The UI is highly configurable through both compile-time options in config.h and runtime environment variables. While the terminal UI is the most visible output, the same statistical data is also periodically written to machine-readable files like fuzzer_stats and plot_data in the output directory for automated analysis and long-term tracking.

UI Rendering and Update Cycle

The fuzzer UI is not always active. It is disabled if the output is not a TTY (e.g., when redirecting output to a file) or if the AFL_NO_UI environment variable is set. Conversely, AFL_FORCE_UI can be used to enable it on virtual consoles.

The UI is refreshed periodically based on the UI_TARGET_HZ constant defined in config.h. The main fuzzing loop in afl-fuzz.c calls show_stats repeatedly, but the function will only redraw the screen if enough time has passed since the last update or if the force_ui_update flag is set.

Sources: src/afl-fuzz-stats.c:1100-1107, src/afl-fuzz.c:2839-2844, include/config.h:237

The following diagram illustrates the UI update logic within the main fuzzing loop.

UI Layout and Panels

The standard UI is divided into several panels, each displaying a specific category of information. The layout is constructed using box-drawing characters for a retro feel, defined in afl-fuzz-stats.c. An alternative "pizza mode" UI exists as an April Fool's joke.

The main panels of the standard UI are:

1. Process Timing: Information about the duration of the fuzzing run and time since key events.
2. Overall Results: High-level statistics about the fuzzing campaign, like cycle count and corpus size.
3. Cycle Progress: Details about the current position in the fuzzing queue.
4. Map Coverage: Statistics related to code coverage bitmap density.
5. Stage Progress: Real-time data on the current mutation stage.
6. Findings in Depth: Metrics on discovered paths, crashes, and hangs.
7. Fuzzing Strategy Yields: Effectiveness of different deterministic and havoc mutation strategies.
8. Item Geometry: Information about the structure and complexity of the inputs in the queue.

This diagram shows the logical layout of the UI panels.

Detailed Panel Breakdown

Each panel displays data pulled directly from the afl_state_t struct, which is the central state management object for the fuzzer.

Sources: include/afl-fuzz.h:356-913, src/afl-fuzz-stats.c:1150-1380

Process Timing

This panel shows timing information for the entire fuzzing session.

Field	Description	Source Variable
run time	Total wall-clock time since the fuzzer started.	afl->start_time, afl->prev_run_time
last new find	Time elapsed since the last new path was discovered.	afl->last_find_time
last saved crash	Time elapsed since the last unique crash was saved.	afl->last_crash_time
last saved hang	Time elapsed since the last unique hang was saved.	afl->last_hang_time

Sources: src/afl-fuzz-stats.c:1182-1210

Overall Results

This panel provides high-level statistics about the state of the fuzzing queue and discovered vulnerabilities.

Field	Description	Source Variable
cycles done	Number of complete passes through the fuzzing queue.	afl->queue_cycle
corpus count	Total number of items in the queue.	afl->queued_items
saved crashes	Number of unique crashing test cases saved. A + indicates the limit (KEEP_UNIQUE_CRASH) has been reached.	afl->saved_crashes
saved hangs	Number of unique test cases that cause a timeout. A + indicates the limit (KEEP_UNIQUE_HANG) has been reached.	afl->saved_hangs

Sources: src/afl-fuzz-stats.c:1189-1215, include/config.h:124-125

Stage Progress & Fuzzing Strategy

These sections detail the performance of the various mutation strategies employed by AFL++.

Field	Description	Source Variable
now trying	The current mutation strategy being applied (e.g., bitflip, havoc).	afl->stage_name
stage execs	Number of executions performed in the current stage vs. the total planned for this stage.	afl->stage_cur / afl->stage_max
total execs	Total number of executions for the entire campaign.	afl->fsrv.total_execs
exec speed	Smoothed average of executions per second.	afl->stats_avg_exec
bit flips, arithmetics, etc.	A ratio of finds/cycles for each deterministic stage, showing its effectiveness.	afl->stage_finds[], afl->stage_cycles[]

Sources: src/afl-fuzz-stats.c:1245-1350

Fuzzing State

The final line of the UI indicates the current high-level strategy and the fuzzer's operational state, determined by the get_fuzzing_state function.

• Strategy: Shows whether the fuzzer is in explore mode (focusing on new coverage) or exploit mode (focusing on finding crashes). This can be manually set or automatically switched.
• State: A descriptor of the current phase, based on how long it has been since a new path was found.

Sources: src/afl-fuzz-stats.c:29-69, src/afl-fuzz-stats.c:1378-1381

The following state machine shows how the fuzzer state is determined.

Configuration and Customization

The UI's appearance and behavior can be modified through compile-time macros and runtime environment variables.

Compile-Time Configuration

These macros are defined in include/config.h and require recompilation to take effect.

Macro	Description	Default Value
USE_COLOR	Enables colored terminal output.	Defined
ALWAYS_COLORED	If USE_COLOR is defined, this forces color on, ignoring AFL_NO_COLOR.	Defined
FANCY_BOXES	Enables the box-drawing character UI style.	Defined
UI_TARGET_HZ	Target refresh frequency for the UI in Hertz.	5
STATS_UPDATE_SEC	Frequency in seconds to update the fuzzer_stats file.	60
PLOT_UPDATE_SEC	Frequency in seconds to update the plot_data file.	5

Sources: include/config.h:98-107, include/config.h:113, include/config.h:237-242

Runtime Configuration

These environment variables can be set before launching afl-fuzz to alter UI behavior.

Variable	Description
AFL_NO_UI	Disables the status screen entirely.
AFL_FORCE_UI	Forces the status screen to be shown, even on non-TTY outputs.
AFL_NO_COLOR	Disables colored output if not compiled with ALWAYS_COLORED.
AFL_NO_CPU_RED	Prevents the CPU load indicator from turning red at high utilization.
AFL_PIZZA_MODE	Enables an alternative "pizza-themed" UI.
AFL_STATSD	Enables StatsD metrics collection.
AFL_STATSD_HOST	Sets the StatsD host.
AFL_STATSD_PORT	Sets the StatsD port.

Sources: src/afl-fuzz.c:400-500

Data Output Files

In addition to the on-screen display, afl-fuzz writes statistics to several files in the output directory. This allows for programmatic monitoring and post-fuzzing analysis.

*fuzzer_stats**: A machine-readable text file containing most of the same statistics shown in the UI. It is updated periodically according to STATS_UPDATE_SEC.

• plot_data: A CSV file intended for generating graphs of fuzzing progress over time. It logs metrics like total execs, corpus count, and unique crashes.
• fuzzer_setup: A file that records the command line and environment variables used to launch the fuzzer, aiding in reproducibility.

Sources: src/afl-fuzz-stats.c:73-89, src/afl-fuzz-stats.c:215-288, src/afl-fuzz-stats.c:293-333

Conclusion

The AFL++ Fuzzer UI is a dense but powerful tool for real-time monitoring of a fuzzing campaign. It provides immediate feedback on everything from execution speed and code coverage to the effectiveness of different mutation strategies. By understanding the data presented in each panel, which corresponds to variables within the fuzzer's state, a user can effectively gauge the health and progress of their fuzzing job. For automated analysis or integration with other tools, the same information is available in the fuzzer_stats and plot_data files in the output directory.