Lines Matching +full:docs +full:- +full:clang +full:- +full:tools +full:- +full:man
2 GWP-ASan
12 GWP-ASan is a sampled allocator framework that assists in finding use-after-free
13 and heap-buffer-overflow bugs in production environments. It informally is a
14 recursive acronym, "**G**\WP-ASan **W**\ill **P**\rovide **A**\llocation
17 GWP-ASan is based on the classic
18 `Electric Fence Malloc Debugger <https://linux.die.net/man/3/efence>`_, with a
27 GWP-ASan vs. ASan
30 Unlike `AddressSanitizer <https://clang.llvm.org/docs/AddressSanitizer.html>`_,
31 GWP-ASan does not induce a significant performance overhead. ASan often requires
37 However, GWP-ASan is only capable of finding a subset of the memory issues
38 detected by ASan. Furthermore, GWP-ASan's bug detection capabilities are
39 only probabilistic. As such, we recommend using ASan over GWP-ASan in testing,
42 environments, this impact is too high and security is indispensable, so GWP-ASan
49 **Please note:** The implementation of GWP-ASan is largely in-flux, and these
51 GWP-ASan, such as the implementation featured in
53 long-term support goal is to ensure feature-parity where reasonable, and to
54 support compiler-rt as the reference implementation.
57 -----------------
59 GWP-ASan is not a replacement for a traditional allocator. Instead, it works by
60 inserting stubs into a supporting allocator to redirect allocations to GWP-ASan
63 extremely small, which makes using GWP-ASan in most allocators fairly trivial.
83 ``-DINSTALL_GWP_ASAN_STUBS`` and link against the GWP-ASan library! For
84 performance reasons, we strongly recommend static linkage of the GWP-ASan
88 -----------------------
90 The core of GWP-ASan is the guarded allocation pool. Each sampled allocation is
97 -----------------------------------
99 We gain buffer-overflow and buffer-underflow detection through these guard
106 Allocations are randomly selected to be either left- or right-aligned to provide
110 ------------------------
112 The guarded allocation pool also provides use-after-free detection. Whenever a
117 Please note that the use-after-free detection for a sampled allocation is
124 GWP-ASan already ships by default in the
125 `Scudo Hardened Allocator <https://llvm.org/docs/ScudoHardenedAllocator.html>`_,
126 so building with ``-fsanitize=scudo`` is the quickest and easiest way to try out
127 GWP-ASan.
130 -------
132 GWP-ASan's configuration is managed by the supporting allocator. We provide a
134 several aspects of GWP-ASan to be configured through the following methods:
136 - When the GWP-ASan library is compiled, by setting
137 ``-DGWP_ASAN_DEFAULT_OPTIONS`` to the options string you want set by default.
138 If you're building GWP-ASan as part of a compiler-rt/LLVM build, add it during
139 cmake configure time (e.g. ``cmake ... -DGWP_ASAN_DEFAULT_OPTIONS="..."``). If
140 you're building GWP-ASan outside of compiler-rt, simply ensure that you
141 specify ``-DGWP_ASAN_DEFAULT_OPTIONS="..."`` when building
144 - By defining a ``__gwp_asan_default_options`` function in one's program that
149 - Depending on allocator support (Scudo has support for this mechanism): Through
174 +----------------------------+---------+--------------------------------------------------------------------------------+
176 +----------------------------+---------+--------------------------------------------------------------------------------+
177 | Enabled | true | Is GWP-ASan enabled? |
178 +----------------------------+---------+--------------------------------------------------------------------------------+
179 | PerfectlyRightAlign | false | When allocations are right-aligned, should we perfectly align them up to the |
181 | | | power of two (2, 4, 8, 16) up to a maximum of 16-byte alignment for |
183 | | | buffer-overflows at the cost of performance, and may be incompatible with |
185 +----------------------------+---------+--------------------------------------------------------------------------------+
186 | MaxSimultaneousAllocations | 16 | Number of simultaneously-guarded allocations available in the pool. |
187 +----------------------------+---------+--------------------------------------------------------------------------------+
188 | SampleRate | 5000 | The probability (1 / SampleRate) that a page is selected for GWP-ASan |
189 | | | sampling. Sample rates up to (2^31 - 1) are supported. |
190 +----------------------------+---------+--------------------------------------------------------------------------------+
191 | InstallSignalHandlers | true | Install GWP-ASan signal handlers for SIGSEGV during dynamic loading. This |
193 | | | deallocation when reporting a memory error. GWP-ASan's signal handler will |
194 | | | forward the signal to any previously-installed handler, and user programs |
198 +----------------------------+---------+--------------------------------------------------------------------------------+
201 -------
203 The below code has a use-after-free bug, where the ``string_view`` is created as
205 use-after-free occurs when ``sv`` is dereferenced on line 8.
219 Compiling this code with Scudo+GWP-ASan will probabilistically catch this bug
224 $ clang++ -fsanitize=scudo -g buggy_code.cpp
229 | *** GWP-ASan detected a memory error ***
230 | Use after free at 0x7feccab26000 (0 bytes into a 41-byte allocation at 0x7feccab26000) by thread 31027 here:
234 | #11 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
240 | #8 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
246 | #13 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
249 | *** End GWP-ASan report ***
254 provides human-readable stack traces in ``function+offset`` form, rather than
255 the normal ``binary+offset`` form. In order to use addr2line or similar tools to
258 ``compiler-rt/lib/gwp_asan/scripts/symbolize.sh``. Using this script will
267 | *** GWP-ASan detected a memory error ***
268 | Use after free at 0x7feccab26000 (0 bytes into a 41-byte allocation at 0x7feccab26000) by thread 31027 here:
270 | #9 /usr/lib/gcc/x86_64-linux-gnu/8.0.1/../../../../include/c++/8.0.1/string_view:547
276 | #8 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
282 | #13 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
285 | *** End GWP-ASan report ***