Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sanitizers support

The Rust compiler contains support for following sanitizers:

  • AddressSanitizer, a faster memory error detector. It can detect out-of-bounds access to heap, stack, and globals, use after free, use after return, double free, invalid free, and memory leaks.
  • ControlFlowIntegrity, LLVM Control Flow Integrity (CFI), provides forward-edge control flow protection.
  • Hardware-assisted AddressSanitizer is similar to AddressSanitizer, but is based on partial hardware assistance.
  • KernelControlFlowIntegrity, LLVM Kernel Control Flow Integrity (KCFI), provides forward-edge control flow protection for operating system kernels.
  • LeakSanitizer, a run-time memory leak detector.
  • MemorySanitizer, a detector of uninitialized reads.
  • ThreadSanitizer, a fast data race detector.

How to use the sanitizers?

To enable a sanitizer, compile with -Z sanitizer=... option, where value is one of address, cfi, hwaddress, kcfi, leak, memory, or thread. For more details on how to use sanitizers, refer to the sanitizer flag in The Unstable Book.

How sanitizers are implemented in rustc

The implementation of sanitizers (except CFI) relies almost entirely on LLVM. The Rust compiler is an integration point for LLVM compile time instrumentation passes and runtime libraries. Highlight of the most important aspects of the implementation:

  • The sanitizer runtime libraries are part of the compiler-rt project, and will be built on supported targets when enabled in bootstrap.toml:

    build.sanitizers = true

    The runtimes are placed into target libdir.

  • During LLVM code generation, the functions intended for instrumentation are marked with an appropriate LLVM attribute: SanitizeAddress, SanitizeHWAddress, SanitizeMemory, or SanitizeThread. By default, all functions are instrumented, but this behaviour can be changed with #[sanitize(xyz = "on|off|<other>")].

  • The decision whether to perform instrumentation or not is possible only at a function granularity. In the cases were those decision differ between functions, it might be necessary to inhibit inlining, both at MIR level and LLVM level.

  • The LLVM IR generated by rustc is instrumented by dedicated LLVM passes, different for each sanitizer. Instrumentation passes are invoked after optimization passes.

  • When producing an executable, the sanitizer-specific runtime library is linked in. The libraries are searched for in the target libdir. First, the search is relative to the overridden system root, and subsequently, it is relative to the default system root. Fall-back to the default system root ensures that sanitizer runtimes remain available when using sysroot overrides constructed by cargo -Z build-std or xargo.

Testing sanitizers

Sanitizers are validated by code generation tests in tests/codegen-llvm/sanitize*.rs and end-to-end functional tests in tests/ui/sanitizer/ directory.

Testing sanitizer functionality requires the sanitizer runtimes (built when build.sanitizer = true in bootstrap.toml) and a target providing support for particular a sanitizer. When a sanitizer is unsupported on a given target, sanitizer tests will be ignored. This behaviour is controlled by compiletest needs-sanitizer-* directives.

Enabling a sanitizer on a new target

To enable a sanitizer on a new target which is already supported by LLVM:

  1. Include the sanitizer in the list of supported_sanitizers in the target definition. rustc --target .. -Zsanitizer=.. should now recognize the sanitizer as supported.
  2. Build the runtime for the target and include it in the libdir.
  3. Teach compiletest that your target now supports the sanitizer. Tests marked with needs-sanitizer-* should now run on the target.
  4. Run tests ./x test --force-rerun tests/ui/sanitize/ to verify.
  5. –enable-sanitizers in the CI configuration to build and distribute the sanitizer runtime as part of the release process.

Additional Information