GWP-ASan

    GWP-ASan is based on the classicElectric Fence Malloc Debugger, with akey adaptation. Notably, we only choose a very small percentage of allocationsto sample, and apply guard pages to these sampled allocations only. The samplingis small enough to allow us to have very low performance overhead.

    There is a small, tunable memory overhead that is fixed for the lifetime of theprocess. This is approximately ~40KiB per process using the default settings,depending on the average size of your allocations.

    Unlike ,GWP-ASan does not induce a significant performance overhead. ASan often requiresthe use of dedicated canaries to be viable in production environments, and assuch is often impractical.

    GWP-ASan is only capable of finding a subset of the memory issues detected byASan. Furthermore, GWP-ASan’s bug detection capabilities are only probabilistic.As such, we recommend using ASan over GWP-ASan in testing, as well as anywhereelse that guaranteed error detection is more valuable than the 2x executionslowdown/binary size bloat. For the majority of production environments, thisimpact is too high, and GWP-ASan proves extremely useful.

    Please note: The implementation of GWP-ASan is largely in-flux, and thesedetails are subject to change. There are currently other implementations ofGWP-ASan, such as the implementation featured inChromium. Thelong-term support goal is to ensure feature-parity where reasonable, and tosupport compiler-rt as the reference implementation.

    GWP-ASan is not a replacement for a traditional allocator. Instead, it works byinserting stubs into a supporting allocator to redirect allocations to GWP-ASanwhen they’re chosen to be sampled. These stubs are generally implemented in theimplementation of , free() and realloc(). The stubs areextremely small, which makes using GWP-ASan in most allocators fairly trivial.The stubs follow the same general pattern (example malloc() pseudocodebelow):

    Guarded Allocation Pool

    The core of GWP-ASan is the guarded allocation pool. Each sampled allocation isbacked using its own guarded slot, which may consist of one or more accessiblepages. Each guarded slot is surrounded by two guard pages, which are mapped asinaccessible. The collection of all guarded slots makes up the guardedallocation pool.

    We gain buffer-overflow and buffer-underflow detection through these guardpages. When a memory access overruns the allocated buffer, it will touch theinaccessible guard page, causing memory exception. This exception is caught andhandled by the internal crash handler. Because each allocation is recorded withmetadata about where (and by what thread) it was allocated and deallocated, wecan provide information that will help identify the root cause of the bug.

    Allocations are randomly selected to be either left- or right-aligned to provideequal detection of both underflows and overflows.

    Use after Free Detection

    The guarded allocation pool also provides use-after-free detection. Whenever asampled allocation is deallocated, we map its guarded slot as inaccessible. Anymemory accesses after deallocation will thus trigger the crash handler, and wecan provide useful information about the source of the error.

    Please note that the use-after-free detection for a sampled allocation istransient. To keep memory overhead fixed while still detecting bugs, deallocatedslots are randomly reused to guard future allocations.

    GWP-ASan already ships by default in the,so building with -fsanitize=scudo is the quickest and easiest way to try outGWP-ASan.

    • When the GWP-ASan library is compiled, by setting-DGWP_ASAN_DEFAULT_OPTIONS to the options string you want set by default.If you’re building GWP-ASan as part of a compiler-rt/LLVM build, add it duringcmake configure time (e.g. cmake … -DGWP_ASAN_DEFAULT_OPTIONS="…"). Ifyou’re building GWP-ASan outside of compiler-rt, simply ensure that youspecify when buildingoptional/options_parser.cpp).
    • By defining a gwp_asan_default_options function in one’s program thatreturns the options string to be parsed. Said function must have the followingprototype: extern "C" const char* gwp_asan_default_options(void), with adefault visibility. This will override the compile time define;
    • Depending on allocator support (Scudo has support for this mechanism): Throughthe environment variable GWP_ASAN_OPTIONS, containing the options stringto be parsed. Options defined this way will override any definition madethrough __gwp_asan_default_options.

    The options string follows a syntax similar to ASan, where distinct optionscan be assigned in the same string, separated by colons.

    For example, using the environment variable:

    1. GWP_ASAN_OPTIONS="MaxSimultaneousAllocations=16:SampleRate=5000" ./a.out

    Or using the function:

    The following options are available:

    Example

    The below code has a use-after-free bug, where the string_view is created asa reference to the temporary result of the operator. Theuse-after-free occurs when sv is dereferenced on line 8.

    1. 2: #include <string>
    2. 3: #include <string_view>
    3. 4:
    4. 5: int main() {
    5. 6:   std::string s = "Hellooooooooooooooo ";
    6. 7:   std::string_view sv = s + "World\n";
    7. 8:   std::cout << sv;
    8. 9: }

    Compiling this code with Scudo+GWP-ASan will probabilistically catch this bugand provide us a detailed error report:

    1. $ cat my_gwp_asan_error.txt | symbolize.sh
    2. |
    3. | *** GWP-ASan detected a memory error ***
    4. | Use after free at 0x7feccab26000 (0 bytes into a 41-byte allocation at 0x7feccab26000) by thread 31027 here:
    5. | ...
    6. | #9 /usr/lib/gcc/x86_64-linux-gnu/8.0.1/../../../../include/c++/8.0.1/string_view:547
    7. |
    8. | 0x7feccab26000 was deallocated by thread 31027 here:
    9. | ...
    10. | #7 /tmp/buggy_code.cpp:8
    11. | #8 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
    12. | #9 ./a.out(_start+0x2a) [0x55585c0867ba]
    13. |
    14. | 0x7feccab26000 was allocated by thread 31027 here:
    15. | ...
    16. | #12 /tmp/buggy_code.cpp:7
    17. | #13 /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xeb) [0x7fecc966952b]
    18. | #14 ./a.out(_start+0x2a) [0x55585c0867ba]
    19. |
    20. | *** End GWP-ASan report ***