cashd

Sanitizer Configuration for Cashd

This document explains how to properly configure and run sanitizers (AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer) with the cashd project. Corresponding suppression files are located in the sanitizers/suppressions directory.

[!CAUTION] Do not mix Address and Thread sanitizers - they are incompatible. Also, we don’t yet support MSVC sanitizers, so this is only for Clang/GCC builds.

• Sanitizer Configuration for Cashd
  • Building with Sanitizers
    • Summary
    • Build steps:
      • Install dependencies
  • Running Tests with Sanitizers
    • AddressSanitizer (ASAN)
    • ThreadSanitizer (TSan)
    • LeakSanitizer (LSan)
    • UndefinedBehaviorSanitizer (UBSan)
  • Suppression Files
    • asan.supp
    • lsan.supp
    • ubsan.supp
    • tsan.supp
    • sanitizer-ignorelist.txt
  • Troubleshooting
    • “ASAN is ignoring requested __asan_handle_no_return” warnings
    • Sanitizer Mismatch Errors
  • References

Building with Sanitizers

Summary

Follow the same instructions as mentioned in BUILD.md but with the following changes:

1. Make sure you have a clean build directory.
2. Set the SANITIZERS environment variable before calling conan install. Only set it once. Example: export SANITIZERS=address,undefinedbehavior

3. Use --profile:all sanitizers with Conan to build dependencies with sanitizer instrumentation.

   [!NOTE] Building with sanitizer-instrumented dependencies is slower but produces fewer false positives.

4. Set ASAN_OPTIONS, LSAN_OPTIONS, UBSAN_OPTIONS and TSAN_OPTIONS environment variables to configure sanitizer behavior when running executables. More details below.

---

Build steps:

cd /path/to/cashd
rm -rf .build
mkdir .build
cd .build

Install dependencies

The SANITIZERS environment variable is used during conan install command.

SANITIZERS=address,undefinedbehavior conan install .. --output-folder . --build missing --settings build_type=Debug --profile:all sanitizers

Proceed with the rest of the build instructions as mentioned in BUILD.md.

Running Tests with Sanitizers

AddressSanitizer (ASAN)

IMPORTANT: ASAN with Boost produces many false positives. Use these options:

export ASAN_OPTIONS="include=sanitizers/suppressions/runtime-asan-options.txt:suppressions=sanitizers/suppressions/asan.supp"
export LSAN_OPTIONS="include=sanitizers/suppressions/runtime-lsan-options.txt:suppressions=sanitizers/suppressions/lsan.supp"

# Run tests
./cashd --unittest --unittest-jobs=5

Why detect_container_overflow=0?

• Boost intrusive containers (used in AgedUnorderedContainer) trigger false positives
• Boost context switching (used in Workers.cpp) confuses ASAN’s stack tracking
• Since we usually don’t build Boost (because we don’t want to instrument Boost and detect issues in Boost code) with ASAN but use Boost containers in ASAN instrumented cashd code, it generates false positives.
• Building dependencies with ASAN instrumentation reduces false positives. But we don’t want to instrument dependencies like Boost with ASAN because it is slow (to compile as well as run tests) and not necessary.
• See: https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow
• More such flags are detailed here

ThreadSanitizer (TSan)

export TSAN_OPTIONS="include=sanitizers/suppressions/runtime-tsan-options.txt:suppressions=sanitizers/suppressions/tsan.supp"

# Run tests
./cashd --unittest --unittest-jobs=5

More details here.

LeakSanitizer (LSan)

LSan is automatically enabled with ASAN. To disable it:

export ASAN_OPTIONS="detect_leaks=0"

More details here.

UndefinedBehaviorSanitizer (UBSan)

export UBSAN_OPTIONS="include=sanitizers/suppressions/runtime-ubsan-options.txt:suppressions=sanitizers/suppressions/ubsan.supp"

# Run tests
./cashd --unittest --unittest-jobs=5

More details here.

Suppression Files

[!NOTE] Attached files contain more details.

asan.supp

• Purpose: Suppress AddressSanitizer (ASAN) errors only
• Format: interceptor_name:<pattern> where pattern matches file names. Supported suppression types are:
  • interceptor_name
  • interceptor_via_fun
  • interceptor_via_lib
  • odr_violation
• More info: AddressSanitizer
• Note: Cannot suppress stack-buffer-overflow, container-overflow, etc.

lsan.supp

• Purpose: Suppress LeakSanitizer (LSan) errors only
• Format: leak:<pattern> where pattern matches function/file names
• More info: LeakSanitizer

ubsan.supp

• Purpose: Suppress undefinedbehaviorSanitizer errors
• Format: <error_type>:<pattern> (e.g., unsigned-integer-overflow:protobuf)
• Covers: Intentional overflows in sanitizers/suppressions libraries (protobuf, gRPC, stdlib)
• More info UBSan suppressions.

tsan.supp

• Purpose: Suppress ThreadSanitizer data race warnings
• Format: race:<pattern> where pattern matches function/file names
• More info: ThreadSanitizer suppressions

sanitizer-ignorelist.txt

• Purpose: Compile-time ignorelist for all sanitizers
• Usage: Passed via -fsanitize-ignorelist=absolute/path/to/sanitizer-ignorelist.txt
• Format: <level>:<pattern> (e.g., src:Workers.cpp)

Troubleshooting

“ASAN is ignoring requested __asan_handle_no_return” warnings

These warnings appear when using Boost context switching and are harmless. They indicate potential false positives.

Sanitizer Mismatch Errors

If you see undefined symbols like ___tsan_atomic_load when building with ASAN:

Problem: Dependencies were built with a different sanitizer than the main project.

Solution: Rebuild everything with the same sanitizer:

rm -rf .build
# Then follow the build instructions above

Then review the log files: asan.log.*, ubsan.log.*, tsan.log.*

References

• AddressSanitizer Wiki
• AddressSanitizer Flags
• Container Overflow Detection
• UndefinedBehavior Sanitizer
• ThreadSanitizer

This site is open source. Improve this page.