hphp/doc/fuzzer

   1 The fuzzer is an automating testing tool for exposing holes in the HHVM verifier
   2 by generating random .hhas files from existing well-formed inputs. Specifics of
   3 how the fuzzer works can be found at https://fburl.com/gc516ctu.
   4
   5 Currently the fuzzer supports eight kinds of mutations to HHAS programs:
   6 * Changing instruction immediates
   7 * Duplicating instructions
   8 * Deleting instructions
   9 * Reordering sequences of instructions
  10 * Replacing instructions with other random instructions
  11 * Inserting new instructions
  12 * Generating random metadata
  13 * Adding random exception regions
  14
  15 The Fuzzer is a dependency of hh_single_compile, but can also be compiled
  16 standalone by pointing buck to the TARGETS file in the fuzzer directory.
  17
  18 The OCaml base of the tool can be run by itself with
  19
  20  buck-out/bin/hphp/vm/runtime/verifier/fuzzer/fuzzer/fuzzer.opt
  21
  22 and can be built with
  23
  24  buck build @mode/<MODE> //hphp/runtime/vm/verifier/fuzzer:fuzzer
  25
  26 but this is unlikely to be useful to a user. The Python script is much more
  27 useful for testing purposes.
  28
  29 In either case, both the OCaml base and the Python script are highly
  30 configurable with command-line arguments.
  31
  32 The OCaml base tool requires only an input file, which is passed without an
  33 argument flag. The rest of the options are:
  34 * -out (string): the output directory for the generated mutations. By default
  35     the mutations are printed to stdout, but this is almost never what you want.
  36     If a directory is specified, the mutations are saved as
  37     <dirname>/mutations<N>.hhas, where <N> denotes the number of the mutations.
  38 * -o (string): alias for the above.
  39 * -prob (float, <=1): The probability of a mutation occurring at each phase,
  40     with a default value of 0.1 (10%). The higher this is, the more likely a
  41     mutation is to occur at each step.
  42 * -magnitude (int): The maximum change to an integer value that can occur as
  43     part of a single mutation, with a default value of 1.
  44 * -immediate (int): The number of immediate mutations to be performed, with a
  45     default value of 1.
  46 * -duplicate (int): The number of duplication mutations to be performed, with a
  47     default value of 1.
  48 * -remove (int): The number of removal mutations to be performed, with a default
  49     value of 1.
  50 * -insert (int): The number of insertion mutations to be performed, with a
  51     default value of 1.
  52 * -reorder (int): The number of reorder mutations to be performed, with a
  53     default value of 1.
  54 * -exception (int): The number of exception region mutations to be performed,
  55     with a default value of 1.
  56 * -metadata (int): The number of metadata mutations to be performed, with a
  57     default value of 1.
  58 * -complete (int): A shorthand way of setting all the mutation numbers to a
  59     single value. This defaults to 0, but when it is N, each mutation will be
  60     performed N times.
  61 ----
  62 The Python script can be run with
  63
  64  python3 hphp/runtime/vm/verifier/fuzzer/fuzz.py
  65
  66 The script requires an initial input file (passed with -i) . The rest of the
  67 options are:
  68 * -g (int): The number of generations to run the Fuzzer for, with a default
  69     value of 1. The runtime of the tool increases exponentially with this value.
  70 * -f (int): The failure threshold for generational pruning, with a default
  71     value of 1. All files with more verification errors than this threshold will
  72     be eliminated at the end of each generation. Higher failure thresholds allow
  73     more files to continue to the next generation, increasing the possibility of
  74     discovering a bug but exponentially increasing the runtime of the tool.
  75 * -p (float, <=1): The probability of a mutation occurring at each step, passed
  76     directly to the OCaml code. This defaults to 0.05. Increasing this will
  77     cause the Fuzzer to generate more trivially broken files, decreasing the
  78     probability of finding a bug but also decreasing the runtime of the tool.
  79 * -v: The flag for verbose mode, default off
  80 * -l (string): The path to the logfile. If verbose mode is active, the tool
  81     will log to this file. If verbose mode is on but no logfile is provided,
  82     the information is printed to stdout.
  83 * -t (int): The number of threads to use when running the Fuzzer. The default
  84     is to run with one thread
  85 * -h: Help flag. Prints the usage text for the script.
  86 * -c: The flag for coverage mode. When turned on, the tool will use coverage
  87     data from HHVM to decide which files to prune after each generation. Turning
  88     this on will drastically increase the amount of time each generation will
  89     take, since collecting coverage data requires actually running HHVM rather
  90     than simply running the verifier. However, over a large number of
  91     generations this will actually decrease the runtime of the tool since
  92     an increasing number of files will be pruned each generation.
  93 * --args (string): Used to pass arguments directly to the OCaml Fuzzer.
  94
  95 The output of the Python tool is stored in the mutations directory, which is
  96 created as a subdirectory of the directory where you ran the script. A summary
  97 of the results of the run, including a list of generated files that successfully
  98 verified but crashed HHVM, is found in mutations/results.txt.