Skip to content

Commit bc67680

Browse files
ericbrumerericbrumer
committed
Initial batch of asan.md changes
1 parent 3657d10 commit bc67680

File tree

1 file changed

+98
-80
lines changed

1 file changed

+98
-80
lines changed

‎docs/cpp/ASAN/asan-top-level.md

Lines changed: 98 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@ helpviewer_keywords: ["ASan","sanitizers","AddressSanitizer","clang_rt.asan","Cl
88

99
# Address Sanitizer
1010

11-
## Intro
11+
C & C++ are some of the most widely used programming languages in the world. While C & C++ are powerful languages, they can suffer from different types of bugs which affect program correctness and program security. Starting with Visual Studio 2019 16.9, the Microsoft Visual C++ compiler and IDE support Address Sanitizer technology to help light up hard-to-find bugs that can be otherwise difficult to find.
1212

13-
We describe a new compiler flag `-fsanitize=address` which may result in exposing hidden [errors](#errors) in your code, not exposed by current testing.
13+
After choosing the (!asan installer option!), simply select the Address Sanitizer dropdown in your project properties, or set the `-fsanitize=address` compiler switch on the command line, or use Visual Studio cmake integration, recompile, and then run your program as normal to light up [bugs](#errors) right in the debugger.
14+
15+
For CI/CD systems use the ASAN_SAVE_DUMPS environment variable to store ASAN crash dumps for post-mortem debugging.
1416

1517
Using this flag can reduce your time spent on:
1618

@@ -20,19 +22,19 @@ Using this flag can reduce your time spent on:
2022
- Stress testing
2123
- Integrating new source code
2224

23-
Building with `-fsanitize=address` and using your existing test assets, is a highly recommended step in properly testing your software. With just a [simple recompile](#Simple-command-line-interface), you can expose difficult to find, errors with **no false positives**. This class of errors is not found with [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160) or [/analyze](https://docs.microsoft.com/en-us/cpp/code-quality/code-analysis-for-c-cpp-overview?view=msvc-160).
25+
The Address Sanitizer is a compiler and runtime runtime [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany). Starting with Visual Studio 2019 16.9 this technology is offered in the Visual C++ compiler toolchain. Many projects can enable Address Sanitizer with a project setting, or a single additional compiler switch. There are known limitations in certain (!!! link !!!) compilation modes (incremental linking, or the [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160) switch, for example), but otherwise all configurations of x86 and x64 are supported.
2426

27+
`-fsanitize=address` is a powerful alternative to [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160), and in addition to [/analyze](https://docs.microsoft.com/en-us/cpp/code-quality/code-analysis-for-c-cpp-overview?view=msvc-160) provides compile-time and run-time bug-finding technologies which leverage your existing build systems and existing test assets.
2528

26-
## Developer Message
29+
## Using the Address Sanitizer
2730

28-
The Address Sanitizer is a compiler based technology targeting a runtime [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany). This [compiler](#Compiler) and [runtime](#address-sanitizer-runtimes) technology has become the "defacto" industry standard for finding memory safety issues. We now offer this technology as a fully supported feature in Visual Studio for the Windows platform. If your existing code compiles with our current Windows compiler, then it will compile with the extra flag -fsanitize=address under any level of optimization and all other compatible flags (e.g., /RTC is not compatible, yet).
31+
!!! We need a picture of the installer option here and mention it's required first !!!
2932

3033
Microsoft recommends using the Address Sanitizer in these **three standard workflows**:
3134

3235
- **Developer inner loop**
3336
- Visual Studio - Command line
34-
- Visual Studio - Project system with integrated IDE error reporting support.
35-
37+
- Visual Studio - Project system with integrated IDE error reporting support
3638

3739
- **CI/CD** - continuous integration / continuous development
3840
- CMake
@@ -42,34 +44,108 @@ Microsoft recommends using the Address Sanitizer in these **three standard workf
4244
- [Azure OneFuzz](https://www.microsoft.com/security/blog/2020/09/15/microsoft-onefuzz-framework-open-source-developer-tool-fix-bugs/)
4345
- Local Machine
4446

45-
This MSDN article will cover all the information needed to enable your builds for any of the three workflows listed above. The information will be specific to the Microsoft Windows 10 platform and supplement existing documentation from [Google, Apple and GCC](#Google,-Apple-and-GCC-documentation). We start with a simple command line use of the compiler and linker.
47+
This article will cover all the information needed to enable your builds for any of the three workflows listed above. The information will be specific to the Microsoft Windows 10 platform and supplement existing documentation from [Google, Apple and GCC](#Google,-Apple-and-GCC-documentation).
4648

4749
> [!NOTE] Current support is limited to x86 and AMD64 on Windows 10. **Customer feedback** would help us prioritize shipping these sanitizers in the future: -fsanitize=thread, -fsanitize=leak, -fsanitize=memory, -fsanitize=hwaddress or -fsanitize=undefined.
4850
51+
## Using the Address Sanitizer from a Developer Command Prompt
52+
53+
Compile with `-fsanitize=address` to enable Address Sanitizer. The compiler flag `-fsanitize=address` is compatible with all existing C++ or C optimization levels (e.g., /Od, /O1, /O2, /O2 /GL and PGO), works with static and dynamic CRTs (e.g. /MD, /MDd, /MT, /MTd) and can be used to create a .EXE or .DLL. Debug information is required for the Address Sanitizer runtime to print correct call stacks on errors; In this example we pass `-Zi`.
54+
55+
The Address Sanitizer libraries (.lib files) will be linked in for you. For more detail, and for guidelines on partitioned build systems, see [building to target the Address Sanitizer runtime.](.\ASan-building.md).
56+
57+
```cpp
58+
#include <iostream>
59+
int x[100];
60+
int main() {
61+
std::cout << "Hello!" << std::endl;
62+
x[100] = 5; // Boom!
63+
return 0;
64+
}
65+
66+
```
4967
50-
## Simple command line interface
68+
C:\> cl main.cpp -fsanitize=address /Zi
5169
52-
Adding the flag -fsanitize=address to your command line (with /Zi to emit debug info.) is all you need to compile and automatically link all required libraries. This can be used to create an .EXE or DLL. The compiler flag `-fsanitize=address` is compatible with all existing C++ or C optimization levels (e.g., /Od, /O1, /O2, /O2 /GL and PGO).
70+
!!! Show media/something here !!! with the red boxes. And describe the red boxes, and the note about the symbolizer.
5371
54-
**Creating a main.exe in one step.**
72+
## Using the Address Sanitizer from Visual Studio
5573
56-
C:\> cl -fsanitize=address /Zi main.cpp file2.cpp 3dparty.lib
74+
!!! todo, make a different example with a different error, animated gif of IDE, and list of instructions !!!
5775
58-
The compiler will default to automatically linking main.exe with the static versions of the Address Sanitizer runtime binaries and the static [CRT](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=msvc-160). Throwing [/MD](https://docs.microsoft.com/en-us/cpp/build/reference/md-mt-ld-use-run-time-library?view=msvc-160) flag will change the default link behavior and cause the dynamic versions of the libraries to be used instead.
76+
## Using the Address Sanitizer from Visual Studio: CMake
5977
60-
For more partitioned build systems, the following command lines show examples of the required compile and link lines to produce an "instrumented" main.exe.
78+
!!! todo, make a different example with a different error, animated gif of CMake, and list of instructions !!!
6179
62-
**Creating a main.exe with an explicit link line.**
80+
## Offline Address Sanitizer crash dumps
6381
64-
C:\> cl -c -fsanitize=address -O2 -Zi main.cpp file2.cpp file3.cpp
82+
Address Sanitizer exceptions are triggered one of the many [errors](#errors) are detected at runtime. When run from the command line the Address Sanitizer runtime produces text output with error information. When run from the Visual Studio IDE the debugger displays the error information.
6583
66-
C:\> link -debug -incremental:no main.obj file2.obj file3.obj
84+
To produce a dump file of the error which can be debugged offline, set an environment variable which is consumed by the Address Sanitizer runtime.
6785
68-
The compiler requires opting into -Zi for debug information and the linker requires -debug to emit that debug information. One caveat is that `-debug` defaults to producing code for future incremental linking for rapid iterative development. which is not compatible with the stack walker used by the Address Sanitizer runtime. The Address Sanitizer requires `link -debug -incremental:no` and it will warn appropriately.
86+
`set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
6987
70-
See the section on [building to target the Address Sanitizer runtime.](.\ASan-building.md) for more detail.
88+
Upon error, your application will produce MyFileName.dmpx which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) that can be opened and debugged using Visual Studio.
89+
90+
**Note** that like all other dump files, [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) must be available and must match the version of the source compiled.
91+
92+
93+
## Error types
94+
95+
The following list of runtime errors can be exposed when you run your binaries compiled Address Sanitizer:
96+
97+
- [stack-use-after-scope](.\examples-stack-use-after-scope.md)
98+
- [stack-buffer-overflow](.\examples-stack-buffer-overflow.md)
99+
- [stack-buffer-underflow](.\examples-stack-buffer-underflow.md)
100+
- [stack-use-after-return](.\examples-stack-use-after-return.md)
101+
- [heap-buffer-overflow](.\examples-heap-buffer-overflow.md)
102+
- [heap-use-after-free](.\examples-heap-use-after-free.md)
103+
- [double-free](.\examples-double-free.md)
104+
- [dynamic-stack-buffer-overflow](.\examples-dynamic-stack-buffer-overflow.md)
105+
- [global-overflow](.\examples-global-overflow.md)
106+
- [calloc-overflow](.\examples-calloc-overflow.md)
107+
- [new-delete-type-mismatch](.\examples-new-delete-type-mismatch.md)
108+
- [memcpy-param-overlap](.\examples-memcpy-param-overlap.md)
109+
- [strcat-param-overlap](.\examples-strcat-param-overlap.md)
110+
- [allocation-size-too-big](.\examples-allocation-size-too-big.md)
111+
- [invalid-aligned-alloc-alignment](.\examples-invalid-aligned-alloc-alignment.md)
112+
- [use-after-poison](.\examples-use-after-poison.md)
113+
- [alloc-dealloc-mismatch](.\examples-alloc-dealloc-mismatch.md)
114+
115+
## Differences with Clang
116+
117+
We differ in two functional areas:
118+
119+
- **stack-use-after-scope** - this is on by default and can't be turned off.
120+
- **stack-use-after-return** - this is not available by just setting ASAN_OPTIONS
121+
122+
See [Building for the Address Sanitizer with MSVC](.\asan-building.md).These decisions were made to reduce the test matrix used to ship this first version.
123+
124+
## Exiting industry documentation
125+
126+
Extensive documentation already exists for these language and platform dependent implementations of the Address Sanitizer technology.
127+
128+
- [Google](https://github.com/google/sanitizers/wiki/AddressSanitizer)
129+
- [Apple](https://developer.apple.com/documentation/xcode/diagnosing_memory_thread_and_crash_issues_early)
130+
- [GCC](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
131+
132+
This seminal paper on the [Address Sanitizer](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) describes the implementation.
133+
134+
!!! is this where we should mention that we don't implement the entire complete feature set? !!!
135+
136+
## See also
137+
138+
- [Building for the Address Sanitizer with MSVC](.\asan-building.md)
139+
140+
- [Address Sanitizer runtime](.\address-sanitizer-runtime.md)
71141
72-
## Errors ##
142+
These structure all further details into the tools and the run times they target.
143+
144+
----
145+
146+
## STUFF TO KEEP -- remove later!!!!!
147+
148+
## Viewing Address Saniziter Errors ##
73149
74150
There are three ways your code can generate error reports:
75151
@@ -81,6 +157,7 @@ These types of reports can be generated for many types of [errors found at runti
81157
82158
### Example
83159
160+
!!! Jim, I think we need a simpler example here. !!!
84161
The following source code is **safe by coincidence**. It will **not** fail at runtime. The Windows 10, 16.9 version of the C runtime, will pad the 13 bytes requested, in order to facilitate alignment for subsequent calls to alloca.
85162
86163
```cpp
@@ -134,15 +211,6 @@ Consider the following error found in our cached version of spec2k6\povray where
134211

135212
![IDE: povray](media\povray.png)
136213

137-
### Snapshot files
138-
139-
There's a powerful feature for workflows that need to retain detailed error information for processing errors off-line. If you **simply** set an environment variable, then your .EXE or .DLL will create a snap shot file.
140-
141-
`set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
142-
143-
Upon error, your application will produce MyFileName.dmpx which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) containing extra meta-data. This meta-data is used to formatting an Address Santiizer error in the IDE on top you your source code. This snapshot file can be displayed later (possibly on another machine), in a newer version of the Visual Studio IDE. The IDE will use the meta-data to display the exact error on the exact source line as it would be seen in a live debug session.
144-
145-
**Note** that this will require [symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) from a PDB. This PDB must be produced from the version of the source you compiled to produce the executable that contained the Address Sanitizer error. That insures the position of the error, and the call stack will be correct.
146214

147215
### VCASan library
148216

@@ -151,54 +219,4 @@ The flag -fsanitize=address automatically links a new static library to your .EX
151219
- In memory meta-data for directly interfacing with the VS IDE, [while debugging](#Error-types).
152220
- An optional [snap shot file](#Snapshot-files) with the same IDE meta-data.
153221

154-
These library features are detailed further in the section for [vcasan.lib](.\address-sanitizer-vcasan.md)
155-
156-
## Error types
157-
158-
The following list of runtime errors can be exposed when you run your binaries compiled -fsanitize=address. A drill down of each class of error, provides source code and Visual Stud screen shots. There are over 30 examples, with screen shots, within the following:
159-
160-
- [stack-use-after-scope](.\examples-stack-use-after-scope.md)
161-
- [stack-buffer-overflow](.\examples-stack-buffer-overflow.md)
162-
- [stack-buffer-underflow](.\examples-stack-buffer-underflow.md)
163-
- [stack-use-after-return](.\examples-stack-use-after-return.md)
164-
- [heap-buffer-overflow](.\examples-heap-buffer-overflow.md)
165-
- [heap-use-after-free](.\examples-heap-use-after-free.md)
166-
- [double-free](.\examples-double-free.md)
167-
- [dynamic-stack-buffer-overflow](.\examples-dynamic-stack-buffer-overflow.md)
168-
- [global-overflow](.\examples-global-overflow.md)
169-
- [calloc-overflow](.\examples-calloc-overflow.md)
170-
- [new-delete-type-mismatch](.\examples-new-delete-type-mismatch.md)
171-
- [memcpy-param-overlap](.\examples-memcpy-param-overlap.md)
172-
- [strcat-param-overlap](.\examples-strcat-param-overlap.md)
173-
- [allocation-size-too-big](.\examples-allocation-size-too-big.md)
174-
- [invalid-aligned-alloc-alignment](.\examples-invalid-aligned-alloc-alignment.md)
175-
- [use-after-poison](.\examples-use-after-poison.md)
176-
- [alloc-dealloc-mismatch](.\examples-alloc-dealloc-mismatch.md)
177-
178-
## Differences with Clang
179-
180-
We differ in two functional areas:
181-
182-
- **stack-use-after-scope** - this is on by default and can't be turned off.
183-
- **stack-use-after-return** - this is not available by just setting ASAN_OPTIONS
184-
185-
See [Building for the Address Sanitizer with MSVC](.\asan-building.md).These decisions were made to reduce the test matrix used to ship this first version.
186-
187-
## Exiting industry documentation
188-
189-
Extensive documentation already exists for these language and platform dependent implementations of the Address Sanitizer technology.
190-
191-
- [Google](https://github.com/google/sanitizers/wiki/AddressSanitizer)
192-
- [Apple](https://developer.apple.com/documentation/xcode/diagnosing_memory_thread_and_crash_issues_early)
193-
- [GCC](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
194-
195-
This seminal paper on the [Address Sanitizer](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) describes the implementation.
196-
197-
## See also
198-
199-
- [Building for the Address Sanitizer with MSVC](.\asan-building.md)
200-
201-
- [Address Sanitizer runtime](.\address-sanitizer-runtime.md)
202-
203-
These structure all further details into the tools and the run times they target.
204-
222+
These library features are detailed further in the section for [vcasan.lib](.\address-sanitizer-vcasan.md)

0 commit comments

Comments
 (0)