proc-canonicalize

A patch for std::fs::canonicalize that preserves Linux /proc/PID/root namespace boundaries.

The Problem

On Linux, /proc/PID/root is a "magic symlink" that crosses into a process's mount namespace. When you access files through it, you're accessing the container's filesystem:

# Reading a container's file from the host:
cat /proc/1234/root/etc/os-release  # Shows container's OS, not host's!

However, std::fs::canonicalize resolves this magic symlink to /, breaking security boundaries. This crate preserves the /proc/PID/root, /proc/PID/cwd, and /proc/PID/task/TID/root prefixes:

use std::path::Path;

// BROKEN: std::fs::canonicalize loses the namespace prefix!
let std_resolved = std::fs::canonicalize("/proc/self/root/etc")?;
assert_eq!(std_resolved, Path::new("/etc"));  // Resolves to host's /etc!

// FIXED: Namespace prefix is preserved!
let resolved = proc_canonicalize::canonicalize("/proc/self/root/etc")?;
assert_eq!(resolved, Path::new("/proc/self/root/etc"));

Use Case

Container monitoring and security tools that need to:

1. Access container filesystems from the host via /proc/PID/root
2. Validate that paths stay within the container boundary
3. Prevent container escape vulnerabilities

use proc_canonicalize::canonicalize;

fn read_container_file(container_pid: u32, path: &str) -> std::io::Result<Vec<u8>> {
    let container_root = format!("/proc/{container_pid}/root");
    let full_path = format!("{container_root}/{path}");

    let canonical = canonicalize(&full_path)?;

    // Security: canonical path must stay inside container_root
    assert!(canonical.starts_with(&container_root));

    std::fs::read(&canonical)
}

Supported Paths

Platform Support

• Linux: Full functionality
• Other platforms: Falls back to std::fs::canonicalize (no-op)

Optional Features

dunce (Windows Only)

Simplifies Windows extended-length paths by removing the \\?\ prefix when possible:

[dependencies]
proc-canonicalize = { version = "0.1.2", features = ["dunce"] }

Behavior:

• Without dunce: Returns \\?\C:\Users\Alice\file.txt (Windows extended-length format)
• With dunce: Returns C:\Users\Alice\file.txt (simplified format)

Benefits:

• ✅ More readable paths in logs and user output
• ✅ Automatically preserves \\?\ prefix when needed (e.g., for paths longer than 260 characters)

Zero Dependencies

This crate has no dependencies beyond the Rust standard library.

Installation

[dependencies]
proc-canonicalize = "0.1.2"

License

MIT OR Apache-2.0