Safe Path

A library to safely handle filesystem paths, typically for container runtimes.

There are often path related attacks, such as symlink based attacks, TOCTTOU attacks. The safe-path crate provides several functions and utility structures to protect against path resolution related attacks.

Support

Operating Systems:

• Linux

Reference

• filepath-securejoin: secure_join() written in Go.
• CVE-2021-30465: symlink related TOCTOU flaw in runC.

License

This code is licensed under Apache-2.0.

lib.rs:

A library to safely handle filesystem paths, typically for container runtimes.

Linux mount namespace provides isolation of the list of mounts seen by the processes in each namespace instance. Thus, the processes in each of the mount namespace instances will see distinct single-directory hierarchies.

Containers are used to isolate workloads from the host system. Container on Linux systems depends on the mount namespace to build an isolated root filesystem for each container, thus protect the host and containers from each other. When creating containers, the container runtime needs to setup filesystem mounts for container rootfs/volumes. Configuration for mounts/paths may be indirectly controlled by end users through:

• container images
• Kubernetes pod specifications
• hook command line arguments

These volume configuration information may be controlled by end users/malicious attackers, so it must not be trusted by container runtimes. When the container runtime is preparing mount namespace for a container, it must be very careful to validate user input configuration information and ensure data out of the container rootfs directory won't be affected by the container. There are several types of attacks related to container mount namespace:

• symlink based attack
• Time of check to time of use (TOCTTOU)

This crate provides several mechanisms for container runtimes to safely handle filesystem paths when preparing mount namespace for containers.

• scoped_join(): safely join unsafe_path to root, and ensure unsafe_path is scoped under root.
• scoped_resolve(): resolve unsafe_path to a relative path, rooted at and constrained by root.
• struct PinnedPathBuf: safe version of PathBuf to protect from TOCTTOU style of attacks, which ensures:
  • the value of [PinnedPathBuf::as_path()] never changes.
  • the path returned by [PinnedPathBuf::as_path()] is always a symlink.
  • the filesystem object referenced by the symlink [PinnedPathBuf::as_path()] never changes.
  • the value of [PinnedPathBuf::target()] never changes.
• struct ScopedDirBuilder: safe version of DirBuilder to protect from symlink race and TOCTTOU style of attacks, which enhances security by:
  • ensuring the new directories are created under a specified root directory.
  • avoiding symlink race attacks during making directories.
  • returning a [PinnedPathBuf] for the last level of directory, so it could be used for other operations safely.

The work is inspired by:

• filepath-securejoin: secure_join() written in Go.
• CVE-2021-30465: symlink related TOCTOU flaw in runC.