1## Command heap-analysis-helper ##
2
3Please note: This feature is still under development, expect bugs and unstability.
4
5`heap-analysis-helper` command aims to help the process of idenfitying Glibc
6heap inconsistencies by tracking and analyzing allocations and deallocations of
7chunks of memory.
8
9Currently, the following issues can be tracked:
10
11   * NULL free
12   * Use-after-Free
13   * Double Free
14   * Heap overlap
15
16The helper can simply be activated by running the command `heap-analysis-helper`.
17
18```
19gef➤ heap-analysis
20[+] Tracking malloc()
21[+] Tracking free()
22[+] Disabling hardware watchpoints (this may increase the latency)
23[+] Dynamic breakpoints correctly setup, GEF will break execution if a possible vulnerabity is found.
24[+] To disable, clear the malloc/free breakpoints (`delete breakpoints`) and restore hardware breakpoints (`set can-use-hw-watchpoints 1`)
25```
26
27The helper will create specifically crafted breakoints to keep tracks of
28allocation, which allows to discover *potential* vulnerabilities. Once
29activated, one can disable the heap analysis breakpoints simply by clearing the
30`__GI___libc_free()` et `__GI___libc_malloc()`. It is also possible to
31enable/disable manually punctual checks via the `gef config` command.
32
33The following settings are accepted:
34
35   * `check_null_free`: to break execution when a free(NULL) is encountered
36     (disabled by default);
37   * `check_double_free`: to break execution when a double free is encountered;
38
39![double-free](https://i.imgur.com/S7b4FJa.png)
40
41   * `check_weird_free`: to execution when `free()` is called against a
42     non-tracked pointer;
43   * `check_uaf`: to break execution when a possible Use-after-Free condition is
44     found.
45
46![uaf](https://i.imgur.com/NfV5Cu9.png)
47
48Just like the format string vulnerability helper, the `heap-analysis-helper`
49can fail to detect complex heap scenarios and/or provide some false positive
50alerts. Each finding must of course be ascertained manually.
51
52The `heap-analysis-helper` can also be used to simply track allocation and
53liberation of chunks of memory. One can simply enable the tracking by setting
54all the configurations stated above to False:
55
56```
57gef➤  gef config heap-analysis-helper.check_double_free False
58gef➤  gef config heap-analysis-helper.check_free_null False
59gef➤  gef config heap-analysis-helper.check_weird_free False
60gef➤  gef config heap-analysis-helper.check_uaf False
61```
62
63Then `gef` will not notify you of any inconsistency detected, but simply display
64a clear message when a chunk is allocated/freed.
65
66![heap-track](https://i.imgur.com/68NGTvw.png)
67
68To get information regarding the currently tracked chunks, use the `show`
69subcommand:
70
71```
72gef➤  heap-analysis-helper show
73```
74
75![heap-analysis-helper-show](http://i.imgur.com/0I4jBWJ.png)
76