Software Engineer's Notes

What is AddressSanitizer?

AddressSanitizer (ASan) is a fast memory error detector built into modern compilers (Clang/LLVM and GCC). When you compile your C/C++ (and many C-compatible) programs with ASan, the compiler injects checks that catch hard-to-debug memory bugs at runtime, then prints a readable, symbolized stack trace to help you fix them.

Finds (most common):

• Heap/stack/global buffer overflows & underflows
• Use-after-free and use-after-scope (return)
• Double-free and invalid free
• Memory leaks (via LeakSanitizer integration)

How does ASan work (deep dive)

ASan adds lightweight instrumentation to your binary and links a runtime that monitors memory accesses:

1. Shadow Memory:
   ASan maintains a “shadow” map where every 8 bytes of application memory correspond to 1 byte in shadow memory. A non-zero shadow byte marks memory as poisoned (invalid); a zero marks it valid. Every load/store checks the shadow first.
2. Redzones (Poisoned Guards):
   Around each allocated object (heap, stack, globals), ASan places redzones—small poisoned regions. If code overreads or overwrites into a redzone, ASan trips immediately with an error report.
3. Quarantine for Frees:
   Freed heap blocks aren’t immediately reused—they go into a quarantine and stay poisoned for a while. Accessing them becomes a use-after-free that ASan can catch reliably.
4. Stack & Global Instrumentation:
   The compiler lays out extra redzones around stack and global objects, poisoning/unpoisoning as scopes begin and end. This helps detect use-after-scope and overflows on local arrays.
5. Intercepted Library Calls:
   Common libc/allocator functions (e.g., malloc, memcpy) are intercepted so ASan can keep metadata accurate and report clearer diagnostics.
6. Detailed Reports & Symbolization:
   On error, ASan prints the access type/size, the exact location, the allocation site, and a symbolized backtrace (when built with debug info), plus hints (“allocated here”, “freed here”).

Benefits

• High signal, low friction: You recompile with a flag; no code changes needed in most cases.
• Fast enough for day-to-day testing: Typically 1.5–2× CPU overhead—often fine for local runs and CI.
• Readable diagnostics: Clear error type, file/line, and allocation/free stacks dramatically reduce debug time.
• Great with fuzzing & tests: Pair with libFuzzer/AFL/pytest-cpp/etc. to turn latent memory issues into immediate, actionable crashes.

Limitations & Caveats

• Overheads: Extra CPU and memory (often 2–3× RAM). Not ideal for tight-resource or latency-critical production paths.
• Rebuild required: You must compile and link with ASan. Prebuilt third-party libs without ASan may dilute coverage or require special handling.
• Not all bugs:
  • Uninitialized reads → use MemorySanitizer (MSan)
  • Data races → use ThreadSanitizer (TSan)
  • Undefined behavior (e.g., integer overflow UB, misaligned access) → UBSan
• Allocator/custom low-level code: Exotic allocators or inline assembly may need tweaks or suppressions.
• Coverage nuances: Intra-object overflows or certain pointer arithmetic patterns may escape detection.

When should you use it?

• During development & CI for C/C++ services, libraries, and tooling.
• Before releases to smoke-test with integration and end-to-end suites.
• While fuzzing/parsing untrusted data, e.g., file formats, network protocols.
• On crash-heavy modules (parsers, codecs, crypto glue, JNI/FFI boundaries) where memory safety is paramount.

How to enable AddressSanitizer

Quick start (Clang or GCC)

# Build
clang++ -fsanitize=address -fno-omit-frame-pointer -g -O1 -o app_san main.cpp
# or
g++      -fsanitize=address -fno-omit-frame-pointer -g -O1 -o app_san main.cpp

# Run with helpful defaults
ASAN_OPTIONS=halt_on_error=1:strict_string_checks=1:detect_leaks=1 ./app_san

Flags explained

• -fsanitize=address — enable ASan
• -fno-omit-frame-pointer -g — better stack traces
• -O1 (or -O0) — keeps instrumentation simple and easier to map to lines
• ASAN_OPTIONS — runtime tuning (leak detection, halting on first error, etc.)

CMake

# CMakeLists.txt
option(ENABLE_ASAN "Build with AddressSanitizer" ON)

if (ENABLE_ASAN AND CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
  add_compile_options(-fsanitize=address -fno-omit-frame-pointer -g -O1)
  add_link_options(-fsanitize=address)
endif()

Make

CXXFLAGS += -fsanitize=address -fno-omit-frame-pointer -g -O1
LDFLAGS  += -fsanitize=address

Real-World Use Cases (and how ASan helps)

1. Image Parser Heap Overflow
   • Scenario: A PNG decoder reads width/height from the file, under-validates them, and writes past a heap buffer.
   • With ASan: First failing test triggers an out-of-bounds write report with call stacks for both the write and the allocation site. You fix the bounds check and add regression tests.
2. Use-After-Free in a Web Server
   • Scenario: Request object freed on one path but referenced later by a logger.
   • With ASan: The access to the freed pointer immediately faults with a use-after-free report. Quarantine ensures it crashes deterministically instead of “works on my machine.”
3. Stack Buffer Overflow in Protocol Handler
   • Scenario: A stack array sized on assumptions gets overrun by a longer header.
   • With ASan: Redzones around stack objects catch it as soon as the bad write occurs, pointing to the exact function and line.
4. Memory Leaks in CLI Tool
   • Scenario: Early returns skip frees.
   • With ASan + LeakSanitizer: Run tests; at exit, you get a leak summary with allocation stacks. You patch the code and verify the leak disappears.
5. Fuzzing Third-Party Libraries
   • Scenario: You integrate libFuzzer to stress a JSON library.
   • With ASan: Any corruptor input hitting memory issues produces actionable reports, turning “mysterious crashes” into clear bugs.

Integrating ASan into Your Software Development Process

1) Add a dedicated “sanitizer” build

• Create a separate build target/profile (e.g., Debug-ASAN).
• Compile everything you can with -fsanitize=address (apps, libs, tests).
• Keep symbols: -g -fno-omit-frame-pointer.

2) Run unit/integration tests under ASan

• In CI, add a job that builds with ASan and runs your full test suite.
• Fail the pipeline on any ASan report (halt_on_error=1).

3) Use helpful ASAN_OPTIONS (per target or globally)

Common choices:

ASAN_OPTIONS=\
detect_leaks=1:\
halt_on_error=1:\
strict_string_checks=1:\
alloc_dealloc_mismatch=1:\
detect_stack_use_after_return=1

(You can also keep a project-level .asanrc/env file for consistency.)

4) Symbolization & developer ergonomics

• Ensure llvm-symbolizer is installed (or available in your toolchain).
• Keep -g in your ASan builds; store dSYMs/PDBs where applicable.
• Teach the team to read ASan reports—share a short “How to read ASan output” page.

5) Handle third-party and system libraries

• Prefer source builds of dependencies with ASan enabled.
• If you must link against non-ASan binaries, test critical boundaries thoroughly and consider suppressions for known benign issues.

6) Combine with other sanitizers (where applicable)

• UBSan (undefined behavior), TSan (data races), MSan (uninitialized reads).
• Run them in separate builds; mixing TSan with others is generally not recommended.

7) Pre-release and nightly sweeps

• Run heavier test suites (fuzzers, long-running integration tests) nightly under ASan.
• Gate releases on “no sanitizer regressions.”

8) Production strategy

• Typically don’t run ASan in production (overhead + noisy reports).
• If necessary, use shadow deploys or limited canaries with low traffic and aggressive alerting.

Developer Tips & Troubleshooting

• Crashing in malloc/new interceptors? Ensure you link the sanitizer runtime last or use the compiler driver (don’t manually juggle libs).
• False positives from assembly or custom allocators? Add minimal suppressions and comments; also review for real bugs—ASan is usually right.
• Random hangs/timeouts under fuzzing? Start with smaller corpora and lower timeouts; increase gradually.
• Build system gotchas: Ensure both compile and link steps include -fsanitize=address.

FAQ

Q: Can I use ASan with C only?
Yes. It works great for C and C++ (and many C-compatible FFI layers).

Q: Does ASan slow everything too much?
For local and CI testing, the trade-off is almost always worth it. Typical overhead: ~1.5–2× CPU, ~2–3× RAM.

Q: Do I need to change my code?
Usually no. Compile/link with the flags and run. You might tweak build scripts or add suppressions for a few low-level spots.

A minimal “Starter Checklist”

• Add an ASan build target to your project (CMake/Make/Bazel).
• Ensure -g and -fno-omit-frame-pointer are on.
• Add a CI job that runs tests with ASAN_OPTIONS=halt_on_error=1:detect_leaks=1.
• Document how to read ASan reports and where symbol files live.
• Pair ASan with fuzzing on parsers/protocols.
• Gate releases on sanitizer-clean status.