Docs/Architecture/Data Flow

Data Flow

Single-execution path, campaign loop, and offline control paths.

End-to-end path of one execution, then campaign-level loops. Aligns with the four-layer stack in Overview and Layers.

Single execution

  1. Select parent — corpus / queue entry (SeedId)
  2. Mutate — hierarchical ops + optional template splice → child TestCase
  3. Enforce sizes — FieldSpec.size constraints
  4. Integrity prepare_for_send — length, checksum, protocol framing
  5. Encryptor (optional) — XOR / ChaCha20 / TLS record / pipelines
  6. Coverage reset (if non-null provider)
  7. Send — TCP or UDP; connection reuse when enabled; desocket if session needs reset
  8. Receive / timeout — build ExecutionResult (codes, bodies, elapsed, crash/hang flags)
  9. Coverage collect → CoverageFeedback
  10. State tracker — update hashes / transitions; set new_state when applicable
  11. Oracle is_interesting
  12. On interesting / crash / hang — minimise, log to output/, boost mutator energy, optionally schedule NXS
seed → mutate → integrity → [encrypt] → send/recv
         ↓                                    ↓
    energy↑ ← interesting ← oracle ← result + coverage + state
         ↓
    [NXS spawn async] → reaper → exit 2 → secondary.jsonl

Campaign loop

  • Engine owns config, providers (coverage, snapshot), worker pool, NXS rate state
  • Workers run the single-execution path concurrently; each holds mutator RNG state
  • Limits — max_execs, max_runtime, or operator SIGINT
  • Snapshot — optional snapshot at start; on crash, restore backend + bump restore_epoch → workers force-reconnect
  • Output layout — crashes/, hangs/, queue/; with NXS: nxs-meta/, nxs-out/, nxs-findings/

Offline / control paths (no full campaign)

PathFlow
--infer-modelRead seeds → heuristics → summary / JSON → exit
--nxs-listResolve set → print found/missing → exit
-L / --libaflDelegate campaign to LibAFL runner (feature required)
-Y RPCUnix socket control plane for Python client

Failure & signal handling

  • Config / init / campaign errors → process exit 1
  • Target crash does not force fuzzer exit 1; artefacts + optional NXS exit 2 carry escalation
  • Unix SIGINT/SIGTERM — graceful campaign stop (platform-gated handlers)
Design invariant

Optional planes (coverage map, snapshot, NXS, encryptor) default off or null. Enabling them is explicit via CLI/config/env — preserving reproducible minimal campaigns.