tools/sanitizer/docs/asan_nightly.rst

   1 ASan Nightly
   2 ============
   3
   4 The **ASan Nightly Project** involves building a Firefox Nightly browser
   5 with the popular
   6 `AddressSanitizer <https://github.com/google/sanitizers/wiki/AddressSanitizer>`__
   7 tool and enhancing it with remote crash reporting capabilities for any
   8 errors detected.
   9
  10 The purpose of the project is to find subtle memory corruptions
  11 occurring during regular browsing that would either not crash at all or
  12 crash in a way that we cannot figure out what the exact problem is just
  13 from the crash dump. We have a lot of inactionable crash reports and
  14 AddressSanitizer traces are usually a lot more actionable on their own
  15 (especially use-after-free traces). Part of this project is to figure
  16 out if and how many actionable crash reports ASan can give us just by
  17 surfing around. The success of the project of course also depends on the
  18 number of participants.
  19
  20 You can download the latest build using one of the links below. The
  21 builds are self-updating daily like regular nightly builds (like with
  22 regular builds, you can go to *"Help"* → *"About Nightly"* to force an
  23 update check or confirm that you run the latest version).
  24
  25 .. note::
  26
  27    If you came here looking for regular ASan builds (e.g. for fuzzing or
  28    as a developer to reproduce a crash), you should probably go to the
  29    :ref:`Address Sanitizer` doc instead.
  30
  31 .. _Requirements:
  32
  33 Requirements
  34 ~~~~~~~~~~~~
  35
  36 Current requirements are:
  37
  38 -  Windows or Linux-based Operating System
  39 -  16 GB of RAM recommended
  40 -  Special ASan Nightly Firefox Build
  41
  42    -  `Linux
  43       Download <https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.v2.mozilla-central.shippable.latest.firefox.linux64-asan-reporter-opt/artifacts/public/build/target.tar.bz2>`__
  44    -  `Windows
  45       Download <https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.v2.mozilla-central.shippable.latest.firefox.win64-asan-reporter-shippable-repackage-signing/artifacts/public/build/target.installer.exe>`__
  46
  47 If you are already using regular Nightly, it should be safe to share the
  48 profile with the regular Nightly instance. If you normally use a beta or
  49 release build (and you would like to be able to switch back to these),
  50 you should consider using a second profile.
  51
  52 .. warning::
  53
  54    **Windows Users:** Please note that the Windows builds currently show
  55    an error during setup (see "*Known Issues*" section below), but
  56    installation works nonetheless. We are working on the problem.
  57
  58 .. note::
  59
  60    If you run in an environment with any sorts of additional security
  61    restrictions (e.g. custom process sandboxing), please make sure that
  62    your /tmp directory is writable and the shipped ``llvm-symbolizer``
  63    binary is executable from within the Firefox process.
  64
  65 Preferences
  66 ~~~~~~~~~~~
  67
  68 If you wish for your crash report to be identifiable, you can go to
  69 ``about:config`` and set the **``asanreporter.clientid``** to your
  70 **valid email address**. This isn't mandatory, you can of course report
  71 crash traces anonymously. If you decide to send reports with your email
  72 address and you have a Bugzilla account, consider using the same email
  73 as your Bugzilla account uses. We will then Cc you on any bugs filed
  74 from your crash reports. If your email does not belong to a Bugzilla
  75 account, then we will not publish it but only use it to resolve
  76 questions about your crash reports.
  77
  78 .. note::
  79
  80    Setting this preference helps us to get back to you in case we have
  81    questions about your setup/OS. Please consider using it so we can get
  82    back to you if necessary.
  83
  84 Bug Bounty Program
  85 ~~~~~~~~~~~~~~~~~~
  86
  87 As a special reward for participating in the program, we decided to
  88 treat all submitted reports as if they were filed directly in Bugzilla.
  89 This means that reports that
  90
  91 -  indicate a security issue of critical or high rating
  92 -  **and** that can be fixed by our developers
  93
  94 are eligible for a bug bounty according to our `client bug bounty
  95 program
  96 rules <https://www.mozilla.org/security/client-bug-bounty/>`__. As
  97 the report will usually not include any steps to reproduce or a test
  98 case, it will most likely receive a lower-end bounty. Like with regular
  99 bug reports, we would typically reward the first (identifiable) report of
 100 an issue.
 101
 102 .. warning::
 103
 104    If you would like to participate in the bounty program, make sure you
 105    set your **``asanreporter.clientid``** preference as specified above.
 106    We cannot reward any reports that are submitted with no email
 107    address.
 108
 109
 110 Known Issues
 111 ~~~~~~~~~~~~
 112
 113 This section lists all currently known limitations of the ASan Nightly
 114 builds that are considered bugs.
 115
 116 -  [STRIKEOUT:Flash is currently not working]
 117 -  `Bug
 118    1477490 <https://bugzilla.mozilla.org/show_bug.cgi?id=1477490>`__\ [STRIKEOUT:-
 119    Windows: Stack instrumentation disabled due to false positives]
 120 -  `Bug
 121    1478096 <https://bugzilla.mozilla.org/show_bug.cgi?id=1478096>`__ -
 122    **Windows:** Error during install with maintenanceservice_tmp.exe
 123 -  It has been reported that ASan Nightly performance is particularly
 124    bad if you run on a screen with 120hz refresh rate. Switching to 60hz
 125    should improve performance drastically.
 126
 127 Note that these bugs are **specific** to ASan Nightly as listed in the
 128 `tracking bug dependency
 129 list <https://bugzilla.mozilla.org/showdependencytree.cgi?id=1386297&hide_resolved=0>`__.
 130 For the full list of bugs found by this project, see `this
 131 list <https://bugzilla.mozilla.org/showdependencytree.cgi?id=1479399&hide_resolved=0>`__
 132 instead and note that some bugs might not be shown because they are
 133 security bugs.
 134
 135 If you encounter a bug not listed here, please file a bug at
 136 `bugzilla.mozilla.org <https://bugzilla.mozilla.org/>`__ or send an
 137 email to
 138 `choller@mozilla.com <mailto:choller@mozilla.com?subject=%5BASan%20Nightly%20Project%5D%5BBug%20Report%5D>`__.
 139 When filing a bug, it greatly helps if you Cc that email address and
 140 make the bug block `bug
 141 1386297 <https://bugzilla.mozilla.org/show_bug.cgi?id=1386297>`__.
 142
 143 FAQ
 144 ~~~
 145
 146 What additional data is collected?
 147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 148
 149 The project only collects ASan traces and (if you set it in the
 150 preferences) your email address. We don't collect any other browser
 151 data, in particular not the sites you were visiting or page contents. It
 152 is really just crash traces submitted to a remote location.
 153
 154 .. note::
 155
 156    The ASan Nightly browser also still has all the data collection
 157    capabilities of a regular Nightly browser. The answer above only
 158    refers to what this project collects **in addition** to what the
 159    regular Nightly browser can collect.
 160
 161 What's the performance impact?
 162 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 163
 164 The ASan Nightly build only comes with a slight slowdown at startup and
 165 browsing, sometimes it is not even noticeable. The RAM consumption
 166 however is much higher than with a regular build. Be prepared to restart
 167 your browser sometimes, especially if you use a lot of tabs at once.
 168 Also, the updates are larger than the regular ones, so download times
 169 for updates will be higher, especially if you have a slower internet
 170 connection.
 171
 172 .. warning::
 173
 174    If you experience performance issues, see also the *"Known Issues"*
 175    section above, in particular the problem about screen refresh rate
 176    slowing down Firefox.
 177
 178 What about stability?
 179 ^^^^^^^^^^^^^^^^^^^^^
 180
 181 The browser is as stable as a regular Nightly build. Various people have
 182 been surfing around with it for their daily work for weeks now and we
 183 have barely received any crash reports.
 184
 185 How do I confirm that I'm running the correct build?
 186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 187
 188 If you open ``about:config`` and type *"asanreporter"* into the search
 189 field, you should see an entry called ``asanreporter.apiurl`` associated
 190 with a URL. Do not modify this value.
 191
 192 .. warning::
 193
 194    Since Firefox 64, the *"ASan Crash Reporter"* feature is no longer
 195    listed in ``about:support``
 196
 197 Will there be support for Mac?
 198 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 199
 200 We are working on support for Mac, but it might take longer because we
 201 have no ASan CI coverage on Mac due to hardware constraints. If you work
 202 on Release Engineering and would like to help make e.g. Mac happen
 203 earlier, feel free to `contact
 204 me <mailto:choller@mozilla.com?subject=%5BASan%20Nightly%20Project%5D%20>`__.