1========================== 2UndefinedBehaviorSanitizer 3========================== 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector. 12UBSan modifies the program at compile-time to catch various kinds of undefined 13behavior during program execution, for example: 14 15* Array subscript out of bounds, where the bounds can be statically determined 16* Bitwise shifts that are out of bounds for their data type 17* Dereferencing misaligned or null pointers 18* Signed integer overflow 19* Conversion to, from, or between floating-point types which would 20 overflow the destination 21 22See the full list of available :ref:`checks <ubsan-checks>` below. 23 24UBSan has an optional run-time library which provides better error reporting. 25The checks have small runtime cost and no impact on address space layout or ABI. 26 27How to build 28============ 29 30Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_. 31 32Usage 33===== 34 35Use ``clang++`` to compile and link your program with ``-fsanitize=undefined`` 36flag. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your 37executable is linked with proper UBSan runtime libraries. You can use ``clang`` 38instead of ``clang++`` if you're compiling/linking C code. 39 40.. code-block:: console 41 42 % cat test.cc 43 int main(int argc, char **argv) { 44 int k = 0x7fffffff; 45 k += argc; 46 return 0; 47 } 48 % clang++ -fsanitize=undefined test.cc 49 % ./a.out 50 test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int' 51 52You can enable only a subset of :ref:`checks <ubsan-checks>` offered by UBSan, 53and define the desired behavior for each kind of check: 54 55* ``-fsanitize=...``: print a verbose error report and continue execution (default); 56* ``-fno-sanitize-recover=...``: print a verbose error report and exit the program; 57* ``-fsanitize-trap=...``: execute a trap instruction (doesn't require UBSan run-time support). 58* ``-fno-sanitize=...``: disable any check, e.g., -fno-sanitize=alignment. 59 60Note that the ``trap`` / ``recover`` options do not enable the corresponding 61sanitizer, and in general need to be accompanied by a suitable ``-fsanitize=`` 62flag. 63 64For example if you compile/link your program as: 65 66.. code-block:: console 67 68 % clang++ -fsanitize=signed-integer-overflow,null,alignment -fno-sanitize-recover=null -fsanitize-trap=alignment 69 70the program will continue execution after signed integer overflows, exit after 71the first invalid use of a null pointer, and trap after the first use of misaligned 72pointer. 73 74.. _ubsan-checks: 75 76Available checks 77================ 78 79Available checks are: 80 81 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation 82 of a misaligned reference. Also sanitizes assume_aligned-like attributes. 83 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither 84 ``true`` nor ``false``. 85 - ``-fsanitize=builtin``: Passing invalid values to compiler builtins. 86 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases 87 where the array bound can be statically determined. The check includes 88 ``-fsanitize=array-bounds`` and ``-fsanitize=local-bounds``. Note that 89 ``-fsanitize=local-bounds`` is not included in ``-fsanitize=undefined``. 90 - ``-fsanitize=enum``: Load of a value of an enumerated type which 91 is not in the range of representable values for that enumerated 92 type. 93 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or 94 between floating-point types which would overflow the 95 destination. Because the range of representable values for all 96 floating-point types supported by Clang is [-inf, +inf], the only 97 cases detected are conversions from floating point to integer types. 98 - ``-fsanitize=float-divide-by-zero``: Floating point division by 99 zero. This is undefined per the C and C++ standards, but is defined 100 by Clang (and by ISO/IEC/IEEE 60559 / IEEE 754) as producing either an 101 infinity or NaN value, so is not included in ``-fsanitize=undefined``. 102 - ``-fsanitize=function``: Indirect call of a function through a 103 function pointer of the wrong type (Darwin/Linux, C++ and x86/x86_64 104 only). 105 - ``-fsanitize=implicit-unsigned-integer-truncation``, 106 ``-fsanitize=implicit-signed-integer-truncation``: Implicit conversion from 107 integer of larger bit width to smaller bit width, if that results in data 108 loss. That is, if the demoted value, after casting back to the original 109 width, is not equal to the original value before the downcast. 110 The ``-fsanitize=implicit-unsigned-integer-truncation`` handles conversions 111 between two ``unsigned`` types, while 112 ``-fsanitize=implicit-signed-integer-truncation`` handles the rest of the 113 conversions - when either one, or both of the types are signed. 114 Issues caught by these sanitizers are not undefined behavior, 115 but are often unintentional. 116 - ``-fsanitize=implicit-integer-sign-change``: Implicit conversion between 117 integer types, if that changes the sign of the value. That is, if the 118 original value was negative and the new value is positive (or zero), 119 or the original value was positive, and the new value is negative. 120 Issues caught by this sanitizer are not undefined behavior, 121 but are often unintentional. 122 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. 123 - ``-fsanitize=nonnull-attribute``: Passing null pointer as a function 124 parameter which is declared to never be null. 125 - ``-fsanitize=null``: Use of a null pointer or creation of a null 126 reference. 127 - ``-fsanitize=nullability-arg``: Passing null as a function parameter 128 which is annotated with ``_Nonnull``. 129 - ``-fsanitize=nullability-assign``: Assigning null to an lvalue which 130 is annotated with ``_Nonnull``. 131 - ``-fsanitize=nullability-return``: Returning null from a function with 132 a return type annotated with ``_Nonnull``. 133 - ``-fsanitize=objc-cast``: Invalid implicit cast of an ObjC object pointer 134 to an incompatible type. This is often unintentional, but is not undefined 135 behavior, therefore the check is not a part of the ``undefined`` group. 136 Currently only supported on Darwin. 137 - ``-fsanitize=object-size``: An attempt to potentially use bytes which 138 the optimizer can determine are not part of the object being accessed. 139 This will also detect some types of undefined behavior that may not 140 directly access memory, but are provably incorrect given the size of 141 the objects involved, such as invalid downcasts and calling methods on 142 invalid pointers. These checks are made in terms of 143 ``__builtin_object_size``, and consequently may be able to detect more 144 problems at higher optimization levels. 145 - ``-fsanitize=pointer-overflow``: Performing pointer arithmetic which 146 overflows, or where either the old or new pointer value is a null pointer 147 (or in C, when they both are). 148 - ``-fsanitize=return``: In C++, reaching the end of a 149 value-returning function without returning a value. 150 - ``-fsanitize=returns-nonnull-attribute``: Returning null pointer 151 from a function which is declared to never return null. 152 - ``-fsanitize=shift``: Shift operators where the amount shifted is 153 greater or equal to the promoted bit-width of the left hand side 154 or less than zero, or where the left hand side is negative. For a 155 signed left shift, also checks for signed overflow in C, and for 156 unsigned overflow in C++. You can use ``-fsanitize=shift-base`` or 157 ``-fsanitize=shift-exponent`` to check only left-hand side or 158 right-hand side of shift operation, respectively. 159 - ``-fsanitize=unsigned-shift-base``: check that an unsigned left-hand side of 160 a left shift operation doesn't overflow. 161 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow, where the 162 result of a signed integer computation cannot be represented in its type. 163 This includes all the checks covered by ``-ftrapv``, as well as checks for 164 signed division overflow (``INT_MIN/-1``), but not checks for 165 lossy implicit conversions performed before the computation 166 (see ``-fsanitize=implicit-conversion``). Both of these two issues are 167 handled by ``-fsanitize=implicit-conversion`` group of checks. 168 - ``-fsanitize=unreachable``: If control flow reaches an unreachable 169 program point. 170 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer overflow, where 171 the result of an unsigned integer computation cannot be represented in its 172 type. Unlike signed integer overflow, this is not undefined behavior, but 173 it is often unintentional. This sanitizer does not check for lossy implicit 174 conversions performed before such a computation 175 (see ``-fsanitize=implicit-conversion``). 176 - ``-fsanitize=vla-bound``: A variable-length array whose bound 177 does not evaluate to a positive value. 178 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that it is of 179 the wrong dynamic type, or that its lifetime has not begun or has ended. 180 Incompatible with ``-fno-rtti``. Link must be performed by ``clang++``, not 181 ``clang``, to make sure C++-specific parts of the runtime library and C++ 182 standard libraries are present. 183 184You can also use the following check groups: 185 - ``-fsanitize=undefined``: All of the checks listed above other than 186 ``float-divide-by-zero``, ``unsigned-integer-overflow``, 187 ``implicit-conversion``, ``local-bounds`` and the ``nullability-*`` group 188 of checks. 189 - ``-fsanitize=undefined-trap``: Deprecated alias of 190 ``-fsanitize=undefined``. 191 - ``-fsanitize=implicit-integer-truncation``: Catches lossy integral 192 conversions. Enables ``implicit-signed-integer-truncation`` and 193 ``implicit-unsigned-integer-truncation``. 194 - ``-fsanitize=implicit-integer-arithmetic-value-change``: Catches implicit 195 conversions that change the arithmetic value of the integer. Enables 196 ``implicit-signed-integer-truncation`` and ``implicit-integer-sign-change``. 197 - ``-fsanitize=implicit-conversion``: Checks for suspicious 198 behavior of implicit conversions. Enables 199 ``implicit-unsigned-integer-truncation``, 200 ``implicit-signed-integer-truncation``, and 201 ``implicit-integer-sign-change``. 202 - ``-fsanitize=integer``: Checks for undefined or suspicious integer 203 behavior (e.g. unsigned integer overflow). 204 Enables ``signed-integer-overflow``, ``unsigned-integer-overflow``, 205 ``shift``, ``integer-divide-by-zero``, 206 ``implicit-unsigned-integer-truncation``, 207 ``implicit-signed-integer-truncation``, and 208 ``implicit-integer-sign-change``. 209 - ``-fsanitize=nullability``: Enables ``nullability-arg``, 210 ``nullability-assign``, and ``nullability-return``. While violating 211 nullability does not have undefined behavior, it is often unintentional, 212 so UBSan offers to catch it. 213 214Volatile 215-------- 216 217The ``null``, ``alignment``, ``object-size``, ``local-bounds``, and ``vptr`` checks do not apply 218to pointers to types with the ``volatile`` qualifier. 219 220Minimal Runtime 221=============== 222 223There is a minimal UBSan runtime available suitable for use in production 224environments. This runtime has a small attack surface. It only provides very 225basic issue logging and deduplication, and does not support 226``-fsanitize=function`` and ``-fsanitize=vptr`` checking. 227 228To use the minimal runtime, add ``-fsanitize-minimal-runtime`` to the clang 229command line options. For example, if you're used to compiling with 230``-fsanitize=undefined``, you could enable the minimal runtime with 231``-fsanitize=undefined -fsanitize-minimal-runtime``. 232 233Stack traces and report symbolization 234===================================== 235If you want UBSan to print symbolized stack trace for each error report, you 236will need to: 237 238#. Compile with ``-g`` and ``-fno-omit-frame-pointer`` to get proper debug 239 information in your binary. 240#. Run your program with environment variable 241 ``UBSAN_OPTIONS=print_stacktrace=1``. 242#. Make sure ``llvm-symbolizer`` binary is in ``PATH``. 243 244Logging 245======= 246 247The default log file for diagnostics is "stderr". To log diagnostics to another 248file, you can set ``UBSAN_OPTIONS=log_path=...``. 249 250Silencing Unsigned Integer Overflow 251=================================== 252To silence reports from unsigned integer overflow, you can set 253``UBSAN_OPTIONS=silence_unsigned_overflow=1``. This feature, combined with 254``-fsanitize-recover=unsigned-integer-overflow``, is particularly useful for 255providing fuzzing signal without blowing up logs. 256 257Issue Suppression 258================= 259 260UndefinedBehaviorSanitizer is not expected to produce false positives. 261If you see one, look again; most likely it is a true positive! 262 263Disabling Instrumentation with ``__attribute__((no_sanitize("undefined")))`` 264---------------------------------------------------------------------------- 265 266You disable UBSan checks for particular functions with 267``__attribute__((no_sanitize("undefined")))``. You can use all values of 268``-fsanitize=`` flag in this attribute, e.g. if your function deliberately 269contains possible signed integer overflow, you can use 270``__attribute__((no_sanitize("signed-integer-overflow")))``. 271 272This attribute may not be 273supported by other compilers, so consider using it together with 274``#if defined(__clang__)``. 275 276Suppressing Errors in Recompiled Code (Ignorelist) 277-------------------------------------------------- 278 279UndefinedBehaviorSanitizer supports ``src`` and ``fun`` entity types in 280:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports 281in the specified source files or functions. 282 283Runtime suppressions 284-------------------- 285 286Sometimes you can suppress UBSan error reports for specific files, functions, 287or libraries without recompiling the code. You need to pass a path to 288suppression file in a ``UBSAN_OPTIONS`` environment variable. 289 290.. code-block:: bash 291 292 UBSAN_OPTIONS=suppressions=MyUBSan.supp 293 294You need to specify a :ref:`check <ubsan-checks>` you are suppressing and the 295bug location. For example: 296 297.. code-block:: bash 298 299 signed-integer-overflow:file-with-known-overflow.cpp 300 alignment:function_doing_unaligned_access 301 vptr:shared_object_with_vptr_failures.so 302 303There are several limitations: 304 305* Sometimes your binary must have enough debug info and/or symbol table, so 306 that the runtime could figure out source file or function name to match 307 against the suppression. 308* It is only possible to suppress recoverable checks. For the example above, 309 you can additionally pass 310 ``-fsanitize-recover=signed-integer-overflow,alignment,vptr``, although 311 most of UBSan checks are recoverable by default. 312* Check groups (like ``undefined``) can't be used in suppressions file, only 313 fine-grained checks are supported. 314 315Supported Platforms 316=================== 317 318UndefinedBehaviorSanitizer is supported on the following operating systems: 319 320* Android 321* Linux 322* NetBSD 323* FreeBSD 324* OpenBSD 325* macOS 326* Windows 327 328The runtime library is relatively portable and platform independent. If the OS 329you need is not listed above, UndefinedBehaviorSanitizer may already work for 330it, or could be made to work with a minor porting effort. 331 332Current Status 333============== 334 335UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM 3363.3. The test suite is integrated into the CMake build and can be run with 337``check-ubsan`` command. 338 339Additional Configuration 340======================== 341 342UndefinedBehaviorSanitizer adds static check data for each check unless it is 343in trap mode. This check data includes the full file name. The option 344``-fsanitize-undefined-strip-path-components=N`` can be used to trim this 345information. If ``N`` is positive, file information emitted by 346UndefinedBehaviorSanitizer will drop the first ``N`` components from the file 347path. If ``N`` is negative, the last ``N`` components will be kept. 348 349Example 350------- 351 352For a file called ``/code/library/file.cpp``, here is what would be emitted: 353 354* Default (No flag, or ``-fsanitize-undefined-strip-path-components=0``): ``/code/library/file.cpp`` 355* ``-fsanitize-undefined-strip-path-components=1``: ``code/library/file.cpp`` 356* ``-fsanitize-undefined-strip-path-components=2``: ``library/file.cpp`` 357* ``-fsanitize-undefined-strip-path-components=-1``: ``file.cpp`` 358* ``-fsanitize-undefined-strip-path-components=-2``: ``library/file.cpp`` 359 360More Information 361================ 362 363* From Oracle blog, including a discussion of error messages: 364 `Improving Application Security with UndefinedBehaviorSanitizer (UBSan) and GCC 365 <https://blogs.oracle.com/linux/improving-application-security-with-undefinedbehaviorsanitizer-ubsan-and-gcc>`_ 366* From LLVM project blog: 367 `What Every C Programmer Should Know About Undefined Behavior 368 <http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html>`_ 369* From John Regehr's *Embedded in Academia* blog: 370 `A Guide to Undefined Behavior in C and C++ 371 <https://blog.regehr.org/archives/213>`_ 372