docs/gwp_asan.md

   1 # GWP-ASan
   2
   3 GWP-ASan is a debug tool intended to detect heap memory errors in the wild. It
   4 samples allocations to a debug allocator, similar to ElectricFence or Page Heap,
   5 causing memory errors to crash and report additional debugging context about
   6 the error.
   7
   8 It is also known by its recursive backronym, GWP-ASan Will Provide Allocation
   9 Sanity.
  10
  11 To read a more in-depth explanation of GWP-ASan see [this post](https://sites.google.com/a/chromium.org/dev/Home/chromium-security/articles/gwp-asan).
  12
  13 ## Allocator
  14
  15 The GuardedPageAllocator returns allocations on pages buffered on both sides by
  16 guard pages. The allocations are either left- or right-aligned to detect buffer
  17 overflows and underflows. When an allocation is freed, the page is marked
  18 inaccessible so use-after-frees cause an exception (until that page is reused
  19 for another allocation.)
  20
  21 The allocator saves stack traces on every allocation and deallocation to
  22 preserve debug context if that allocation results in a memory error.
  23
  24 The allocator implements a quarantine mechanism by allocating virtual memory for
  25 more allocations than the total number of physical pages it can return at any
  26 given time. The difference forms a rudimentary quarantine.
  27
  28 Because pages are re-used for allocations, it's possible that a long-lived
  29 use-after-free will cause a crash long after the original allocation has been
  30 replaced. In order to decrease the likelihood of incorrect stack traces being
  31 reported, we allocate a lot of virtual memory but don't store metadata for every
  32 allocation. That way though we may not be able to report the metadata for an old
  33 allocation, we will not report incorrect stack traces.
  34
  35 ## Crash handler
  36
  37 The allocator is designed so that memory errors with GWP-ASan allocations
  38 intentionally trigger invalid access exceptions. A hook in the crashpad crash
  39 handler process inspects crashes, determines if they are GWP-ASan exceptions,
  40 and adds additional debug information to the crash minidump if so.
  41
  42 The crash handler hook determines if the exception was related to GWP-ASan by
  43 reading the allocator internals and seeing if the exception address was within
  44 the bounds of the allocator region. If it is, the crash handler hook extracts
  45 debug information about that allocation, such as thread IDs and stack traces
  46 for allocation (and deallocation, if relevant) and writes it to the crash dump.
  47
  48 The crash handler runs with elevated privileges so parsing information from a
  49 lesser-privileged process is security sensitive. The GWP-ASan hook is specially
  50 structured to minimize the amount of allocator logic it relies on and to
  51 validate the allocator internals before reasoning about them.
  52
  53 ## Status
  54
  55 GWP-ASan is implemented for malloc and PartitionAlloc. It is enabled by default
  56 on Windows and macOS. The allocator parameters can be manually modified by using
  57 an invocation like the following:
  58
  59 ```shell
  60 chrome --enable-features="GwpAsanMalloc<Study" \
  61        --force-fieldtrials=Study/Group1 \
  62        --force-fieldtrial-params=Study.Group1:MaxAllocations/128/MaxMetadata/255/TotalPages/4096/AllocationSamplingFrequency/1000/ProcessSamplingProbability/1.0
  63 ```
  64
  65 GWP-ASan is tuned more aggressively in canary/dev, to increase the likelihood we
  66 catch newly introduced bugs, and for specific processes depending on the
  67 particular allocator.
  68
  69 A [hotlist of bugs discovered by by GWP-ASan](https://bugs.chromium.org/p/chromium/issues/list?can=1&q=Hotlist%3DGWP-ASan)
  70 exists, though GWP-ASan crashes are filed Bug-Security, e.g. without external
  71 visibility, by default.
  72
  73 ## Limitations
  74
  75 - GWP-ASan is configured with a small fixed-size amount of memory, so
  76   long-lived allocations can quickly deplete the page pool and lead the
  77   allocator to run out of memory. Depending on the sampling frequency and
  78   distribution of allocation lifetimes this may lead to only allocations early
  79   in the process lifetime being sampled.
  80 - Allocations over a page in size are not sampled.
  81 - The allocator skips zero-size allocations. Zero-size allocations on some
  82   platforms return valid pointers and may be subject to lifetime and bounds
  83   issues.
  84 - GWP-ASan does not intercept allocations for Oilpan or the v8 GC.
  85 - GWP-ASan does not hook PDFium's fork of PartitionAlloc.
  86 - Right-aligned allocations to catch overflows are not perfectly right-aligned,
  87   so small out-of-bounds accesses may be missed.
  88 - GWP-ASan does not sample some early allocations that occur before field trial
  89   initialization.
  90 - Depending on the platform, GWP-ASan may or may not hook malloc allocations
  91   that occur in code not linked directly against Chrome.
  92
  93 ## Testing
  94
  95 There is [not yet](https://crbug.com/910751) a way to intentionally trigger a
  96 GWP-ASan exception.
  97
  98 There is [not yet](https://crbug.com/910749) a way to inspect GWP-ASan data in
  99 a minidump (crash report) without access to Google's crash service.