1---2name: rust-sanitizers-miri3description: Use when running AddressSanitizer, ThreadSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer, or Miri on Rust code, interpreting sanitizer output, or validating unsafe code for undefined behaviour.4---56# Rust sanitizers and Miri78## Contract910| Field | Bound contract |11|---|---|12| Trigger | Rust code is being checked with a sanitizer or Miri, or a user asks how to run ASan, TSan, MSan, UBSan, or `cargo miri` on Rust. |13| Authority | Reversible local. Edits `Cargo.toml`, CI workflow files, or build directories only when the user asks; most uses are read-only guidance. Rollback is `git checkout` or removal of added files. No remote mutation. |14| Side effect | Chat guidance, command output, and optionally local build artifacts or CI files. |15| Done | The chosen sanitizer or Miri command runs and produces an interpretable result, or the report explains why the target cannot run. |1617## Inputs18191. **Tool** (required): ASan, TSan, MSan, UBSan, or Miri.202. **Target** (required): the crate, workspace, test, or binary to check.213. **Toolchain** (optional): nightly is required for Rust sanitizers and Miri.224. **CI context** (optional): GitHub Actions, GitLab CI, or a local runner.2324## Procedure25261. **Confirm the toolchain.** Run `rustup toolchain list` and `rustc +nightly --version`. Sanitizers and Miri require a nightly toolchain. Done when: nightly is selected, the user accepts installing it, or the missing toolchain is reported.272. **Choose the tool.** ASan for memory errors, TSan for data races, MSan for uninitialized reads, UBSan for language and integer UB, and Miri for interpretation-time UB detection in unsafe code. Done when: the tool matches the failure mode.283. **Run a sanitizer.** Set `RUSTFLAGS="-Z sanitizer=<tool>"` and run `cargo +nightly test -Zbuild-std --target <triple>`. For MSan add `-Z sanitizer-memory-track-origins`. Done when: the build completes and the sanitizer report appears.294. **Interpret sanitizer output.** Match the `ERROR: AddressSanitizer:`, `WARNING: ThreadSanitizer:`, or similar banner to the code path and the likely Rust cause. Done when: the report maps to a source line and a failure class.305. **Run Miri.** Install Miri with `rustup +nightly component add miri`, then run `cargo +nightly miri test` or `cargo +nightly miri run`. Miri interprets MIR and detects UB at interpretation time. Use `MIRIFLAGS="-Zmiri-strict-provenance"` for stricter pointer provenance and `MIRIFLAGS="-Zmiri-disable-isolation"` for host file I/O, clocks, or randomness. Done when: Miri reports UB or completes without error.316. **Configure CI.** Add a step that installs the nightly toolchain, adds the `rust-src` and `miri` components, and runs the chosen command. For ASan, set `RUSTFLAGS="-Z sanitizer=address"` and use `-Zbuild-std` with a `--target` triple. Done when: the CI file is valid and the command is reproducible.327. **Document findings.** Report each UB or sanitizer hit with the source location, the failure class, and a recommended fix. Done when: the report is complete.3334## Failure and recovery3536| Failure class | Behavior |37|---|---|38| Tool requires nightly | Install the nightly toolchain and the `rust-src` component, then retry. |39| Sanitizer fails to build | Check the target triple, `-Zbuild-std`, and the sanitizer compatibility for that target. |40| Miri reports an unsupported operation | Skip the test under Miri with `#[cfg(not(miri))]`, or stub the operation for Miri. |41| CI cannot fetch nightly | Pin a known-good nightly date and add it to the CI cache. |4243## Output44451. The sanitizer or Miri command and its output.462. A mapping of findings to source locations and failure classes.473. Recommended fixes for each finding.484. A CI snippet when CI was requested.495. Pointers to `references/miri-ub-patterns.md` for Miri-detected UB patterns and sanitizer comparison.
OutlineDriven