AddressSanitizer
Contract
| Field |
Bound contract |
| Trigger |
User needs to build or run native code with ASan, interpret an ASan report, or debug a memory-corruption failure. |
| Authority |
Reversible local: writes only the instrumented build artifacts and test invocations named by the user; rollback is discarding the instrumented binary and rebuilding without -fsanitize=address. No remote mutation. |
| Side effect |
Instrumented native build and test process under the target project directory. |
| Done |
When building or running: the target is instrumented, exercised, and any reported memory error is explained with a reproducible location. When interpreting an existing report: the error type, faulting source location, and allocation/deallocation sites are extracted from the report and mapped to a root cause, without requiring a fresh instrumented run. |
Inputs
Required when building or running: the native source or build target to instrument (C/C++ source, Rust crate with unsafe blocks or FFI, or an existing fuzz harness) and the command that exercises it.
Required when interpreting a report: a specific ASan report file or captured ASan output.
Optional: a preferred sanitizer combination, or a fuzzer in use (libFuzzer, AFL++, cargo-fuzz, honggfuzz). When interpreting a report, the build target and exercise command are also optional and used only to confirm the root cause against source.
Procedure
- Determine the invocation mode. If the user supplies an existing ASan report or captured output, take the report-interpretation branch (step 2R) and skip the build-and-run steps (3–9). If the user asks to build or run a target under ASan, take the build-and-run branch (steps 3–9). Done when: the mode is selected.
2R. Report interpretation. Read the supplied ASan report and extract the error type (heap-buffer-overflow, use-after-free, double-free, stack-buffer-overflow, memory leak), the faulting stack trace with source file and line, and the allocation/deallocation traces. If source is available, correlate the faulting and alloc/dealloc frames to the source to state the root cause. Done when: the error type, faulting location, and alloc/dealloc locations are extracted from the report and the root cause is stated. This branch does not require a fresh instrumented run.
- Confirm the target is C/C++ or Rust with unsafe blocks or FFI. ASan is not useful for pure safe languages without FFI. Linux gives full support; macOS and Windows have limited or experimental support: state the platform limitation before proceeding. Done when: the target is confirmed and platform limitations are stated.
- Compile and link the target with
-fsanitize=address -g. Apply the flag in both the compile and link steps; missing it at link time produces "ASan runtime not initialized." Add -O2 or -O3 if the uninstrumented slowdown exceeds roughly 4x. Done when: the target compiles and links with -fsanitize=address -g.
- Set
ASAN_OPTIONS for the run: verbosity=1 to confirm ASan is active at startup, abort_on_error=1 when a fuzzer requires abort() instead of _exit(), and detect_leaks=0 during fuzzing to keep LeakSanitizer output from cluttering crash reports. Join multiple options with colons. Done when: ASAN_OPTIONS are set for the run.
- If a fuzzer drives the target, lift its memory limit because ASan maps approximately 20 TB of virtual memory: libFuzzer
-rss_limit_mb=0, AFL++ -m none. For libFuzzer combine -fsanitize=fuzzer,address; for AFL++ set AFL_USE_ASAN=1 on the compiler; for cargo-fuzz pass --sanitizer=address; for honggfuzz compile the target with hfuzz-clang -fsanitize=address. Done when: the fuzzer's memory limit is lifted for ASan's virtual mapping.
- Run the instrumented binary or fuzzer. When ASan reports an error, extract the error type (heap-buffer-overflow, use-after-free, double-free, stack-buffer-overflow, memory leak), the faulting stack trace with source file and line, and the allocation/deallocation traces that show where the memory was created and freed. Done when: ASan output is captured with error type, stack trace, and alloc/dealloc traces.
- Map the error to a reproducible location: the faulting frame names the file and line of the illegal access; the alloc/dealloc frames name where the memory was born and died. Correlate these to the source to state the root cause. Done when: the root cause is stated with file, line, and alloc/dealloc locations.
- To combine with undefined-behavior detection, add
,undefined to the -fsanitize value (-fsanitize=address,undefined). Done when: -fsanitize=address,undefined is set if UBSan is requested.
Failure and recovery
- ASan runtime not initialized:
-fsanitize=address was missing from the link step. Re-link with the flag and rerun.
- Fuzzer kills the process immediately: memory limit is below ASan's 20 TB virtual mapping. Set
-rss_limit_mb=0 or -m none and rerun.
- LeakSanitizer output obscures crash reports: set
ASAN_OPTIONS=detect_leaks=0 during fuzzing; review leak reports separately at the end of a campaign.
- ASan prints no startup info: the binary was not instrumented. Rebuild with the flag and confirm
verbosity=1 prints ASan initialization.
- Partial result rule: a run that reports one memory error stops at that error; do not claim the target is clean. Report the error and its location; further runs may surface additional errors.
- Rollback: delete the instrumented binary and rebuild without
-fsanitize=address. No source change is required for instrumentation-only builds.
Output
When building or running: an instrumented binary or fuzz target, the exercise run result, and for any detected memory error a statement of the error type, the faulting source location, and the allocation/deallocation locations, sufficient to reproduce the failure. When interpreting a report: a statement of the error type, the faulting source location, and the allocation/deallocation locations extracted from the supplied report, with the root cause mapped to source where available.
1---2name: address-sanitizer3description: Use when building or running native code under AddressSanitizer, interpreting an existing ASan report, or debugging a memory-corruption failure. Not for remote or irreversible changes.4---56# AddressSanitizer78## Contract910| Field | Bound contract |11|---|---|12| Trigger | User needs to build or run native code with ASan, interpret an ASan report, or debug a memory-corruption failure. |13| Authority | Reversible local: writes only the instrumented build artifacts and test invocations named by the user; rollback is discarding the instrumented binary and rebuilding without `-fsanitize=address`. No remote mutation. |14| Side effect | Instrumented native build and test process under the target project directory. |15| Done | When building or running: the target is instrumented, exercised, and any reported memory error is explained with a reproducible location. When interpreting an existing report: the error type, faulting source location, and allocation/deallocation sites are extracted from the report and mapped to a root cause, without requiring a fresh instrumented run. |1617## Inputs1819Required when building or running: the native source or build target to instrument (C/C++ source, Rust crate with unsafe blocks or FFI, or an existing fuzz harness) and the command that exercises it.2021Required when interpreting a report: a specific ASan report file or captured ASan output.2223Optional: a preferred sanitizer combination, or a fuzzer in use (libFuzzer, AFL++, cargo-fuzz, honggfuzz). When interpreting a report, the build target and exercise command are also optional and used only to confirm the root cause against source.2425## Procedure26271. Determine the invocation mode. If the user supplies an existing ASan report or captured output, take the report-interpretation branch (step 2R) and skip the build-and-run steps (3–9). If the user asks to build or run a target under ASan, take the build-and-run branch (steps 3–9). Done when: the mode is selected.28292R. Report interpretation. Read the supplied ASan report and extract the error type (heap-buffer-overflow, use-after-free, double-free, stack-buffer-overflow, memory leak), the faulting stack trace with source file and line, and the allocation/deallocation traces. If source is available, correlate the faulting and alloc/dealloc frames to the source to state the root cause. Done when: the error type, faulting location, and alloc/dealloc locations are extracted from the report and the root cause is stated. This branch does not require a fresh instrumented run.30313. Confirm the target is C/C++ or Rust with unsafe blocks or FFI. ASan is not useful for pure safe languages without FFI. Linux gives full support; macOS and Windows have limited or experimental support: state the platform limitation before proceeding. Done when: the target is confirmed and platform limitations are stated.324. Compile and link the target with `-fsanitize=address -g`. Apply the flag in both the compile and link steps; missing it at link time produces "ASan runtime not initialized." Add `-O2` or `-O3` if the uninstrumented slowdown exceeds roughly 4x. Done when: the target compiles and links with `-fsanitize=address -g`.335. Set `ASAN_OPTIONS` for the run: `verbosity=1` to confirm ASan is active at startup, `abort_on_error=1` when a fuzzer requires `abort()` instead of `_exit()`, and `detect_leaks=0` during fuzzing to keep LeakSanitizer output from cluttering crash reports. Join multiple options with colons. Done when: `ASAN_OPTIONS` are set for the run.346. If a fuzzer drives the target, lift its memory limit because ASan maps approximately 20 TB of virtual memory: libFuzzer `-rss_limit_mb=0`, AFL++ `-m none`. For libFuzzer combine `-fsanitize=fuzzer,address`; for AFL++ set `AFL_USE_ASAN=1` on the compiler; for cargo-fuzz pass `--sanitizer=address`; for honggfuzz compile the target with `hfuzz-clang -fsanitize=address`. Done when: the fuzzer's memory limit is lifted for ASan's virtual mapping.357. Run the instrumented binary or fuzzer. When ASan reports an error, extract the error type (heap-buffer-overflow, use-after-free, double-free, stack-buffer-overflow, memory leak), the faulting stack trace with source file and line, and the allocation/deallocation traces that show where the memory was created and freed. Done when: ASan output is captured with error type, stack trace, and alloc/dealloc traces.368. Map the error to a reproducible location: the faulting frame names the file and line of the illegal access; the alloc/dealloc frames name where the memory was born and died. Correlate these to the source to state the root cause. Done when: the root cause is stated with file, line, and alloc/dealloc locations.379. To combine with undefined-behavior detection, add `,undefined` to the `-fsanitize` value (`-fsanitize=address,undefined`). Done when: `-fsanitize=address,undefined` is set if UBSan is requested.3839## Failure and recovery40- ASan runtime not initialized: `-fsanitize=address` was missing from the link step. Re-link with the flag and rerun.41- Fuzzer kills the process immediately: memory limit is below ASan's 20 TB virtual mapping. Set `-rss_limit_mb=0` or `-m none` and rerun.42- LeakSanitizer output obscures crash reports: set `ASAN_OPTIONS=detect_leaks=0` during fuzzing; review leak reports separately at the end of a campaign.43- ASan prints no startup info: the binary was not instrumented. Rebuild with the flag and confirm `verbosity=1` prints ASan initialization.44- Partial result rule: a run that reports one memory error stops at that error; do not claim the target is clean. Report the error and its location; further runs may surface additional errors.45- Rollback: delete the instrumented binary and rebuild without `-fsanitize=address`. No source change is required for instrumentation-only builds.4647## Output48When building or running: an instrumented binary or fuzz target, the exercise run result, and for any detected memory error a statement of the error type, the faulting source location, and the allocation/deallocation locations, sufficient to reproduce the failure. When interpreting a report: a statement of the error type, the faulting source location, and the allocation/deallocation locations extracted from the supplied report, with the root cause mapped to source where available.
OutlineDriven