| Message ID | 20200921022506.873303-17-alxndr@bu.edu |
|---|---|
| State | New |
| Headers | show |
| Series | Add a General Virtual Device Fuzzer | expand |
On Sunday, 2020-09-20 at 22:25:06 -04, Alexander Bulekov wrote: > Signed-off-by: Alexander Bulekov <alxndr@bu.edu> > --- > docs/devel/fuzzing.txt | 38 ++++++++++++++++++++++++++++++++++++++ > 1 file changed, 38 insertions(+) > > diff --git a/docs/devel/fuzzing.txt b/docs/devel/fuzzing.txt > index 96d71c94d7..208b0c8360 100644 > --- a/docs/devel/fuzzing.txt > +++ b/docs/devel/fuzzing.txt > @@ -125,6 +125,44 @@ provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly the > fuzzer loops over the byte-array interpreting it as a list of qtest commands, > addresses, or values. > > +== The General Fuzzer == > +Writing a fuzz target can be a lot of effort (especially if a device driver has > +not be built-out within libqos). Many devices can be fuzzed to some degree, > +without any device-specific code, using the general-fuzz target. > + > +The general-fuzz target is capable of fuzzing devices over their PIO, MMIO, > +and DMA input-spaces. To apply the general-fuzz to a device, we need to define > +two env-variables, at minimum: > + > +QEMU_FUZZ_ARGS= is the set of QEMU arguments used to configure a machine, with > +the device attached. For example, if we want to fuzz the virtio-net device > +attached to a pc-i440fx machine, we can specify: > +QEMU_FUZZ_ARGS="-M pc -nodefaults -netdev user,id=user0 \ > + -device virtio-net,netdev=user0" > + > +QEMU_FUZZ_OBJECTS= is a set of space-delimited strings used to identify the > +MemoryRegions that will be fuzzed. These strings are compared against > +MemoryRegion names and MemoryRegion owner names, to decide whether each > +MemoryRegion should be fuzzed. These strings support globbing. For the > +virtio-net example, we could use > +QEMU_FUZZ_OBJECTS='virtio-net' > +QEMU_FUZZ_OBJECTS='virtio*' > +QEMU_FUZZ_OBJECTS='virtio* pcspk' # Fuzz the virtio-net device and the PC speaker... > +QEMU_FUZZ_OBJECTS='*' # Fuzz the whole machine > + Maybe format these as lists, where each list item is the variable? > +The "info mtree" and "info qom-tree" monitor commands can be especially useful > +for identifying the MemoryRegion and Object names used for matching. > + > +As a general rule-of-thumb, the more MemoryRegions/Devices we match, the greater > +the input-space, and the smaller the probability of finding crashing inputs for > +individual devices. As such, it is usually a good idea to limit the fuzzer to > +only a few MemoryRegions. > + > +To ensure that these env variables have been configured correctly, we can use: Add a blank line here? > +./qemu-fuzz-i386 --fuzz-target=general-fuzz -runs=0 > + > +The output should contain a complete list of matched MemoryRegions. > + > = Implementation Details = > > == The Fuzzer's Lifecycle == Not this patch, but this text file is partially written in Restructured Text format, but not completely. Should it be converted to RsT format properly - doesn't have to be now, but something we could consider. Otherwise, it looks find to me, so: Reviewed-by: Darren Kenny <darren.kenny@oracle.com> Thanks, Darren.
diff --git a/docs/devel/fuzzing.txt b/docs/devel/fuzzing.txt index 96d71c94d7..208b0c8360 100644 --- a/docs/devel/fuzzing.txt +++ b/docs/devel/fuzzing.txt @@ -125,6 +125,44 @@ provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly the fuzzer loops over the byte-array interpreting it as a list of qtest commands, addresses, or values. +== The General Fuzzer == +Writing a fuzz target can be a lot of effort (especially if a device driver has +not be built-out within libqos). Many devices can be fuzzed to some degree, +without any device-specific code, using the general-fuzz target. + +The general-fuzz target is capable of fuzzing devices over their PIO, MMIO, +and DMA input-spaces. To apply the general-fuzz to a device, we need to define +two env-variables, at minimum: + +QEMU_FUZZ_ARGS= is the set of QEMU arguments used to configure a machine, with +the device attached. For example, if we want to fuzz the virtio-net device +attached to a pc-i440fx machine, we can specify: +QEMU_FUZZ_ARGS="-M pc -nodefaults -netdev user,id=user0 \ + -device virtio-net,netdev=user0" + +QEMU_FUZZ_OBJECTS= is a set of space-delimited strings used to identify the +MemoryRegions that will be fuzzed. These strings are compared against +MemoryRegion names and MemoryRegion owner names, to decide whether each +MemoryRegion should be fuzzed. These strings support globbing. For the +virtio-net example, we could use +QEMU_FUZZ_OBJECTS='virtio-net' +QEMU_FUZZ_OBJECTS='virtio*' +QEMU_FUZZ_OBJECTS='virtio* pcspk' # Fuzz the virtio-net device and the PC speaker... +QEMU_FUZZ_OBJECTS='*' # Fuzz the whole machine + +The "info mtree" and "info qom-tree" monitor commands can be especially useful +for identifying the MemoryRegion and Object names used for matching. + +As a general rule-of-thumb, the more MemoryRegions/Devices we match, the greater +the input-space, and the smaller the probability of finding crashing inputs for +individual devices. As such, it is usually a good idea to limit the fuzzer to +only a few MemoryRegions. + +To ensure that these env variables have been configured correctly, we can use: +./qemu-fuzz-i386 --fuzz-target=general-fuzz -runs=0 + +The output should contain a complete list of matched MemoryRegions. + = Implementation Details = == The Fuzzer's Lifecycle ==
Signed-off-by: Alexander Bulekov <alxndr@bu.edu> --- docs/devel/fuzzing.txt | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+)