Skip to content
dfluxdocs
dflux.io

Fuzzing

rk can mutate the messages a flow sends, to find inputs that crash or confuse the network function under test. Fuzzing needs the licence feature robustness.fuzz.

Two pieces are involved:

  • A fuzz: block in a flow turns mutation on. No command-line flag does.
  • rk fuzz runs fuzz campaigns across several targets, each judged by an oracle.

The fuzz: block

YAML

rk schema lists every key the block accepts.

  • Scope: the block can sit on the flow, on a state, or on a single send. The most specific one wins.
  • Strategies: bitflip (the default), truncate, extend, field, ie-drop, ie-dup, ie-reorder, nest, unknown-ie, downgrade.
  • Seed on the command line: -fuzz-seed <n> replaces the template's seed. auto or random picks a new one each run.

Every mutated run writes its artifacts to -fuzz-out. When that's not set, it uses $D3X_FUZZ_OUT, then ./fuzz-runs. Each run gets a directory named after the time and the flow:

FileWhat it holds
campaign.jsonthe seed and where it came from, every mutation, and a digest to reproduce the run
repro.txthow to reproduce the run
mutations/each mutated message, as hex before and after
oracle.jsonthe oracle's verdict
corpus/wire mutations in Go's fuzz-corpus format

Oracles: did the target break?

Two ways to judge a fuzzed run, on run-flow or in the manifest:

  • Panic counter: -fuzz-metrics-url <url> reads the target's d3x_recovered_panics_total before and after the run. Any increase fails the run.
  • Known-good replay: -fuzz-known-good <flow> replays a normal flow after the campaign (and every -fuzz-known-good-every seconds, if set). If it no longer passes, the target's state was corrupted, and the run fails.

rk fuzz: campaigns

Shell
FlagDefaultWhat it does
-targetrequired: a name, a list, all, or nf=<role>, protocol=<p>, schedule_class=<c>
-manifestfuzz/targets.yamlthe target list, searched in the current directory and up to 8 levels above
-budget2mthe total wall time, divided equally across targets
-templates, -c, -stemplates, environment (single target only) and subscribers
-fuzz-seed, -fuzz-out, -fuzz-metrics-url, -fuzz-known-goodas on run-flow
-output-filestdoutthe JSON report

Each manifest target names:

  • its base_flow (which must have a fuzz: block);
  • nf, protocol, strategies and its oracle;
  • a schedule_class: parallel, serial-per-upf or lab-exclusive.

Targets that need a lab aren't run by rk fuzz; they're reported as inconclusive.

Each target's status:

  • fail: the oracle judged the target unclean;
  • error: the campaign errored;
  • inconclusive: no mutation was applied, or no oracle ran;
  • pass: none of these.

The exit code:

  • 1 if any target failed;
  • otherwise the first errored target's code;
  • otherwise 3 if nothing passed;
  • otherwise 0.

The report is always JSON.