1# Fuzzing terminal emulators #
2
3## Step 1: Prepare libclose.so and terminal-test ##
4
5```
6$ cd /home/jagger/src/honggfuzz/examples/terminal-emulators/
7$ make
8../../hfuzz_cc/hfuzz-clang -std=c99  -o terminal-test terminal-test.c
9cc -std=c99  -shared -o libclose.so libclose.c
10```
11
12*libclose.so* serves one purpose only: when preloaded (with _LD_PRELOAD=libclose.so_)
13it will prevent file-descriptors *1022* and *1023* (used by honggfuzz for coverage
14feedback accumulation) will not be closed by the fuzzed binary (terminal emulator)
15before passing to the _terminal-test_ binary.
16
17The *terminal-test* program will feed the terminal emulator with data from the
18fuzzing engine, and will try to read back any data that the terminal can produce.
19See the _Bonus: term.log_ secion on why it might matter.
20
21## Step 2: Instrument your terminal emulator ##
22
23Add compiler-time instrumentation to your fuzzed terminal emulator. Typically it
24would consist of the following sequence of commands (for xterm):
25
26```
27$ cd xterm-327
28$ CC=/home/jagger/src/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$CC ./configure
29...
30...
31$ CC=/home/jagger/src/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$CC make -j4
32```
33
34Alternatively, you might want to compile it with ASAN enabled, for better
35detection of memory corruption problems
36
37```
38$ cd xterm-327
39$ HFUZZ_CC_ASAN=1 CC=/home/jagger/src/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$CC ./configure
40...
41...
42$ HFUZZ_CC_ASAN=1 CC=/home/jagger/src/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$CC make -j4
43```
44
45## Step 3: Create initial input corpus ##
46
47It can consist even of a single file.
48
49```
50$ mkdir IN
51$ echo A >IN/1
52```
53
54## Step 4: Launch it! ##
55
56```
57$ /home/jagger/src/honggfuzz/honggfuzz -z -P -f IN/ -E LD_PRELOAD=/home/jagger/src/honggfuzz/examples/terminal-emulators/libclose.so -- xterm-327/xterm -e /home/jagger/src/honggfuzz/examples/terminal-emulators/terminal-test
58```
59
60Typical output:
61```
62----------------------------[ honggfuzz v1.0alpha ]---------------------------
63  Iterations : 4,865,546 [4.87M]
64       Phase : Dynamic Main (2/2)
65    Run Time : 0 hrs 0 min 15 sec
66   Input Dir : [865] 'IN/'
67  Fuzzed Cmd : './xterm -e /home/jagger/src/honggfuzz/examples/terminal-em...'
68     Threads : 4, CPUs: 8, CPU: 733% (91%/CPU)
69       Speed : 320,951/sec (avg: 324,369)
70     Crashes : 0 (unique: 0, blacklist: 0, verified: 0)
71    Timeouts : 0 [10 sec.]
72 Corpus Size : 265, max file size: 1,024
73    Coverage : bb: 850 cmp: 35,516
74-----------------------------------[ LOGS ]-----------------------------------
75NEW, size:912 (i,b,sw,hw,cmp): 0/0/1/0/1, Tot:0/0/772/0/32216
76NEW, size:940 (i,b,sw,hw,cmp): 0/0/1/0/32, Tot:0/0/773/0/32248
77NEW, size:919 (i,b,sw,hw,cmp): 0/0/0/0/9, Tot:0/0/773/0/32257
78NEW, size:1024 (i,b,sw,hw,cmp): 0/0/0/0/2, Tot:0/0/773/0/32259
79NEW, size:1013 (i,b,sw,hw,cmp): 0/0/0/0/1, Tot:0/0/773/0/32260
80...
81...
82```
83
84## Bonus: term.log ##
85
86The *term.log* file will contain interesting data which can be fetched from the
87terminal emulator's input buffer. It will typically contains responses to ESC
88sequences requesting info about terminal size, or about the current color map.
89But, if you notice there arbitrary or binary data, basically something that
90a typical terminal shouldn't responsd with, try to investigate it. You might
91have just found and interesting case of RCE, where arbitrary data can
92be pushed into terminal's input buffer, and then read back (and potentially
93executed) with whatever runs under said emulator (e.g. _/bin/bash_)
94