diff --git a/docs/contribute/development/rust/certification/index.rst b/docs/contribute/development/rust/certification/index.rst index c9b484270ab..a80d01a2c21 100644 --- a/docs/contribute/development/rust/certification/index.rst +++ b/docs/contribute/development/rust/certification/index.rst @@ -15,6 +15,35 @@ Certification ############## + +Rust Certification Guidance +=========================== + +This section summarizes certification-relevant guidance for Rust and its +tooling, especially in the context of ISO 26262 and RTCA DO-178C/DO-332. + +Key points for practice: + +* Tool confidence and qualification must be explicitly defined for compiler and + crates. +* Depending on project context and integrity level, three paths are considered: + qualified tools, strong downstream verification that detects tool faults, or + comprehensive confidence evidence for tool usage. +* Qualification evidence is tied to the exact tool version, target + architecture, and relevant compiler configuration. +* Stable toolchains are expected for certification contexts; nightly features + are not recommended for safety-related projects. +* Configuration management must include Rust toolchain components (e.g., + compiler, rustup/cargo, clippy/rustdoc), runtime libraries, and external + crates. +* "Proven in use" arguments alone are considered difficult to justify for + safety cases and should not replace structured qualification or verification + arguments. + +For SCORE, this baseline guidance should be used for certification +strategy, while project-specific safety case evidence is documented in the +corresponding plans and work products. + .. toctree:: :maxdepth: 1 diff --git a/docs/contribute/development/rust/coding_guidelines.rst b/docs/contribute/development/rust/coding_guidelines.rst index 9bfcc920fdd..30ac35b409a 100644 --- a/docs/contribute/development/rust/coding_guidelines.rst +++ b/docs/contribute/development/rust/coding_guidelines.rst @@ -23,8 +23,43 @@ Writing Rust Code incl. Coding Guidelines :realizes: wp__sw_development_plan +Safety Rust +=========== + +For writing Rust code in SCORE, especially for safety- and +security-relevant software, the following guidance and tooling references +apply. + + Coding Guidelines -================= +----------------- + +The following coding guidelines and reference documents are relevant for +Rust development in SCORE: + +* A safety- and cybersecurity-oriented Rust baseline is used as the primary + reference for safety- and security-related development and for arguing + safety according to ISO 26262 or RTCA DO-178C combined with RTCA DO-332. + It provides a comprehensive set of recommendations for using Rust in + safety-critical systems, including language features, coding practices, and + tool usage. +* `Safety-Critical Rust Coding Guidelines `_ + are still under development and currently only define a subset of the + desired rules. +* `Secure Rust Guidelines (unstable) `_ + complement this baseline. ANSSI focuses more on process and architecture + guidance, while the baseline is more concrete regarding tool usage and + enforceable checks. +* `Linux Kernel Rules `_ + mainly define formatting and documentation requirements for Rust in the + Linux kernel and do not provide broader static code analysis rules. +* `MISRA C:2025 Addendum 6, Applicability of MISRA C:2025 to the Rust Programming Language `_ + overlaps strongly with this baseline and is therefore primarily relevant as an + additional cross-reference. + + +State of Rust Safety-Critical Tooling +------------------------------------- The Safety-Critical Rust Consortium aims to make Rust suitable for use in automotive and other safety-critical environments by building and maintaining a @@ -52,17 +87,13 @@ enable certification and safe use of Rust in automotive applications. `Rust language `_ - -State of Rust Safety-Critical Tooling -##################################### - The linked document provides a current overview of the tooling landscape for certifying Rust in safety-critical applications, presenting a community-approved list of essential tools and tracking their development status. It also explores whether developing specialized training curricula for safety-critical Rust is necessary, potentially requiring a separate -subcommittee. The document details the state of specific tools—such as -compilers and analysis utilities—by outlining their intended purposes, +subcommittee. The document details the state of specific tools, such as +compilers and analysis utilities, by outlining their intended purposes, certification requirements, and their availability or progress. While some tools, such as the Ferrocene compiler, are already available or being actively developed, others remain under evaluation or are not yet accessible. @@ -70,20 +101,8 @@ developed, others remain under evaluation or are not yet accessible. `Mission Statement - Tooling Subcommittee `_ -Explanation of ARA Applications in Rust -####################################### - -AUTOSAR also shares a public available document that explains how to use Rust in -ARA applications as Rust is offering safety and performance advantages. While -ecosystem support is still maturing, Rust-based ARA applications can lead to -safer, more reliable automotive software, especially in safety-critical and -high-performance domains. - -`AUTOSAR ARA Applications in Rust `_ - - -MISRA vs Cert -############# +MISRA vs CERT +------------- This issue contrasts the MISRA and CERT coding standards, highlighting their different approaches to software safety and security. MISRA is noted for its @@ -93,19 +112,21 @@ security. This can create unnecessary work for developers without clear benefits and is sometimes inconsistent across languages. CERT, on the other hand, is praised for its focus on practical, consensus-based rules that target real security vulnerabilities in existing code, avoiding excessive constraints. -The overall recommendation is to favor guidelines like CERT’s—practical, -evidence-based, and focused on real-world issues—over rigid, untested standards -that hinder adoption and developer productivity. +The overall recommendation is to favor guidelines like CERT's: practical, +evidence-based, and focused on real-world issues, over rigid, untested +standards that hinder adoption and developer productivity. `MISRA vs Cert `_ -In 2026 the Coding Guidelines Subcommittee of the SCRC are aiming to have MISRA C and CERT C mapped to Rust, with +In 2026 the Coding Guidelines Subcommittee of the SCRC are aiming to have +MISRA C and CERT C mapped to Rust, with + +* a bulk of the coding guidelines written +* a bulk of the Clippy lints necessary written to check the guidelines -- a bulk of the coding guidelines written -- a bulk of the Clippy lints necessary written to check the guidelines -Link to Clippy -############## +Rust Tooling: Clippy +-------------------- Rust Clippy is a collection of lints (code style and correctness checks) for the Rust programming language. It helps developers identify common mistakes, @@ -117,8 +138,36 @@ tool for writing clean, idiomatic, and efficient Rust code. `Link to Clippy `_ -Link to Miri -############ +Rust Tooling: CodeQL +-------------------- + +CodeQL is a code analysis platform based on the QL query language and +associated tooling. It supports Rust (see +https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/ +and https://codeql.github.com/codeql-query-help/rust-cwe/). + +Typical problem classes detected by CodeQL for Rust include: + +* injection vulnerabilities (e.g., SQL injection, path traversal, + regex injection, log injection, XSS) +* insecure communication and transport usage (e.g., non-HTTPS URLs, + disabled TLS certificate checks) +* cryptographic weaknesses (e.g., hard-coded cryptographic values, + weak algorithms or weak hashing) +* sensitive data exposure (e.g., cleartext logging, cleartext + transmission or storage) +* request and input abuse patterns (e.g., SSRF, uncontrolled allocation + size from untrusted input) +* unsafe memory-related patterns relevant at Rust unsafe boundaries + (e.g., access-after-lifetime-ended, invalid pointer access, + constructor initialization issues) + +CodeQL's key strength is inter-procedural data-flow/taint tracking, +which complements compiler and lint checks. + + +Rust Tooling: Miri +------------------ Miri is an Undefined Behavior detection tool for Rust. It can run binaries and test suites of cargo projects and detect unsafe code that fails to @@ -126,17 +175,127 @@ uphold its safety requirements. `Link to Miri `_ + Conclusions for S-CORE -###################### +---------------------- + +The current baseline includes general Rust safety and security topics together +with related rules and recommendations. The following table shows how each +topic is captured in practice, including automated checks (by tool and tool option) and supporting +process measures. Where no automated check exists, coverage is captured +through manual review, process controls, or architecture decisions. + +The classification follows a MISRA-style convention: + +* Required — Mandatory. Deviations need documented reasoning. +* Advisory — Recommended. Deviations should be documented when practical. +* Document — The decision and its reasoning must be documented regardless of outcome. + +The matrix below summarizes overall coverage for these topics. The +`Cargo.toml` profiles further below provide a practical baseline and +intentionally contain a recommended subset of checks. + +.. csv-table:: Overlap Summary Matrix (Baseline Measures) + :header: "Name", "Type", "Automated (Baseline)", "CodeQL", "Clippy", "Rustc", "Other Tooling / Process", "Combined" + :widths: 24, 14, 12, 10, 18, 18, 22, 8 + + "Compiler qualification", "Document, Required", "-", "-", "-", "-", "Process/evidence", "M" + "Dependency management", "Required", "-", "-", "-", "-", "cargo-audit, cargo-deny, cargo-vet, SBOM", "H" + "async/await decision", "Document, Advisory", "-", "-", "-", "-", "Architecture decision record", "M" + "Extension trait guidelines", "Document, Advisory", "-", "-", "-", "-", "Review guideline", "M" + "Minimum Supported Rust Version", "Document, Advisory", "cargo plugin", "-", "-", "M (stable toolchain pinning, rust-version policy)", "Toolchain pinning in CI", "H" + "Shadowing style", "Document, Advisory", "Partially, clippy", "-", "M (shadow_reuse/shadow_unrelated as warn, shadow_same as allow)", "-", "Review style guide", "M" + "Code review environment", "Advisory", "-", "-", "-", "-", "Process/tooling setup", "M" + "Macro review and testing strategy", "Document, Advisory", "-", "-", "-", "-", "Tests, trybuild, review", "M" + "Module file naming", "Document, Advisory", "Partially", "-", "L (no strong built-in lint)", "-", "Custom checks", "M" + "Default trait implementations", "Document, Advisory", "-", "-", "-", "-", "Design guideline", "M" + "Usage of unwrap in mutex lock", "Document, Advisory", "-", "-", "M (unwrap_used with documented exception policy)", "-", "Review policy", "M" + "Document undesirable but not unsafe hardware effects", "Advisory", "-", "-", "-", "-", "Safety documentation", "M" + "FFI: Check values at boundary", "Required", "-", "-", "-", "-", "FFI tests, fuzzing, review", "M" + "Safe wrapper for unsafe interfaces", "Required", "-", "-", "-", "-", "Design/review", "M" + "Document unsafe assumptions in Safety: clause", "Required", "clippy", "-", "H (undocumented_unsafe_blocks)", "-", "-", "H" + "Minimal scope for unsafe", "Required", "-", "-", "M (policy/review support, no single strong lint)", "-", "cargo-geiger, review", "M" + "Unsafe block in unsafe function", "Required", "clippy", "-", "M (supporting only, project-dependent)", "H (unsafe_op_in_unsafe_fn)", "-", "H" + "Safety documentation for unsafe functions", "Required", "clippy", "-", "M (manual documentation/review in profile baseline)", "-", "Rustdoc + review process", "M" + "Panic documentation on functions", "Required", "clippy", "-", "H (missing_panics_doc)", "-", "-", "H" + "Global mutable state with sound wrapper", "Required", "-", "-", "-", "-", "Review/design", "M" + "FFI rules from ANSII", "Required", "-", "-", "-", "-", "FFI conformance process", "M" + "Inline assembly rules from reference", "Required", "-", "-", "-", "-", "Manual asm review", "M" + "Automated contract versioning", "Advisory", "symbols", "-", "-", "-", "Symbol/ABI diff tooling", "H" + "Pointer to reference conversion", "Required", "-", "M", "M (cast_ptr_alignment, ptr_cast_constness, ref_as_ptr, transmute_ptr_to_ptr)", "M (invalid_reference_casting plus diagnostics)", "Review/tests", "M" + "Define proper panic handling", "Document, Required", "-", "-", "M (panic_in_result_fn as warn; unwrap_used and panicking_overflow_checks evaluated for usefulness)", "M (panic strategy/profile settings)", "Panic strategy in CI/profile", "H" + "catch_unwind only for controlled shutdown", "Required", "-", "-", "L (no direct strong lint)", "-", "Review policy", "M" + "Deref misuse for inheritance", "Required", "-", "-", "L (no direct strong lint)", "-", "Review/style", "M" + "Transitive interior mutability documentation", "Advisory", "-", "-", "-", "-", "Documentation process", "M" + "No internal mutability in constants", "Required", "-", "-", "H (declare_interior_mutable_const)", "-", "-", "H" + "Prefer cfg!() over #[cfg()]", "Required", "-", "-", "-", "-", "Review/custom linting", "M" + "Features are additive, not exclusive", "Required", "-", "-", "-", "-", "Cargo feature CI checks", "H" + "No deprecated interfaces from core/std", "Required", "-", "-", "M (deprecated in lint profile)", "H (deprecated)", "-", "H" + "No nightly features", "Required", "rustc", "-", "-", "H (stable compiler policy; unstable_features on nightly)", "Stable toolchain enforcement", "H" + "No wildcard in imports", "Required", "clippy", "-", "H (wildcard_imports)", "-", "-", "H" + "Ensure formatting and lints (e.g., in CI)", "Advisory", "rustfmt + clippy", "-", "H (CI clippy gate)", "-", "rustfmt in CI", "H" + "No raw identifiers", "Required", "grep", "-", "-", "-", "grep/custom check", "H" + "Rustc linter", "Advisory", "rustc", "-", "-", "H (curated rustc baseline profile; extended edition/future lints enabled per toolchain support)", "-", "H" + "Clippy linter", "Advisory", "clippy", "-", "H (curated warn/deny/allow clippy profile)", "-", "-", "H" + "Strong typing for error detection at compile time", "Advisory", "-", "-", "-", "H (type system, borrow checker, trait bounds)", "-", "H" + "Structures replace many arguments", "Advisory", "-", "-", "L (style/review guidance)", "-", "Review/style", "M" + "Testing trait requirements on trait implementations", "Required", "-", "-", "-", "-", "Tests/property tests", "H" + "Test coverage on generics", "Advisory", "coverage", "-", "-", "-", "Coverage tooling", "H" + "Avoid as for conversions", "Required", "clippy", "-", "H (as_underscore, cast_lossless, cast_possible_truncation, cast_possible_wrap, cast_ptr_alignment, cast_sign_loss)", "-", "-", "H" + "Error/Option instead of magic values", "Advisory", "-", "-", "M (partial style support)", "M (type checks support pattern, no direct rule)", "Review", "M" + "Resource Acquisition Is Initialization", "Required", "-", "-", "-", "M (ownership and Drop semantics, no direct lint)", "Review/tests", "M" + "Overflow checking", "Required", "rustc", "-", "-", "H (release overflow-checks enabled)", "Release profile setting", "H" + "Dynamic memory design", "Required", "-", "-", "-", "-", "Allocator/system design checks", "M" + "Stack checking", "Required", "rustc", "-", "-", "M (limited compiler support)", "cargo-call-stack, external analysis", "M" + "Concurrency system design (timing constraints)", "Required", "-", "-", "-", "-", "loom, WCET, system analysis", "M" + "Document cancellation safety of async functions", "Advisory", "-", "-", "-", "-", "Documentation/review", "M" + "Explicit task dropping intention", "Advisory", "-", "-", "L (let_underscore_future as supporting signal)", "-", "Runtime policy/review", "M" + "Planning ahead for Pin/Send", "Document, Advisory", "-", "-", "-", "M (Send and lifetime trait-bound checks)", "Design constraints review", "M" + "Minimize duplicated dependencies because of versioning", "Required", "cargo", "-", "-", "-", "cargo tree, cargo-deny", "H" + "Minimal scope for symbols", "Advisory", "(clippy)", "-", "M (redundant_pub_crate as supporting signal)", "M (unreachable_pub, visibility diagnostics)", "Visibility checks/review", "M" + "Multi-crate design to minimize cyclic dependencies", "Advisory", "-", "-", "-", "-", "cargo graph, dependency analysis", "M" + "Usize should only measure memory, not environment quantities", "Required", "-", "-", "L (no direct strong lint)", "-", "Review/style", "M" + "Separation of download and build steps", "Advisory", "-", "-", "-", "-", "CI sandboxing/pipeline controls", "H" + "Special protection of sensitive data", "Advisory", "-", "H", "-", "-", "Secret handling process", "H" + "Marker traits for formal documentation", "Advisory", "-", "-", "-", "M (trait-bound enforcement mechanism)", "Review/formal method support", "M" + "Lifetime and pointers", "Advisory", "-", "M", "-", "H (borrow checker, lifetime analysis)", "-", "H" + "Atomic access modes", "Advisory", "-", "-", "L (no explicit lint in current baseline profile block)", "-", "Review for ordering rationale", "M" + "Unintended matches", "Advisory", "-", "-", "M (wildcard_enum_match_arm)", "M (non_exhaustive_omitted_patterns)", "-", "M" + "Logically significant return values should be #[must_use]", "Required", "-", "-", "M (let_underscore_must_use)", "M (unused_results in profile; must_use semantics by language)", "-", "M" + "Complex drop logic should be called explicitly", "Required", "-", "-", "L (no direct strong lint)", "-", "Review/tests", "M" + During the S-CORE project formatting and clippy checks are enforced. Miri can -be used to detect undefined behaviors. Also the code should compile with zero warnings. -Additional guidelines by the Rust Community, the Rust Foundation and the Safety-Critical -Rust Consortium are applied where applicable but not enforced. If possible the usage -of `unsafe` is avoided. To keep the code `panic`-free only APIs with a proper return value -should be used. The goal is to have coding guidelines for Rust suitable for safety-critial -systems by Safety-Critical Rust Consortium by the end of 2026. Until that, please also use -Slack score-rust-community channel for discussions and participation in the SCRC. +be used to detect undefined behaviors. Also the code should compile with zero +warnings. Additional guidelines by the Rust Community, the Rust Foundation and +the Safety-Critical Rust Consortium are applied where applicable but not +enforced. If possible the usage of `unsafe` is avoided. To keep the code +`panic`-free only APIs with a proper return value should be used. The goal is +to have coding guidelines for Rust suitable for safety-critical systems by the +Safety-Critical Rust Consortium by the end of 2026. Until that, please also +use Slack score-rust-community channel for discussions and participation in the +SCRC. The adaption of these guidelines will be documented in the S-CORE project documentation. + +The recommended ``[lints.rust]``, ``[lints.clippy]``, and ``[profile.release]`` +settings are maintained centrally in the +`score_rust_policies repository `_: + +* `Practical baseline (relaxed) `_ — + suitable for general SCORE components. +* `Strict / ASIL variant `_ — + for safety-critical code requiring stricter enforcement. + + +Explanation of ARA Applications in Rust +======================================= + +AUTOSAR also shares a public available document that explains how to use Rust in +ARA applications as Rust is offering safety and performance advantages. While +ecosystem support is still maturing, Rust-based ARA applications can lead to +safer, more reliable automotive software, especially in safety-critical and +high-performance domains. + +`AUTOSAR ARA Applications in Rust `_ diff --git a/docs/contribute/development/rust/index.rst b/docs/contribute/development/rust/index.rst index 6f3e5b7b988..b96edc6dee4 100644 --- a/docs/contribute/development/rust/index.rst +++ b/docs/contribute/development/rust/index.rst @@ -15,6 +15,11 @@ Rust #### +For safety- and security-related Rust development, SCORE uses +widely adopted safety- and cybersecurity-oriented Rust guidance as a +baseline reference for recommended practices, in addition to the +project-specific guidance linked below. + .. toctree:: :maxdepth: 1