Documentation Index
Fetch the complete documentation index at: https://mintlify.com/AdithyaaSivamal/Agentic-AFL/llms.txt
Use this file to discover all available pages before exploring further.
agentic-afl fuzz launches an AFL++ fuzzing campaign with the Agentic-AFL agent running as an asynchronous co-process. It manages the full lifecycle: starting AFL++, running the AgentLoop, detecting stalls, solving constraints, and injecting payloads.
Synopsis
Required Arguments
Path to the AFL++-instrumented harness binary. Must exist and be compiled with
afl-cc. Agentic-AFL resolves this to an absolute path before launching AFL++.Directory containing initial seed corpus files. The directory must exist and contain at least one file before the campaign starts.
Optional Flags
Campaign duration. Accepts
h (hours), m (minutes), or s (seconds). Examples: "6h", "30m", "90s". The value is parsed internally to seconds and controls the campaign wall-clock runtime.Minutes of edge plateau before the agent triggers. Lower values catch stalls faster but may cause false triggers early in the campaign when edge growth is naturally slow.
Stdout/stderr marker the harness prints when the math wall is bypassed. Used to detect bypass and trigger Level 3 mutator deployment. Set this to match whatever your harness emits on a successful constraint pass.
Path to a Python AFL++ custom mutator script. Deployed automatically after bypass is detected (Level 3). The script is passed directly to AFL++ via the
AFL_CUSTOM_MUTATOR_LIBRARY environment variable.Directory for JSON campaign result files. Files are named
<target>_<timestamp>.json. The directory is created if it does not already exist. These JSON files are the input for agentic-afl plot.Campaign name. Defaults to the harness filename stem (e.g., a harness at
./build/dnp3_harness produces the name dnp3_harness). Used as a label in the campaign summary and in the log filename.Enable the Rich terminal UI dashboard with a live coverage sparkline and pipeline stage tracker. This is a boolean flag that takes no value — pass it alone to activate. Requires the
rich package (pip install rich). When active, standard log output is suppressed and all events are routed through the TUI instead.Enable debug logging. This is a boolean flag that takes no value — pass it alone to activate. Saves raw LLM completions and Z3 scripts to
/tmp/agentic_afl_debug/ for post-mortem analysis.Examples
Output
When--tui is not active, Agentic-AFL prints a plain-text dashboard to stdout. A new row is emitted roughly every 25 seconds:
Console output (no --tui)
| Column | Snapshot field | Description |
|---|---|---|
Time | elapsed | Wall-clock time since campaign start |
Edges | edges | Unique edges discovered by AFL++ |
Execs | execs | Total executions performed |
Stalls | stalls_detected | Number of edge-growth stalls detected so far |
Inject | payloads_injected | Number of agent-generated payloads injected |
Status | derived | fuzzing, stall×N, or injected×N |
Campaign Summary
At the end of every campaign, a results block is printed to stdout regardless of whether--tui was active:
Campaign summary block
Evidence line is printed only when bypass evidence is available, and Custom mutator is printed only when a mutator was deployed. When --log-dir is set, the same data is serialised to a JSON file in that directory alongside any evidence string and mutator deployment status.
The harness must be compiled with AFL++ instrumentation (
afl-cc). Agentic-AFL does not compile the harness itself — it only manages the AFL++ process lifecycle and the AgentLoop co-process.