[Qemu-devel] [RFC] image-fuzzer: Documentation for the image fuzzer

[Maria Kustova]

Initial documentation for the image fuzzer

Signed-off-by: Maria Kustova <address@hidden>
---
 tests/image-fuzzer/docs/image-fuzzer.txt | 126 +++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 tests/image-fuzzer/docs/image-fuzzer.txt

diff --git a/tests/image-fuzzer/docs/image-fuzzer.txt 
b/tests/image-fuzzer/docs/image-fuzzer.txt
new file mode 100644
index 0000000..a34df8c
--- /dev/null
+++ b/tests/image-fuzzer/docs/image-fuzzer.txt
@@ -0,0 +1,126 @@
+Image fuzzer
+============
+
+Description
+-----------
+
+The goal of the image fuzzer is to catch crashes of qemu-io/qemu-img providing
+to them randomly corrupted images.
+Test images are generated from scratch and have valid inner structure with some
+elements, e.g. L1/L2 tables, having random invalid values.
+
+
+Test runner
+-----------
+
+The test runner generates a test image, executes one test, indicates its result
+and collect all test related artefacts (logs, core dumps, test image). The test
+means one start of a test binary, e.g. qemu-io, with specified arguments and
+one test image.
+Path to a test binary can be specified via environment variables (for now only
+qemu-img). For details see qemu-iotests/check.
+
+
+Module interfaces
+-----------------
+
+* Test runner/image generator
+
+The runner calls an image generator specifying path to a test image file, its
+size and seed. An image generator is expected to create a test image of the
+specified size using the specified seed for random generator and write an image
+to file. File should be created if it doesn't exist or overwritten otherwise.
+Size and seed arguments are optional.
+
+An image generator should return seeds for the logging purpose.
+
+
+Overall fuzzer requirements
+===========================
+
+Input data
+----------
+
+ - image structure template
+ - test run duration (optional)
+ - action vector (optional)
+ - seed (optional)
+ - fuzzing type (optional)
+ - qemu-img arguments (optional)
+
+
+Fuzzer requirements
+-------------------
+
+1.  Should be able to inject random data
+2.  Should be able to permutate part of specified data
+3.  Should be able to select a random value from the manually pregenerated
+    vector (boundary values, e.g. max/min cluster size)
+4.  Image template should describe a general structure invariant for all
+    test images (image format description)
+5.  Image template should be autonomous and other fuzzer parts should not
+    relate on it
+6.  Image template should contain reference rules (not only block+size
+    description)
+7.  Should generate the test image with the correct structure based on an image
+    template
+8.  Should accept a seed as an argument (for regression purpose)
+9.  Should generate a seed if it is not specified as an input parameter.
+10. The same seed should generate the same image, if no or the same action
+    vector and fuzzing type are specified
+11. Should accept a vector of actions as an argument (for test reproducing and
+    for test case specification, e.g. group of tests for header structure,
+    group of test for snapshots, etc)
+12. Action vector should be randomly generated from the pool of available
+    actions, if it is not specified as an input parameter
+13. Pool of actions should be defined automatically based on an image template
+14. Should accept a fuzzing type: random values or pregenerated ones
+    (if possible).
+15. Should accept qemu-img call parameters as an argument and select them
+    randomly otherwise. As far as it's expected to be rarely changed, the list
+    of possible values will be available in the test runner internally.
+16. Should accept a test run duration as an argument. Tests should be executed
+    during a minimum period from a test run duration and time while fuzzer can
+    generate different test images
+17. Should support an external cancellation of a test run
+18. Seed, action vector and fuzzing type should be logged (for regression
+    purpose)
+19. All files related to test result should be collected: a test image,
+    qemu logs, fuzzer logs and crash dumps
+20. Should be compatible with python version 2.4-2.7
+21. Usage of external libraries should be limited as much as possible.
+
+
+Image formats
+-------------
+
+Main target image format is qcow2, but support of image templates should
+provide an ability to add any other image format.
+
+
+Effectiveness
+-------------
+
+Fuzzer can be controlled via template, seed and action vector;
+this make the fuzzer itself invariant to an image format and test logic.
+It should be able to perform rather complex and precise tests, that can be
+specified via action vector. Otherwise, knowledge about an image structure
+allows the fuzzer to generate the pool of all available areas can be fuzzed
+and randomly select some of them and so compose its own action vector.
+Also complexity of a template defines complexity of the fuzzer, so its
+functionality can be varied from simple model-independent fuzzing to smart
+model-based one.
+
+
+Glossary
+--------
+
+Action vector is a sequence of structure elements retrieved from an image
+format, each of which will be fuzzed for the test image. It's a subset of
+elements of the action pool. Example: header, refcount block, etc.
+Action pool is all available elements of an image structure that generated
+automatically from an image template.
+Image template is a formal description of an image structure and relations
+between image blocks
+Test image is an output image of fuzzer defined by the current seed, fuzz type
+and action vector.
-- 
1.8.2.1