{"id":25067,"date":"2019-10-23T15:20:36","date_gmt":"2019-10-23T15:20:36","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=25067"},"modified":"2021-03-24T17:12:44","modified_gmt":"2021-03-24T17:12:44","slug":"addresssanitizer-asan-for-windows-with-msvc","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/addresssanitizer-asan-for-windows-with-msvc\/","title":{"rendered":"AddressSanitizer (ASan) for Windows with MSVC"},"content":{"rendered":"<p>\u231a <em>This post was last updated on March 24th, 2021 with the latest information on ASan support.<\/em><\/p>\n<p><strong>Note:<\/strong> This feature is now generally available. To get started, take a look at the official <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/sanitizers\/asan\">AddressSanitizer for Windows with MSVC<\/a> documentation. Many experience improvements have been made since this blog post was published, and our docs have the latest information.<\/p>\n<p>&nbsp;<\/p>\n<p>We are pleased to announce <a href=\"https:\/\/github.com\/google\/sanitizers\/wiki\/AddressSanitizer\">AddressSanitizer (ASan)<\/a> support for the MSVC toolset. ASan is a fast memory error detector that can find runtime memory issues such as use-after-free and perform out of bounds checks. <a href=\"https:\/\/developercommunity.visualstudio.com\/content\/idea\/435735\/add-sanitizers-ub-address-thread-etc.html\">Support for sanitizers<\/a> has been one of our more popular suggestions on <a href=\"https:\/\/developercommunity.visualstudio.com\">Developer Community<\/a>, and we can now say that we have an experience for ASan on Windows, in addition to our <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/addresssanitizer-asan-for-the-linux-workload-in-visual-studio-2019\/\">existing support for Linux projects<\/a>.<\/p>\n<p>At Microsoft, we believe that developers should be able to use the tools of their choice, and we are glad to collaborate with the LLVM team to introduce more of their tooling into Visual Studio. In the past, we also incorporated tools like <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/clangformat-support-in-visual-studio-2017-15-7-preview-1\/\">clang-format<\/a>, and most recently, clang-tidy. MSVC support for ASan is available in our second <a href=\"https:\/\/visualstudio.microsoft.com\/vs\/preview\/\">Preview release of Visual Studio 2019 version 16.4<\/a>.<\/p>\n<p>To bring ASan to Windows and MSVC, we made the <span style=\"font-size: 1rem;\">following changes:<\/span><\/p>\n<ul>\n<li>The ASan runtime has been updated to better target Windows binaries<\/li>\n<li>The MSVC compiler can now instrument binaries with ASan<\/li>\n<li>CMake and MSBuild integrations have been updated to support enabling ASan<\/li>\n<li>The Visual Studio debugger now can detect ASan errors in Windows binaries<\/li>\n<li>ASan can be installed from the Visual Studio installer for the C++ Desktop workload<\/li>\n<\/ul>\n<p>When you\u2019re debugging your ASan-instrumented binary in Visual Studio, the IDE Exception Helper will be displayed when an issue is encountered, and program execution will stop. You can also view detailed ASan logging information in the Output window.<\/p>\n<p><img decoding=\"async\" class=\"alignnone size-full wp-image-25099\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-1.jpg\" alt=\"ASan Exception in Visual Studio\" width=\"1267\" height=\"643\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-1.jpg 1267w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-1-300x152.jpg 300w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-1-768x390.jpg 768w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-1-1024x520.jpg 1024w\" sizes=\"(max-width: 1267px) 100vw, 1267px\" \/><\/p>\n<h3>Installing ASan support for Windows<\/h3>\n<p>ASan is included with the C++ Desktop workload by default for new installations. However, if you are upgrading from an older version of Visual Studio 2019, you will need to enable ASan support in the Installer after the upgrade:<\/p>\n<p><img decoding=\"async\" class=\"alignnone size-full wp-image-25098\" style=\"font-size: 1rem;\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASan-Blog-Post-Image-0.png\" alt=\"Visual Studio Installer with ASan checkbox\" width=\"1290\" height=\"720\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASan-Blog-Post-Image-0.png 1290w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASan-Blog-Post-Image-0-300x167.png 300w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASan-Blog-Post-Image-0-768x429.png 768w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASan-Blog-Post-Image-0-1024x572.png 1024w\" sizes=\"(max-width: 1290px) 100vw, 1290px\" \/><\/p>\n<p>You can click\u00a0<strong>Modify<\/strong> on your existing Visual Studio installation from the Visual Studio Installer to get to the screen above.<\/p>\n<p>Note: if you run Visual Studio on the new update but have not installed ASan, you will get the following error when you run your code:<\/p>\n<p><em>LNK 1356 \u2013 cannot find library \u2018clang_rt.asan_dynamic-i386.lib\u2019<\/em><\/p>\n<p>&nbsp;<\/p>\n<h3>Turning on ASan for Windows MSBuild projects<\/h3>\n<p>You can turn on ASan for an MSBuild project by right-clicking on the project in <em>Solution Explorer<\/em>, choosing <em>Properties<\/em>, navigating under C\/C++ &gt; General, and changing the <strong>Enable Address Sanitizer (Experimental)<\/strong> option. The same approach can be used to enable ASan for MSBuild Linux projects.<\/p>\n<p><img decoding=\"async\" class=\"alignnone size-full wp-image-25100\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-2.png\" alt=\"Enabling ASan in the MSBuild project properties\" width=\"1231\" height=\"842\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-2.png 1231w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-2-300x205.png 300w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-2-768x525.png 768w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-2-1024x700.png 1024w\" sizes=\"(max-width: 1231px) 100vw, 1231px\" \/><\/p>\n<p><strong>Note: <\/strong>Right now, this will only work for x86 Release targets, though we will be expanding to more architectures in the future.<\/p>\n<p>&nbsp;<\/p>\n<h3>Turning on ASan for Windows CMake projects<\/h3>\n<p>To enable ASan for CMake projects targeting Windows, do the following:<\/p>\n<ol>\n<li>Open the Configurations dropdown at the top of the IDE and click on <em>Manage Configurations<\/em>. This will open the CMake Project Settings UI, which is saved in a CMakeSettings.json file.<\/li>\n<li>Click the <em>Edit JSON<\/em> link in the UI. This will switch the view to raw .json.<\/li>\n<li>Under the <em>x86-Release<\/em> configuration, add the following property: <span class=\"lang:default decode:true crayon-inline \">&#8220;addressSanitizerEnabled&#8221;: true<\/span><\/li>\n<\/ol>\n<p>You may get a green squiggle under the line above with the following warning: <em>Property name is not allowed by the schema<\/em>. This is a bug that will be fixed shortly \u2013 the property will in fact work.<\/p>\n<p>Here is an image of the relevant section of the CMakeSettings.json file after the change:<\/p>\n<p><img decoding=\"async\" class=\"alignnone size-full wp-image-25101\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-3.jpg\" alt=\"Enabling ASan in the CMakeSettings.json file\" width=\"1036\" height=\"616\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-3.jpg 1036w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-3-300x178.jpg 300w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-3-768x457.jpg 768w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2019\/10\/ASAN-Blog-Post-Image-3-1024x609.jpg 1024w\" sizes=\"(max-width: 1036px) 100vw, 1036px\" \/><\/p>\n<p>We will further simplify the process for enabling ASan in CMake projects in a future update.<\/p>\n<p>&nbsp;<\/p>\n<h3>Contributions to ASan Runtime<\/h3>\n<p>To enable a great Windows experience, we decided to contribute to the <a href=\"https:\/\/github.com\/llvm\/llvm-project\/tree\/master\/compiler-rt\">LLVM compiler-rt project<\/a> and reuse their runtime in our implementation of ASan. Our contributions to the ASan project include bug fixes and improved interception for <span class=\"lang:default decode:true crayon-inline \">HeapAlloc<\/span>\u00a0, <span class=\"lang:default decode:true crayon-inline \">RtlAllocateHeap<\/span>\u00a0, <span class=\"lang:default decode:true crayon-inline \">GlobalAlloc<\/span>\u00a0, and <span class=\"lang:default decode:true crayon-inline \">LocalAlloc<\/span>\u00a0, along with their corresponding <span class=\"lang:default decode:true crayon-inline \">Free<\/span>\u00a0<em>,<\/em> <span class=\"lang:default decode:true crayon-inline\">ReAllocate<\/span>\u00a0, and <span class=\"lang:default decode:true crayon-inline \">Size<\/span>\u00a0functions. Anyone can enable these features by adding the following to the <span class=\"lang:default decode:true crayon-inline \">ASAN_OPTIONS<\/span>\u00a0environment variable for either Clang or MSVC on Windows:<\/p>\n<pre class=\"lang:default decode:true \">set ASAN_OPTIONS= windows_hook_rtl_allocators=true<\/pre>\n<p><a href=\"https:\/\/github.com\/google\/sanitizers\/wiki\/AddressSanitizerFlags\">Additional options<\/a> can be added with a colon at the end of the line above.<\/p>\n<p>&nbsp;<\/p>\n<h3>Changes to MSVC to enable ASan<\/h3>\n<p>To enable ASan, c1.dll and c2.dll have been modified to add instrumentation to programs at compile time. For a 32-bit address space, about 200 MB of memory is allocated to represent (or \u2018shadow\u2019) the entire address space. When an allocation is made, the shadow memory is modified to represent that the allocation is now valid to access. When the allocation is freed or goes out of scope, the shadow memory is modified to show that this allocation is no longer valid. Memory accesses which are potentially dangerous are checked against their entry in the shadow memory to verify that the memory is safe to access at that time. Violations are reported to the user as output from either stderr or an exception window in Visual Studio. The allocation data in the shadow memory is checked before the access happens. The AddressSanitizer algorithm enables error reports to show exactly where the problem occurred and what went wrong.<\/p>\n<p>This means that programs compiled with MSVC + ASan also have the appropriate clang_rt.asan library linked for their target. Each library has a specific use case and linking can be complicated if your program is complex.<\/p>\n<p>&nbsp;<\/p>\n<h3>Compiling with ASan from the console<\/h3>\n<p>If you are on Visual Studio version 16.9 Preview 3 or later, if the<code>fsanitize=address<\/code> compiler flag is specified, ASan libraries are automatically linked (both for console and IDE builds).<\/p>\n<p>For console compilation, if you are on <strong>Visual Studio version 16.9 Preview 2 or earlier<\/strong>, you will have to link the ASan libraries manually. Here are the libraries required for an x86 target:<\/p>\n<ul>\n<li><em>clang_rt.asan-i386.lib<\/em> \u2013 static runtime compatible with \/MT CRT.<\/li>\n<li><em>clang_rt.asan_cxx-i386.lib<\/em> -static runtime component which adds support for new and delete, also compatible with \/MT CRT.<\/li>\n<li><em>clang_rt.asan_dynamic-i386.lib<\/em> \u2013 dynamic import library, compatible with \/MD CRT.<\/li>\n<li><em>clang_rt.asan_dynamic-i386.dll<\/em> \u2013 dynamic runtime DLL, compatible with \/MD.<\/li>\n<li><em>clang_rt.asan_dynamic_runtime_thunk-i386.lib<\/em> \u2013 dynamic library to import and intercept some \/MD CRT functions manually.<\/li>\n<li><em>clang_rt.asan_dll_thunk-i386.lib<\/em> \u2013 import library which allows an ASAN instrumented DLL to use the static ASan library which is linked into the main executable. Compatible with \/MT CRT.<\/li>\n<\/ul>\n<p>Once you have selected the correct ASan runtime to use, you should add <span class=\"lang:default decode:true crayon-inline \">\/wholearchive:&lt;library to link&gt;<\/span>\u00a0to your link line and add the appropriate library to your executables. The clang_rt.asan_dynamic_i386.dll is not installed into System32, so when running you should make sure it is available in your environment\u2019s search path.<\/p>\n<p>Some additional instructions:<\/p>\n<ul>\n<li><strong>When compiling a single static EXE:<\/strong> link the static runtime (<em>asan-i386.lib)<\/em> and the cxx library if it is needed.<\/li>\n<li><strong>When compiling an EXE with the \/MT runtime which will use ASan-instrumented DLLs:<\/strong> the EXE needs to have <em>asan-i386.lib<\/em> linked and the DLLs need the <em>clang_rt.asan_dll_thunk-i386.lib<\/em>. This allows the DLLs to use the runtime linked into the main executable and avoid a shadow memory collision problem.<\/li>\n<li><strong>When compiling with the \/MD dynamic runtime:<\/strong> all EXE and DLLs with instrumentation should be linked with copies of <em>asan_dynamic-i386.lib<\/em> and <em>clang_rt.asan_dynamic_runtime_thunk-i386.lib<\/em>. At runtime, these libraries will refer to the <em>clang_rt.asan_dynamic-i386.dll<\/em> shared ASan runtime.<\/li>\n<\/ul>\n<p>The ASan runtime libraries patch memory management functions at run-time and redirect executions to an ASan wrapper function which manages the shadow memory. This can be unstable if the runtime environment differs from what the libraries have been written to expect. Please submit any compile or run time errors which you encounter while using ASan via the feedback channels below!<\/p>\n<p><strong>Note: <\/strong>Loading ASan-instrumented DLLs with an non-ASan-instrumented EXE without linking the clang_rt.asan_dynamic and clang_rt.asan_dynamic\u00ad_runtime_thunk library will result in false positive ASan reports. This is due to allocations being created in-between program initialization and whenever the ASan instrumented DLL is loaded. Any allocations which are created during this window will result in an erroneous bug report when they are passed into the newly intercepted CRT functions. These false positive reports are avoidable if you link the dynamic import libraries into the main executable; since linking the dynamic runtime libraries in this manner allows the interceptors to initialize at the proper time. Be sure to use the \/wholearchive linker flag to ensure asan\u2019s init routines are not optimized away in the main exe.<\/p>\n<p>&nbsp;<\/p>\n<h3>Send us feedback!<\/h3>\n<p>Your feedback is key for us to deliver the best experience running ASan in Visual Studio. We\u2019d love for you to try out the latest Preview version of <a href=\"https:\/\/visualstudio.microsoft.com\/vs\/preview\/\">Visual Studio 2019 version 16.4<\/a> and let us know how it\u2019s working for you, either in the comments below or <a href=\"mailto:visualcpp@microsoft.com\">via email<\/a>. If you encounter problems with the experience or have suggestions for improvement, please <a href=\"https:\/\/docs.microsoft.com\/en-us\/visualstudio\/ide\/how-to-report-a-problem-with-visual-studio?view=vs-2019\">Report A Problem<\/a> or reach out via <a href=\"https:\/\/developercommunity.visualstudio.com\/spaces\/62\/index.html\">Developer Community<\/a>. You can also find us on Twitter <a href=\"https:\/\/twitter.com\/visualc\">@VisualC<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>\u231a This post was last updated on March 24th, 2021 with the latest information on ASan support. Note: This feature is now generally available. To get started, take a look at the official AddressSanitizer for Windows with MSVC documentation. Many experience improvements have been made since this blog post was published, and our docs have [&hellip;]<\/p>\n","protected":false},"author":1063,"featured_media":25099,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[270],"tags":[],"class_list":["post-25067","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-announcement"],"acf":[],"blog_post_summary":"<p>\u231a This post was last updated on March 24th, 2021 with the latest information on ASan support. Note: This feature is now generally available. To get started, take a look at the official AddressSanitizer for Windows with MSVC documentation. Many experience improvements have been made since this blog post was published, and our docs have [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/25067","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/1063"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=25067"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/25067\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/25099"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=25067"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=25067"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=25067"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}