[ASan] Document define to disable container overflow checks at compile time. (#163468)

Document a define to allow library developers to support disabling 
AddressSanitizer's container overflow detection in template code at 
compile time.

The primary motivation is to reduce false positives in environments
where
libraries and frameworks that cannot be recompiled with sanitizers
enabled
are called from application code. This supports disabling checks when
the
runtime environment cannot be reliably controlled to use ASAN_OPTIONS.

Key changes:
- Use the define `__SANITIZER_DISABLE_CONTAINER_OVERFLOW__` to disable
  instrumentation at compile time
- Implemented redefining the container overflow APIs in
common_interface_defs.h
  to use define to provide null implementation when define is present
- Update documentation in AddressSanitizer.rst to suggest and illustrate
  use of the define
- Add details of the define in PrintContainerOverflowHint()
- Add test disable_container_overflow_checks to verify new hints on the
error and fill the testing gap that
ASAN_OPTIONS=detect_container_overflow=0
  works
- Add tests demonstrating the issue around closed source libraries and 
  instrumented apps that both modify containers

This requires no compiler changes and should be supportable cross
compiler toolchains.

An RFC has been opened to discuss: 

https://discourse.llvm.org/t/rfc-add-fsanitize-address-disable-container-overflow-flag-to-addresssanitizer/88349

Author: padriff

clang/docs/AddressSanitizer.rst

@@ -164,6 +164,18 @@ To summarize: ``-fsanitize-address-use-after-return=<mode>``
   * ``always``: Enables detection of UAR errors in all cases. (reduces code
     size, but not as much as ``never``).
 
+Container Overflow Detection
+----------------------------
+
+AddressSanitizer can detect overflows in containers with custom allocators
+(such as std::vector) where the library developers have added calls into the
+AddressSanitizer runtime to indicate which memory is poisoned etc.
+
+In environments where not all the process binaries can be recompiled with 
+AddressSanitizer enabled, these checks can cause false positives.
+
+See `Disabling container overflow checks`_ for details on suppressing checks.
+
 Memory leak detection
 ---------------------
 
@@ -242,6 +254,46 @@ AddressSanitizer also supports
 works similarly to ``__attribute__((no_sanitize("address")))``, but it also
 prevents instrumentation performed by other sanitizers.
 
+Disabling container overflow checks
+-----------------------------------
+
+Runtime suppression
+^^^^^^^^^^^^^^^^^^^
+
+Container overflow checks can be disabled at runtime using the
+``ASAN_OPTIONS=detect_container_overflow=0`` environment variable.
+
+Compile time suppression
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``-D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__`` can be used at compile time to
+disable container overflow checks if the container library has added support
+for this define.
+
+To support a standard way to disable container overflow checks at compile time,
+library developers should use this definition in conjunction with the 
+AddressSanitizer feature test to conditionally include container overflow 
+related code compiled into user code:
+
+The recommended form is
+
+.. code-block:: c
+
+    // include the sanitizer common interfaces
+    #include <sanitizer/common_interface_defs.h>
+
+    #if __has_feature(address_sanitizer)
+    // Container overflow detection enabled - include annotations
+    __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid);
+    #endif
+
+This pattern ensures that:
+
+* Container overflow annotations are only included when AddressSanitizer is
+  enabled
+* Container overflow detection can be disabled by passing 
+  ``-D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__`` to the compiler
+
 Suppressing Errors in Recompiled Code (Ignorelist)
 --------------------------------------------------
 

compiler-rt/include/sanitizer/common_interface_defs.h

@@ -156,8 +156,15 @@ int SANITIZER_CDECL __sanitizer_acquire_crash_state();
 /// \param end End of memory region.
 /// \param old_mid Old middle of memory region.
 /// \param new_mid New middle of memory region.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline void SANITIZER_CDECL
+__sanitizer_annotate_contiguous_container(const void *beg, const void *end,
+                                          const void *old_mid,
+                                          const void *new_mid) {}
+#else
 void SANITIZER_CDECL __sanitizer_annotate_contiguous_container(
     const void *beg, const void *end, const void *old_mid, const void *new_mid);
+#endif
 
 /// Similar to <c>__sanitizer_annotate_contiguous_container</c>.
 ///
@@ -188,10 +195,18 @@ void SANITIZER_CDECL __sanitizer_annotate_contiguous_container(
 /// \param old_container_end End of used region.
 /// \param new_container_beg New beginning of used region.
 /// \param new_container_end New end of used region.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline void
+    SANITIZER_CDECL __sanitizer_annotate_double_ended_contiguous_container(
+        const void *storage_beg, const void *storage_end,
+        const void *old_container_beg, const void *old_container_end,
+        const void *new_container_beg, const void *new_container_end) {}
+#else
 void SANITIZER_CDECL __sanitizer_annotate_double_ended_contiguous_container(
     const void *storage_beg, const void *storage_end,
     const void *old_container_beg, const void *old_container_end,
     const void *new_container_beg, const void *new_container_end);
+#endif
 
 /// Copies memory annotations from a source storage region to a destination
 /// storage region. After the operation, the destination region has the same
@@ -226,9 +241,17 @@ void SANITIZER_CDECL __sanitizer_annotate_double_ended_contiguous_container(
 /// \param src_end End of the source container region.
 /// \param dst_begin Begin of the destination container region.
 /// \param dst_end End of the destination container region.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline void SANITIZER_CDECL
+__sanitizer_copy_contiguous_container_annotations(const void *src_begin,
+                                                  const void *src_end,
+                                                  const void *dst_begin,
+                                                  const void *dst_end) {}
+#else
 void SANITIZER_CDECL __sanitizer_copy_contiguous_container_annotations(
     const void *src_begin, const void *src_end, const void *dst_begin,
     const void *dst_end);
+#endif
 
 /// Returns true if the contiguous container <c>[beg, end)</c> is properly
 /// poisoned.
@@ -246,9 +269,16 @@ void SANITIZER_CDECL __sanitizer_copy_contiguous_container_annotations(
 ///
 /// \returns True if the contiguous container <c>[beg, end)</c> is properly
 ///  poisoned.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline int
+    SANITIZER_CDECL __sanitizer_verify_contiguous_container(const void *beg,
+                                                            const void *mid,
+                                                            const void *end) {}
+#else
 int SANITIZER_CDECL __sanitizer_verify_contiguous_container(const void *beg,
                                                             const void *mid,
                                                             const void *end);
+#endif
 
 /// Returns true if the double ended contiguous
 /// container <c>[storage_beg, storage_end)</c> is properly poisoned.
@@ -271,9 +301,17 @@ int SANITIZER_CDECL __sanitizer_verify_contiguous_container(const void *beg,
 /// \returns True if the double-ended contiguous container <c>[storage_beg,
 /// container_beg, container_end, end)</c> is properly poisoned - only
 /// [container_beg; container_end) is addressable.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline int SANITIZER_CDECL
+__sanitizer_verify_double_ended_contiguous_container(const void *storage_beg,
+                                                     const void *container_beg,
+                                                     const void *container_end,
+                                                     const void *storage_end) {}
+#else
 int SANITIZER_CDECL __sanitizer_verify_double_ended_contiguous_container(
     const void *storage_beg, const void *container_beg,
     const void *container_end, const void *storage_end);
+#endif
 
 /// Similar to <c>__sanitizer_verify_contiguous_container()</c> but also
 /// returns the address of the first improperly poisoned byte.
@@ -285,8 +323,15 @@ int SANITIZER_CDECL __sanitizer_verify_double_ended_contiguous_container(
 /// \param end Old end of memory region.
 ///
 /// \returns The bad address or NULL.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline const void *SANITIZER_CDECL
+__sanitizer_contiguous_container_find_bad_address(const void *beg,
+                                                  const void *mid,
+                                                  const void *end) {}
+#else
 const void *SANITIZER_CDECL __sanitizer_contiguous_container_find_bad_address(
     const void *beg, const void *mid, const void *end);
+#endif
 
 /// returns the address of the first improperly poisoned byte.
 ///
@@ -298,10 +343,17 @@ const void *SANITIZER_CDECL __sanitizer_contiguous_container_find_bad_address(
 /// \param storage_end End of memory region.
 ///
 /// \returns The bad address or NULL.
+#ifdef __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+__attribute__((__internal_linkage__)) inline const void *SANITIZER_CDECL
+__sanitizer_double_ended_contiguous_container_find_bad_address(
+    const void *storage_beg, const void *container_beg,
+    const void *container_end, const void *storage_end) {}
+#else
 const void *SANITIZER_CDECL
 __sanitizer_double_ended_contiguous_container_find_bad_address(
     const void *storage_beg, const void *container_beg,
     const void *container_end, const void *storage_end);
+#endif
 
 /// Prints the stack trace leading to this call (useful for calling from the
 /// debugger).

compiler-rt/lib/asan/asan_errors.cpp

@@ -514,11 +514,15 @@ ErrorGeneric::ErrorGeneric(u32 tid, uptr pc_, uptr bp_, uptr sp_, uptr addr,
 }
 
 static void PrintContainerOverflowHint() {
-  Printf("HINT: if you don't care about these errors you may set "
-         "ASAN_OPTIONS=detect_container_overflow=0.\n"
-         "If you suspect a false positive see also: "
-         "https://github.com/google/sanitizers/wiki/"
-         "AddressSanitizerContainerOverflow.\n");
+  Printf(
+      "HINT: if you don't care about these errors you may set "
+      "ASAN_OPTIONS=detect_container_overflow=0.\n"
+      "Or if supported by the container library, pass "
+      "-D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ to the compiler to disable "
+      " instrumentation.\n"
+      "If you suspect a false positive see also: "
+      "https://github.com/google/sanitizers/wiki/"
+      "AddressSanitizerContainerOverflow.\n");
 }
 
 static void PrintShadowByte(InternalScopedString *str, const char *before,

compiler-rt/test/asan/TestCases/disable_container_overflow_checks.cpp

@@ -0,0 +1,50 @@
+// Test crash gives guidance on -D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ and
+// ASAN_OPTIONS=detect_container_overflow=0
+// RUN: %clangxx_asan -O %s -o %t
+// RUN: not %run %t 2>&1 | FileCheck --check-prefix=CHECK-CRASH %s
+//
+// Test overflow checks can be disabled at runtime with
+// ASAN_OPTIONS=detect_container_overflow=0
+// RUN: %env_asan_opts=detect_container_overflow=0 %run %t 2>&1 | FileCheck --check-prefix=CHECK-NOCRASH %s
+//
+// Illustrate use of -D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ flag to suppress
+// overflow checks at compile time.
+// RUN: %clangxx_asan -D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ -O %s -o %t-no-overflow
+// RUN: %run %t-no-overflow 2>&1 | FileCheck --check-prefix=CHECK-NOCRASH %s
+//
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+
+// public definition of __sanitizer_annotate_contiguous_container
+#include "sanitizer/common_interface_defs.h"
+
+static volatile int one = 1;
+
+int TestCrash() {
+  long t[100];
+  t[60] = 0;
+#if __has_feature(address_sanitizer)
+  __sanitizer_annotate_contiguous_container(&t[0], &t[0] + 100, &t[0] + 100,
+                                            &t[0] + 50);
+#endif
+  // CHECK-CRASH: AddressSanitizer: container-overflow
+  // CHECK-CRASH: ASAN_OPTIONS=detect_container_overflow=0
+  // CHECK-CRASH: __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+  // CHECK-NOCRASH-NOT: AddressSanitizer: container-overflow
+  // CHECK-NOCRASH-NOT: ASAN_OPTIONS=detect_container_overflow=0
+  // CHECK-NOCRASH-NOT: __SANITIZER_DISABLE_CONTAINER_OVERFLOW__
+  return (int)t[60 * one]; // Touches the poisoned memory.
+}
+
+int main(int argc, char **argv) {
+
+  int retval = 0;
+
+  retval = TestCrash();
+
+  printf("Exiting main\n");
+
+  return retval;
+}

compiler-rt/test/asan/TestCases/stack_container_dynamic_lib.cpp

@@ -0,0 +1,118 @@
+// Test to demonstrate compile-time disabling of container-overflow checks
+// in order to handle uninstrumented libraries
+// UNSUPPORTED: target={{.*windows-msvc.*}}
+
+// Mimic a closed-source library compiled without ASan
+// RUN: %clangxx_asan -fno-sanitize=address -DSHARED_LIB %s %fPIC -shared -o %t-so.so
+
+// Mimic multiple files being linked into a single executable,
+// %t-object.o and %t-main compiled seperately and then linked together
+// RUN: %clangxx_asan -DMULTI_SOURCE %s -c -o %t-object.o
+// RUN: %clangxx_asan %s -c -o %t-main.o
+// RUN: %clangxx_asan -o %t %t-main.o %t-object.o
+// RUN: not %run %t 2>&1 | FileCheck %s
+
+// Disable container overflow checks at runtime using ASAN_OPTIONS=detect_container_overflow=0
+// RUN: %env_asan_opts=detect_container_overflow=0 %run %t 2>&1 | FileCheck --check-prefix=CHECK-NO-CONTAINER-OVERFLOW %s
+
+// RUN: %clangxx_asan -D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ -DMULTI_SOURCE %s -c -o %t-object.o
+// RUN: %clangxx_asan -D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ %s -c -o %t-main.o
+// RUN: %clangxx_asan -D__SANITIZER_DISABLE_CONTAINER_OVERFLOW__ -o %t %t-main.o %t-object.o
+// RUN: %run %t 2>&1 | FileCheck --check-prefix=CHECK-NO-CONTAINER-OVERFLOW %s
+
+#include <assert.h>
+#include <sanitizer/common_interface_defs.h>
+#include <stdio.h>
+
+template <typename T> class Stack {
+private:
+  T data[5];
+  size_t size;
+
+public:
+  Stack() : size(0) {
+#if __has_feature(address_sanitizer) && !__ASAN_DISABLE_CONTAINER_OVERFLOW__
+    // Mark entire storage as unaddressable initially
+    __sanitizer_annotate_contiguous_container(data, data + 5, data + 5, data);
+#endif
+  }
+
+  ~Stack() {
+#if __has_feature(address_sanitizer) && !__ASAN_DISABLE_CONTAINER_OVERFLOW__
+    __sanitizer_annotate_contiguous_container(data, data + 5, data + size,
+                                              data + 5);
+#endif
+  }
+
+  void push(const T &value) {
+    assert(size < 5 && "Stack overflow");
+#if __has_feature(address_sanitizer) && !__ASAN_DISABLE_CONTAINER_OVERFLOW__
+    __sanitizer_annotate_contiguous_container(data, data + 5, data + size,
+                                              data + size + 1);
+#endif
+    data[size++] = value;
+  }
+
+  T pop() {
+    assert(size > 0 && "Cannot pop from empty stack");
+    T result = data[--size];
+#if __has_feature(address_sanitizer) && !__ASAN_DISABLE_CONTAINER_OVERFLOW__
+    __sanitizer_annotate_contiguous_container(data, data + 5, data + size + 1,
+                                              data + size);
+#endif
+    return result;
+  }
+};
+
+#ifdef SHARED_LIB
+// Mimics a closed-source library compiled without ASan
+
+extern "C" void push_value_to_stack(Stack<int> &stack) { stack.push(42); }
+#else // SHARED_LIB
+
+#  include <dlfcn.h>
+#  include <string>
+
+typedef void (*push_func_t)(Stack<int> &);
+
+#  if defined(MULTI_SOURCE)
+extern push_func_t push_value;
+
+extern "C" void do_push_value_to_stack(Stack<int> &stack) {
+  assert(push_value);
+  push_value(stack);
+}
+
+#  else
+push_func_t push_value = nullptr;
+
+extern "C" void do_push_value_to_stack(Stack<int> &stack);
+
+int main(int argc, char *argv[]) {
+  std::string path = std::string(argv[0]) + "-so.so";
+  printf("Loading library: %s\n", path.c_str());
+
+  void *lib = dlopen(path.c_str(), RTLD_NOW);
+  assert(lib);
+
+  push_value = (push_func_t)dlsym(lib, "push_value_to_stack");
+  assert(push_value);
+
+  Stack<int> stack;
+  do_push_value_to_stack(stack);
+
+  // BOOM! uninstrumented library didn't update container bounds
+  int value = stack.pop();
+  // CHECK: AddressSanitizer: container-overflow
+  printf("Popped value: %d\n", value);
+  assert(value == 42 && "Expected value 42");
+
+  dlclose(lib);
+  printf("SUCCESS\n");
+  // CHECK-NO-CONTAINER-OVERFLOW: SUCCESS
+  return 0;
+}
+
+#  endif // MULTI_SOURCE
+
+#endif // SHARED_LIB