Initial documentation for the image fuzzer Signed-off-by: Maria Kustova <mari...@catit.be> --- 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