rust-unsafe-block-auditor

0. BUILD     -> once: for t in unsafe_inventory safety_comments ub_patterns risky_calls ffi_and_globals; do
                  rustc -O --edition 2021 "$SKILL/scripts/$t.rs" -o "/tmp/$t"; done
1. INVENTORY -> /tmp/unsafe_inventory src/
                every unsafe block/fn/impl/trait/extern block with location, size, SAFETY status, risky ops
                then: /tmp/ub_patterns src/  /tmp/risky_calls src/  /tmp/ffi_and_globals src/  /tmp/safety_comments src/
2. AVOID     -> For each item: does a safe API do the same job? (table below) If yes, replace it.
3. CONTRACT  -> For what remains, write the invariant: `# Safety` on unsafe fn/trait (caller's duty),
                `// SAFETY:` on every block/impl (why the duty is met HERE). No proof -> needs-justification.
4. PROVE     -> Check each unsafe op against its preconditions (references/undefined-behavior-catalog.md):
                validity, alignment, initialisation, aliasing, lifetime, provenance, thread safety, unwinding.
                Ask: can SAFE code calling this API break the invariant? If yes -> unsound API.
5. CLASSIFY  -> sound | needs-justification | likely UB, with file:line and rule id (USxxx)
6. VERIFY    -> cargo +nightly miri test (also MIRIFLAGS=-Zmiri-tree-borrows), sanitizers for FFI,
                loom for atomics, cargo-fuzz for parsers; every scanner with --strict in CI

// Edition 2024 (MSRV 1.85). Crate root:
#![deny(unsafe_op_in_unsafe_fn)]
#![warn(clippy::undocumented_unsafe_blocks, clippy::multiple_unsafe_ops_per_block)]

/// Splits `values` into `[0, mid)` and `[mid, len)`. (std has `split_at_mut`; this is the textbook shape.)
pub fn split_halves(values: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) {
    let len = values.len();
    assert!(mid <= len, "mid {mid} > len {len}");
    let ptr = values.as_mut_ptr();
    // SAFETY: mid <= len (asserted above), so both ranges lie inside the one allocation of
    // `values`, are initialised, and do not overlap; both inherit the unique borrow of `values`.
    unsafe {
        (
            std::slice::from_raw_parts_mut(ptr, mid),
            std::slice::from_raw_parts_mut(ptr.add(mid), len - mid),
        )
    }
}

/// Reads the element at `i` without a bounds check.
///
/// # Safety
///
/// `i` must be less than `slice.len()`.
pub unsafe fn read_unchecked(slice: &[u64], i: usize) -> u64 {
    debug_assert!(i < slice.len());
    // SAFETY: the caller guarantees `i < slice.len()` (see `# Safety`).
    unsafe { *slice.get_unchecked(i) }
}

mod stack {
    use std::mem::MaybeUninit;

    pub struct Stack<T, const N: usize> {
        items: [MaybeUninit<T>; N], // invariant: items[..len] are initialised
        len: usize,                 // private: only this module can change it
    }

    impl<T, const N: usize> Stack<T, N> {
        pub const fn new() -> Self {
            Self { items: [const { MaybeUninit::uninit() }; N], len: 0 } // inline const: 1.79+
        }

        pub fn push(&mut self, v: T) -> Result<(), T> {
            let Some(slot) = self.items.get_mut(self.len) else {
                return Err(v); // full
            };
            slot.write(v);
            self.len += 1;
            Ok(())
        }

        pub fn pop(&mut self) -> Option<T> {
            self.len = self.len.checked_sub(1)?;
            // SAFETY: the slot at the old `len - 1` was initialised by `push`; len was
            // decremented first, so the value is moved out exactly once.
            Some(unsafe { self.items[self.len].assume_init_read() })
        }
    }

    impl<T, const N: usize> Drop for Stack<T, N> {
        fn drop(&mut self) {
            while self.pop().is_some() {}
        }
    }
}

use std::sync::atomic::{AtomicU64, Ordering};

unsafe extern "C" {
    pub safe fn abs(x: i32) -> i32;           // declared safe: callable without unsafe
    fn strlen(s: *const std::ffi::c_char) -> usize; // unqualified items stay unsafe to call
}

static REQUESTS: AtomicU64 = AtomicU64::new(0); // instead of `static mut REQUESTS: u64`

static mut SCRATCH: [u8; 64] = [0; 64];
pub fn scratch_ptr() -> *mut u8 {
    (&raw mut SCRATCH).cast::<u8>() // creating a raw pointer to a static mut is safe since 1.82
}

pub fn bump() -> u64 {
    REQUESTS.fetch_add(1, Ordering::Relaxed) + 1
}

pub fn len_of(s: &std::ffi::CStr) -> usize {
    // SAFETY: `s` is a valid NUL-terminated string borrowed for the duration of the call.
    unsafe { strlen(s.as_ptr()) }
}

rustup +nightly component add miri
cargo +nightly miri test                                   # Stacked Borrows (default)
MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test   # Tree Borrows model
MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
cargo +nightly miri test --target s390x-unknown-linux-gnu  # big-endian
RUSTFLAGS="-Zsanitizer=address" cargo +nightly test --target x86_64-unknown-linux-gnu
RUSTFLAGS="--cfg loom" cargo test --release --test loom_queue
cargo +nightly fuzz run parse_header -- -max_total_time=300
cargo geiger                                               # unsafe usage across the dependency tree
cargo clippy -- -W clippy::undocumented_unsafe_blocks -W clippy::missing_safety_doc

/tmp/unsafe_inventory src/                              # walk *.rs (skips target/, .git/)
/tmp/unsafe_inventory src/ffi.rs --json > unsafe.json   # machine-readable inventory
cat lib.rs | /tmp/ub_patterns -                         # stdin
/tmp/safety_comments src/ --strict --max-block-lines 20 # CI gate (exit 1 on findings)
/tmp/risky_calls src/ --select US012,US013 --ignore US022
/tmp/ffi_and_globals --list-rules                       # each scanner lists its rules with why and fix