1Fuzzing Example
2###############
3
4Overview
5********
6
7This is a simple example of fuzz test integration with Zephyr apps
8that displays LLVM libfuzzer's most important feature: it's ability to
9detect and explore deep and complicated call trees by exploiting
10coverage information gleaned from instrumented binaries.
11
12Building and Running
13********************
14
15Right now, the only toolchain that works with libfuzzer is a recent 64
16bit clang (clang 14 was used at development time).  Make sure such a
17toolchain is installed in your host environment, and build with:
18
19.. code-block:: console
20
21   $ clang --version
22   clang version 14.0.6
23   Target: x86_64-pc-linux-gnu
24   Thread model: posix
25   InstalledDir: /usr/bin
26   $ export ZEPHYR_TOOLCHAIN_VARIANT=llvm
27   $ west build -t run -b native_sim/native/64 samples/subsys/debug/fuzz
28
29Over 10-20 seconds or so (runtimes can be quite variable) you will see
30it discover and recurse deeper into the test's deliberately
31constructed call tree, eventually crashing when it reaches the final
32state and reporting the failure.
33
34Example output:
35
36.. code-block:: console
37
38   -- west build: running target run
39   [0/1] cd /home/andy/z/zephyr/build && .../andy/z/zephyr/build/zephyr/zephyr.exe
40   INFO: Running with entropic power schedule (0xFF, 100).
41   INFO: Seed: 108038547
42   INFO: Loaded 1 modules   (2112 inline 8-bit counters): 2112 [0x55cbe336ec55, 0x55cbe336f495),
43   INFO: Loaded 1 PC tables (2112 PCs): 2112 [0x55cbe336f498,0x55cbe3377898),
44   INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes
45   *** Booting Zephyr OS build zephyr-v3.1.0-3976-g806034e02865  ***
46   Hello World! native_sim/native/64
47   INFO: A corpus is not provided, starting from an empty corpus
48   #2	INITED cov: 101 ft: 102 corp: 1/1b exec/s: 0 rss: 30Mb
49   #
50   # Found key 0
51   #
52   NEW_FUNC[1/6]: 0x55cbe3339c45 in check1 /home/andy/z/zephyr/samples/subsys/debug/fuzz/src/main.c:43
53   NEW_FUNC[2/6]: 0x55cbe333c8d8 in char_out /home/andy/z/zephyr/lib/os/printk.c:108
54   ...
55   ...
56   ...
57   #418965	REDUCE cov: 165 ft: 166 corp: 15/400b lim: 4052 exec/s: 38087 rss: 31Mb L: 5/256 MS: 1 EraseBytes-
58   #524288	pulse  cov: 165 ft: 166 corp: 15/400b lim: 4096 exec/s: 40329 rss: 31Mb
59   #
60   # Found key 5
61   #
62   NEW_FUNC[1/1]: 0x55cbe3339ff7 in check6 /home/andy/z/zephyr/samples/subsys/debug/fuzz/src/main.c:48
63   #579131	NEW    cov: 168 ft: 169 corp: 16/406b lim: 4096 exec/s: 38608 rss: 31Mb L: 6/256 MS: 1 InsertByte-
64   #579432	NEW    cov: 170 ft: 171 corp: 17/414b lim: 4096 exec/s: 38628 rss: 31Mb L: 8/256 MS: 1 PersAutoDict- DE: "\000\000"-
65   #579948	REDUCE cov: 170 ft: 171 corp: 17/413b lim: 4096 exec/s: 38663 rss: 31Mb L: 7/256 MS: 1 EraseBytes-
66   #
67   # Found key 6
68   #
69   UndefinedBehaviorSanitizer:DEADLYSIGNAL
70   ==3243305==ERROR: UndefinedBehaviorSanitizer: SEGV on unknown address 0x000000000000 (pc 0x55cbe333a09d bp 0x7f3114afadf0 sp 0x7f3114afade0 T3243308)
71   ==3243305==The signal is caused by a WRITE memory access.
72   ==3243305==Hint: address points to the zero page.
73       #0 0x55cbe333a09d in check6 /home/andy/z/zephyr/samples/subsys/debug/fuzz/src/main.c:48:1
74