Polish Rust chapter prose

Author: elopez

.github/workflows/markdown.yml

@@ -48,7 +48,7 @@ jobs:
         persist-credentials: false
     - uses: tbroadley/spellchecker-cli-action@8369e98753c0d2c3a3c76fb4519d9056d1d4b129 # v1
       with:
-        # No need to use a dictionary file with the disabled spell plugin 
+        # No need to use a dictionary file with the disabled spell plugin
         # dictionaries: '.github/workflows/dictionary.txt'
         files: "'content/**/*.md'"
         quiet: true

content/docs/languages/rust/10-security-overview.md

@@ -49,11 +49,11 @@ There’s more. Some safe (defined) behavior may result in vulnerabilities. The
 
 * [General race conditions](https://doc.rust-lang.org/nomicon/races.html)
   * Deadlocks (blocking bugs)
-  * Incorrect state synchronization (non-blocking bugs)  
-* Resource leaks  
-* Pointer exposures  
-* Arithmetic errors  
-* Nondeterminism  
+  * Incorrect state synchronization (non-blocking bugs)
+* Resource leaks
+* Pointer exposures
+* Arithmetic errors
+* Nondeterminism
 * Logic errors
 
 Moreover, safe Rust may happen to be unsound in some rare cases. Check [the issues on the Rust GitHub](https://github.com/rust-lang/rust/issues?q=is%3Aissue%20state%3Aopen%20label%3AI-unsound) and the ["Counterexamples in Type Systems"](https://counterexamples.org/intro.html) resource for more information. Usually auditors don’t need to focus on these edge cases.
@@ -76,8 +76,8 @@ Pointer exposure is considered safe, because it does not make your program explo
 
 Dealing with numbers is safe in Rust, but some operations may produce unexpected results. There are three main sources of bugs:
 
-* [Integer overflows](https://doc.rust-lang.org/reference/expressions/operator-expr.html#overflow)  
-* [Imprecision of float operations](https://seclists.org/oss-sec/2023/q2/99)  
+* [Integer overflows](https://doc.rust-lang.org/reference/expressions/operator-expr.html#overflow)
+* [Imprecision of float operations](https://seclists.org/oss-sec/2023/q2/99)
 * [Rounding errors](https://github.com/crytic/roundme)
 
 There are [three types of integer bugs](https://phrack.org/issues/60/10.html#article): arithmetic overflows, width overflows, and signedness errors.
@@ -100,7 +100,7 @@ You can read more about integer overflows in [RFC 560](https://github.com/rust-l
 
 Width and signedness overflows can occur when converting between numeric types. Thanks to Rust’s lack of implicit conversions, unexpected overflows are easy to deal with, using one of the following:
 
-* A [checked conversion](https://doc.rust-lang.org/std/convert/trait.TryFrom.html) with overflows handled explicitly (e.g., with a panic)  
+* A [checked conversion](https://doc.rust-lang.org/std/convert/trait.TryFrom.html) with overflows handled explicitly (e.g., with a panic)
 * An [`as` cast](https://doc.rust-lang.org/rust-by-example/types/cast.html) that may result in a wrap-over (but is always well defined, [unlike in C](https://stackoverflow.com/questions/16188263/is-signed-integer-overflow-still-undefined-behavior-in-c))
 
 The latter cast method is more error-prone and should get the same amount of scrutiny as arithmetic overflows. An [`as` cast](https://doc.rust-lang.org/rust-by-example/types/cast.html) silently truncates bigger integer types converted to smaller integer types, even in debug mode.
@@ -113,16 +113,16 @@ There are two types of nondeterminism in Rust: introduced during compilation and
 
 The following are sources of compilation-time nondeterminism:
 
-* Architecture-dependent integral types (like `usize` and `libc::c_char`) and pointer sizes  
-* [Float numbers](https://internals.rust-lang.org/t/pre-rfc-dealing-with-broken-floating-point/2673)  
-* [NaN bit representation](https://github.com/rust-lang/rfcs/blob/master/text/3514-float-semantics.md)  
-* Struct field reordering  
+* Architecture-dependent integral types (like `usize` and `libc::c_char`) and pointer sizes
+* [Float numbers](https://internals.rust-lang.org/t/pre-rfc-dealing-with-broken-floating-point/2673)
+* [NaN bit representation](https://github.com/rust-lang/rfcs/blob/master/text/3514-float-semantics.md)
+* Struct field reordering
 * Enum discriminant values
 
 The following are sources of runtime nondeterminism:
 
-* Iterations over [`HashMap`](https://dev.to/gnunicorn/hunting-down-a-non-determinism-bug-in-our-rust-wasm-build-4fk1) and `HashSet`  
-* Struct padding  
+* Iterations over [`HashMap`](https://dev.to/gnunicorn/hunting-down-a-non-determinism-bug-in-our-rust-wasm-build-4fk1) and `HashSet`
+* Struct padding
 * Pointers (specific memory addresses)
 
 ## Logic errors

content/docs/languages/rust/20-dynamic-analysis.md

@@ -244,13 +244,15 @@ To find deep bugs, we can run tests with [various sanitizers](https://doc.rust-l
 
 Examples of Rust sanitizers commonly used for security testing include:
 
-* AddressSanitizer  
-* HWAddressSanitizer  
-* LeakSanitizer  
-* MemorySanitizer  
+* AddressSanitizer
+* HWAddressSanitizer
+* LeakSanitizer
+* MemorySanitizer
 * ThreadSanitizer
 
-To enable them, add the `RUSTFLAGS` environment variable.
+To enable them, set the `RUSTFLAGS` environment variable.
+
+The examples below run the subset supported by the shown `x86_64-unknown-linux-gnu` target. Sanitizers are target-specific, so adjust the sanitizer name and target triple for others like HWAddressSanitizer.
 
 {{< hint warning >}}
 At this time, nightly toolchains must be used for sanitizers. If you use the stable toolchain, the compilation fails with the following error:
@@ -334,13 +336,13 @@ mod tests {
 
 ## Miri
 
-[Miri](https://github.com/rust-lang/miri) is an interpreter for Rust’s "mid-level intermediate representation." Miri helps to detect undefined behaviors like these:
+[Miri](https://github.com/rust-lang/miri) is an interpreter for Rust’s "mid-level intermediate representation." Miri helps detect undefined behavior and related issues like these:
 
-* Memory corruption bugs  
-* Memory leaks  
-* Uses of uninitialized data  
-* Memory alignment issues  
-* Issues with aliasing  
+* Memory corruption bugs
+* Memory leaks
+* Uses of uninitialized data
+* Memory alignment issues
+* Issues with aliasing
 * Data races
 
 To use Miri, you must point it at some executable code (it performs dynamic analysis). The easiest is to run your tests through Miri. Note that the nightly toolchain is required.
@@ -460,7 +462,7 @@ Keep these tips in mind while using Miri:
 
 {{< details "Example to try: Miri in action" >}}
 
-The test below should pass or fail on the assertion. Miri would detect undefined behavior.
+The test below may pass or fail normally, but Miri should report undefined behavior.
 
 ```rust
 fn main() { println!("Hello, world!"); }
@@ -509,17 +511,17 @@ To use proptest, you must write unit tests. But instead of hard-coding values th
 
 Proptest ships with many [configurable strategies](https://docs.rs/proptest/latest/proptest/):
 
-* Range-like generator for integers  
-* Regex generator for strings  
-* Simple generators for `bit`, `bool`, and `char` values  
-* Random-size generators for `std::collections`  
+* Range-like generator for integers
+* Regex generator for strings
+* Simple generators for `bit`, `bool`, and `char` values
+* Random-size generators for `std::collections`
 * Generators for `Option` and `Result`
 
 The generators [can be combined together](https://proptest-rs.github.io/proptest/proptest/tutorial/macro-prop-compose.html). You can also use the following `Strategy` methods and the `prop_oneof!` macro to further combine and restrict generation:
 
-* Do mapping with the `prop_map` method  
-* Do filtering with the `prop_filter` method  
-* Create enums with the `prop_oneof!` macro  
+* Do mapping with the `prop_map` method
+* Do filtering with the `prop_filter` method
+* Create enums with the `prop_oneof!` macro
 * Do recursion with the `prop_recursive` method
 
 Let’s see some example code:
@@ -608,13 +610,13 @@ cargo +nightly miri test
 
 {{< /hint >}}
 
-Finally, use our [`property-based-testing`](https://github.com/trailofbits/skills/tree/main/plugins/property-based-testing) Claude skill to automate the testing.
+Finally, use our [`property-based-testing`](https://github.com/trailofbits/skills/tree/main/plugins/property-based-testing) skill to automate the testing.
 
 ## Coverage
 
 It is critically important to know how much coverage your tests have. Coverage gathering consists of four steps:
 
-* Compile-time instrumentation  
+* Compile-time instrumentation
 * Execution of tests, producing "raw" data
 * Merge of per-execution run results
 * Conversion of merged data to a usable format (like an HTML report)
@@ -680,7 +682,7 @@ While checking coverage statistics from a command line and using one of many cov
 | HTML output/tool | `grcov` | `llvm-cov` | `tarpaulin` |
 | :---- | :---- | :---- | :---- |
 | Examples | [Open `grcov`]({{% staticref "/languages/rust/coverage/grcov_llvm/" %}}) [Open `grcov` with `lcov`]({{% staticref "/languages/rust/coverage/grcov_llvm_lcov/" %}}) | [Open `llvm-cov`]({{% staticref "/languages/rust/coverage/llvm_cov/" %}}) [Open `llvm-cov-pretty`]({{% staticref "/languages/rust/coverage/llvm_cov_pretty/" %}}) | [Open `tarpaulin`]({{% staticref "/languages/rust/coverage/tarpaulin-report.html" %}}) |
-| Handles Rust’s constructions? | Yes | Yes | Yes |
+| Handles Rust constructs? | Yes | Yes | Yes |
 | Expands Rust’s generics? | No | `--show-instantiations` | No |
 | Includes number of hits? | Yes | Yes | Yes |
 | Supports multi-file output? | Yes | Yes | No |
@@ -730,11 +732,11 @@ While checking coverage statistics from a command line and using one of many cov
 
 These are our general recommendations for generating test coverage:
 
-* Use `llvm-cov` (with [`llvm-cov-pretty`](https://crates.io/crates/llvm-cov-pretty)) for rapid testing. It is the easiest to run, it resolves generics, and it produces pretty HTML output.  
-* Use either `llvm-cov` or `grcov` for complex projects. Both are decent and can produce readable outputs.  
-* Use `tarpaulin` when other tools work incorrectly. [The developers claim](https://github.com/xd009642/tarpaulin?tab=readme-ov-file#nuances-with-llvm-coverage) that this can happen in the event of the following:  
-  * The code panics unexpectedly.  
-  * There are race conditions.  
+* Use `llvm-cov` (with [`llvm-cov-pretty`](https://crates.io/crates/llvm-cov-pretty)) for rapid testing. It is the easiest to run, it resolves generics, and it produces pretty HTML output.
+* Use either `llvm-cov` or `grcov` for complex projects. Both are decent and can produce readable outputs.
+* Use `tarpaulin` when other tools work incorrectly. [The developers claim](https://github.com/xd009642/tarpaulin?tab=readme-ov-file#nuances-with-llvm-coverage) that this can happen in the event of the following:
+  * The code panics unexpectedly.
+  * There are race conditions.
   * The code forks.
 
 For profiling, consider using [`measureme`](https://github.com/rust-lang/measureme), possibly with [Miri and Chrome DevTools](https://medium.com/source-and-buggy/data-driven-performance-optimization-with-rust-and-miri-70cb6dde0d35).
@@ -756,16 +758,16 @@ For starters, you need basic but decent unit test coverage. Then, use one of the
 
 [`cargo-mutants`](https://mutants.rs/welcome.html)
 
-* Easy to use  
-* Parses the AST of every file with the [`syn` library](https://docs.rs/syn/latest/syn/)  
-* Partially type-aware  
+* Easy to use
+* Parses the AST of every file with the [`syn` library](https://docs.rs/syn/latest/syn/)
+* Partially type-aware
 * Can [divide jobs](https://mutants.rs/shards.html) between multiple machines
 
 [`universalmutator`](https://github.com/agroce/universalmutator)
 
-* Multiple languages supported  
-* Requires more manual setup than `cargo-mutants`  
-* Two parsing modes: regexes and [Comby](https://github.com/comby-tools/comby)  
+* Multiple languages supported
+* Requires more manual setup than `cargo-mutants`
+* Two parsing modes: regexes and [Comby](https://github.com/comby-tools/comby)
 * Trivial Compiler Equivalence (TCE) optimization to eliminate redundant mutants before test runs
 
 ### Bugs in existing tests
@@ -833,6 +835,6 @@ The tool produces a `necessist.db` file that can be used to resume an interrupte
 
 ## Resources
 
-* ["The Rust Programming Language," chapter 11: Testing](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/second-edition/ch11-00-testing.html): The basics of unit and integration testing in Rust  
-* [Ed Page’s "Iterating on Testing in Rust"](https://epage.github.io/blog/2023/06/iterating-on-test/): Lists potential issues with `cargo` `test` and introduces `cargo-nextest`  
+* ["The Rust Programming Language," chapter 11: Testing](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/second-edition/ch11-00-testing.html): The basics of unit and integration testing in Rust
+* [Ed Page’s "Iterating on Testing in Rust"](https://epage.github.io/blog/2023/06/iterating-on-test/): Lists potential issues with `cargo` `test` and introduces `cargo-nextest`
 * [Unsafe Rust and Miri by Ralf Jung \- Rust Zürisee June 2023](https://www.youtube.com/watch?v=svR0p6fSUYY)

content/docs/languages/rust/30-static-analysis.md

@@ -14,8 +14,8 @@ Clippy is the fundamental linter. Just use it.
 
 [Clippy lints](https://rust-lang.github.io/rust-clippy/master/index.html) are categorized into groups and levels. Groups categorize lints by the types of issues they detect. Levels indicate what to do when a lint finds an issue:
 
-* Allow: Ignore the issue  
-* Warn: Print a message to stderr  
+* Allow: Ignore the issue
+* Warn: Print a message to stderr
 * Deny: Return an error code (useful in CI pipelines)
 
 Clippy is a wrapper over the `rustc` compiler, so when Clippy is run, it executes [its own set of lints](https://doc.rust-lang.org/rustc/lints/listing/index.html) in addition to `rustc`’s. These lints are similarly categorized and can be controlled with the same flags and configuration options.
@@ -75,10 +75,10 @@ cargo clippy --message-format=json | clippy-sarif
 
 For continuous use, such as in a CI/CD pipeline, you want to minimize false positives and focus on the important lints. For that, follow these guidelines:
 
-* Use the default Clippy configuration.  
-* Enable recommended `clippy::restriction` lints (see the example below).  
-* Enable selected lints from `clippy::pedantic` groups (these should be enabled case by case depending on your project).  
-* Turn warnings into errors so that CI/CD fails on any issue.  
+* Use the default Clippy configuration.
+* Enable recommended `clippy::restriction` lints (see the example below).
+* Enable selected lints from `clippy::pedantic` groups (these should be enabled case by case depending on your project).
+* Turn warnings into errors so that CI/CD fails on any issue.
 * Add `#[allow(..)]` attributes in the code to silence specific findings of enabled lints when really needed. Make sure to comment why the lint was disabled in the specific location.
 
 ```sh
@@ -106,9 +106,9 @@ allow-unwrap-in-tests = true
 
 [Dylint](https://github.com/trailofbits/dylint) runs lints from dynamic libraries named by the user, allowing developers to maintain their own personal lint collections. While you could write new Clippy lints and send a pull request, this is not always an ideal solution:
 
-* The new lints cannot be project-specific.  
-* The new lints cannot target third-party crates.  
-* Complex lints may not be wanted due to maintenance effort.  
+* The new lints cannot be project-specific.
+* The new lints cannot target third-party crates.
+* Complex lints may not be wanted due to maintenance effort.
 * Lints with a high false-positive rate may not be wanted.
 
 Moreover, writing lints with Dylint instead of forking Clippy [helps with dealing with the unstable `rustc` API and with sharing lints with other people](https://blog.trailofbits.com/2021/11/09/write-rust-lints-without-forking-clippy/).
@@ -138,8 +138,8 @@ cargo dylint  \
 
 You can write your own lint, but it is a nontrivial task and is beyond the scope of this chapter. At a high level, you will need to decide on the type of lint:
 
-* Pre-expansion: Run on the AST before macros are expanded  
-* Early: Run on the AST after macros have been expanded  
+* Pre-expansion: Run on the AST before macros are expanded
+* Early: Run on the AST after macros have been expanded
 * Late: Run on the high-level intermediate representation (HIR)—that is, after names have been resolved, types have been checked, etc.
 
 Check out [Samuel Moelius’s ‘Linting with Dylint’ EuroRust 2024](https://youtu.be/MjlPUA7sAmA?t=548) talk for detailed guidelines.

content/docs/languages/rust/40-gotchas.md

@@ -16,8 +16,8 @@ This section provides a checklist that can be used during manual Rust code revie
   - Often partial-match (`starts_with`, `ends_with`, `contains`) is used instead of equality.
   - Case (in)sensitivity of comparisons often results in issues.
 - [ ] Check string conversions to other data types (like `Vec`) and vice versa. These may come with UTF-8 encoding issues. Options for handling bytes that may not be valid UTF-8:
-  - `from_utf8` with `unwrap`—strict, panics on non-convertible data  
-  - `from_utf8_lossy`—lossy, replaces invalid UTF-8 sequences with U+FFFD (replacement character)  
+  - `from_utf8` with `unwrap`—strict, panics on non-convertible data
+  - `from_utf8_lossy`—lossy, replaces invalid UTF-8 sequences with U+FFFD (replacement character)
   - `OsStr`/`OsString`—for platform-native strings that may not be valid UTF-8 (e.g., paths, environment variables, and `argv`); it is not a UTF-8/bytes converter, and there is no portable way to get its raw bytes (`as_bytes` is Unix-only; `as_encoded_bytes` uses a non-portable encoding)
 - [ ] Verify that the `with_capacity` method of the `Vec`, `HashMap`, `HashSet`, and `indexmap::IndexSet` types (and possibly other types) is not called with user-controlled data. Large values can lead to denial of service.
   - Also check that the provided capacity is smaller than the `isize::MAX` bytes [to prevent panics](https://doc.rust-lang.org/std/vec/struct.Vec.html#panics).
@@ -62,14 +62,14 @@ Common issues to check for in unsafe code are given below. For more information,
 
 {{< checklist >}}
 
-- [ ] Any union access is unsafe in Rust. Verify that the union field that matches the underlying data is used.  
-- [ ] Look for uses of libc APIs like `memset` or `memcpy`. Most of them can be replaced with safe Rust counterparts.  
+- [ ] Any union access is unsafe in Rust. Verify that the union field that matches the underlying data is used.
+- [ ] Look for uses of libc APIs like `memset` or `memcpy`. Most of them can be replaced with safe Rust counterparts.
 - [ ] If `#[repr(packed)]` is used on a struct, then check that `read_unaligned`/[`write_unaligned`](https://doc.rust-lang.org/std/ptr/fn.write_unaligned.html#on-packed-structs) is used for unaligned fields.
 - [ ] Check for uses of [`std::mem::uninitialized`](https://doc.rust-lang.org/std/mem/fn.uninitialized.html) and `mem::zeroed`.
 - [ ] Review uses of `MaybeUninit` to ensure that all calls to `assume_init` are preceded by initialization.
   - Ensure that dropping of partially initialized data is implemented correctly.
-- [ ] Check for uses of [`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html).  
-- [ ] Check for uses of `transmute` or `cast` from a non-mutable reference `&` to a mutable `&mut` (likely an undefined behavior).
+- [ ] Check for uses of [`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html).
+- [ ] Check for uses of `transmute` or `cast` from a non-mutable reference `&` to a mutable `&mut` (likely undefined behavior).
   - Using [`bytemuck`](https://docs.rs/bytemuck/latest/bytemuck/) or [`zerocopy`](https://docs.rs/zerocopy/latest/zerocopy/) crates may be a safer alternative.
 - [ ] Review uses of `static mut` and [recommend using synchronization instead](https://github.com/rust-lang/rust/issues/53639).
 - [ ] Review uses of [unsafe attributes](https://github.com/rust-lang/rfcs/blob/master/text/3325-unsafe-attributes.md) like `#[unsafe(no_mangle)]`.