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