Security Assurance Case

This document provides a structured argument that mmap-guard meets its security requirements.

Frameworks Referenced

This assurance case draws on three complementary frameworks:

• NIST IR 7608 – structured assurance case model. Provides the overall argument structure (security requirements, threat model, trust boundaries, countermeasures).
• NIST SSDF (SP 800-218) – Secure Software Development Framework. Maps our development practices to the four SSDF practice groups (PO, PS, PW, RV). See Section 10.
• SLSA v1.0 – Supply-chain Levels for Software Artifacts. Defines progressive build integrity levels. See Section 11.

1. Security Requirements

mmap-guard is a safe wrapper around memmap2::Mmap::map() that isolates the single unsafe call behind a hardened boundary. Its security requirements are:

1. SR-1: Must not exhibit undefined behavior when mapping any file
2. SR-2: Must not allow use-after-unmap of memory-mapped regions
3. SR-3: Must not create mutable aliasing of mapped memory
4. SR-4: Must not allow path traversal via file path arguments
5. SR-5: Must validate all pre-flight conditions (non-empty, permissions) before the unsafe mmap call
6. SR-6: Must hold advisory locks for the full lifetime of the mapping
7. SR-7: Must not leak file descriptors or mappings across FileData instances

2. Threat Model

2.1 Assets

• Host system: The machine running mmap-guard
• Mapped file contents: Data being mapped (may be sensitive)
• File descriptors: OS resources held by FileData::Mapped

2.2 Threat Actors

2.3 Attack Vectors

3. Trust Boundaries

flowchart TD
    subgraph Untrusted["Untrusted Zone"]
        direction LR
        FP["File Paths<br/>(user input)"]
        FC["File Contents<br/>(any data)"]
        CP["Concurrent Processes<br/>(may truncate files)"]
    end

    subgraph mmap-guard["mmap-guard (Trusted Zone)"]
        PF["Pre-flight Checks<br/>exists, non-empty, permissions"]
        AL["Advisory Locking<br/>fs4 try_lock_shared"]
        UB["Unsafe Boundary<br/>single Mmap::map() call"]
        FD["FileData<br/>Mmap + File lifetime coupling"]
    end

    FP -- "path" --> PF
    FC -- "file bytes" --> UB
    CP -- "filesystem ops" --> AL
    PF -- "validated file" --> AL
    AL -- "locked file" --> UB
    UB -- "mapped region" --> FD

    style Untrusted fill:#4a1a1a,stroke:#ef5350,color:#e0e0e0,stroke-width:2px
    style mmap-guard fill:#1b3d1b,stroke:#66bb6a,color:#e0e0e0,stroke-width:2px

All data crossing the trust boundary (file paths, file contents) is treated as untrusted and validated before use. Concurrent processes are mitigated through cooperative advisory locking.

4. Secure Design Principles (Saltzer and Schroeder)

5. The Unsafe Boundary

Unlike most Rust crates which use #![forbid(unsafe_code)], mmap-guard is the unsafe boundary. It exists specifically to contain the one unsafe call that downstream #![forbid(unsafe_code)] crates cannot make themselves.

The crate enforces:

• Exactly one unsafe block in the entire crate (in src/map.rs). Adding new ones requires an issue discussion.
• #![deny(clippy::undocumented_unsafe_blocks)] – every unsafe block must have a // SAFETY: comment explaining why the invariants are upheld.
• Strict clippy lints: unwrap_used = "deny", panic = "deny", full pedantic/nursery/cargo groups enabled.

Safety Invariants

The safety of memmap2::Mmap::map() relies on these conditions, all of which mmap-guard upholds:

6. Common Weakness Countermeasures

6.1 CWE/SANS Top 25

6.2 OWASP Top 10 (where applicable)

Most OWASP Top 10 categories target web applications and are not applicable to a memory-mapping library. The applicable items are:

7. Known Limitation: SIGBUS / Access Violation

If the underlying file is truncated or modified by another process while mapped, the operating system may deliver:

• Unix: SIGBUS signal
• Windows: Access violation (structured exception)

This is inherent to memory-mapped I/O and cannot be fully prevented. It is explicitly out of scope for security reports (see SECURITY.md).

Mitigation

mmap-guard acquires a cooperative shared advisory lock via fs4::FileExt::try_lock_shared before creating the mapping. This is advisory only – it relies on other processes cooperating. The lock and mapping lifetimes are coupled through FileData::Mapped(Mmap, File).

For applications needing stronger guarantees:

1. Advisory locking – rely on mmap-guard’s built-in shared lock (cooperative)
2. Signal handling – install a SIGBUS handler that can recover gracefully (complex and platform-specific)
3. Copy-on-read – for small files, prefer std::fs::read() via the FileData::Loaded path

8. Supply Chain Security

Note: cargo-auditable is not applicable – it embeds dependency metadata in ELF/PE binaries, which do not exist for a library crate. SBOM and provenance attestation cover the equivalent supply chain visibility.

9. Ongoing Assurance

This assurance case is maintained as a living document. It is updated when:

• New features introduce new attack surfaces
• New threat vectors are identified
• Dependencies change significantly
• Security incidents occur

The project maintains continuous assurance through automated CI checks (clippy, cargo audit, cargo deny, OSSF Scorecard) that run on every commit and on daily schedules.

10. SSDF Practice Mapping

This section maps mmap-guard’s development practices to the NIST Secure Software Development Framework (SP 800-218) practice groups.

PO: Prepare the Organization

PS: Protect the Software

PW: Produce Well-Secured Software

RV: Respond to Vulnerabilities

11. SLSA Build Level Assessment

This section assesses mmap-guard’s current SLSA v1.0 build level and identifies gaps for advancement.

Current Level: Build L1

Build L2 Requirements (target)

Build L3 Requirements (aspirational)

Roadmap to Build L2

1. Add slsa-framework/slsa-github-generator to the release workflow to produce signed SLSA provenance
2. Attach the provenance attestation to the GitHub Release alongside the SBOM
3. Document verification steps for consumers (slsa-verifier)