pathrs 0.2.4

// SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later
/*
 * libpathrs: safe path resolution on Linux
 * Copyright (C) 2019-2025 SUSE LLC
 * Copyright (C) 2026 Aleksa Sarai <cyphar@cyphar.com>
 *
 * == MPL-2.0 ==
 *
 *  This Source Code Form is subject to the terms of the Mozilla Public
 *  License, v. 2.0. If a copy of the MPL was not distributed with this
 *  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 *
 * Alternatively, this Source Code Form may also (at your option) be used
 * under the terms of the GNU Lesser General Public License Version 3, as
 * described below:
 *
 * == LGPL-3.0-or-later ==
 *
 *  This program is free software: you can redistribute it and/or modify it
 *  under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or (at
 *  your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License  for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this program. If not, see <https://www.gnu.org/licenses/>.
 */

use crate::{
    error::{Error, ErrorImpl},
    flags::OpenFlags,
    procfs,
    syscalls::{self, OpenHow, ResolveFlags},
    utils::{fd::proc_threadself_subpath, FdExt, MaybeOwnedFd},
};

use std::{
    os::unix::{
        fs::MetadataExt,
        io::{AsRawFd, BorrowedFd, OwnedFd},
    },
    path::Path,
};

use rustix::fs::{Access, AtFlags};

/// "We have [`ProcfsHandle`] at home."
///
/// One of the core issues when implementing [`ProcfsHandle`] is that a lot of
/// helper functions used by [`ProcfsHandle`] would really like to be able to
/// use [`ProcfsHandle`] in a re-entrant way to get some extra safety against
/// attacks, while also supporting callers that don't even have a `/proc` handle
/// ready or callers that are not within the [`ProcfsHandle`] implementation and
/// thus can get full safety from [`ProcfsHandle`] itself.
///
/// The main purpose of this type is to allow us to easily indicate this (as
/// opposed to `Option<BorrowedFd<'_>>` everywhere) and provide some helpers to
/// help reduce the complexity of the helper functions.
///
/// In general, you should only be using this for core helper functions used by
/// [`ProcfsHandle`] which need to take a reference to the *root* of `/proc`.
/// Make sure to always use the same [`RawProcfsRoot`] consistently, lest you
/// end up with very weird coherency problems.
///
/// [`ProcfsHandle`]: crate::procfs::ProcfsHandle
#[derive(Copy, Clone, Debug)]
pub(crate) enum RawProcfsRoot<'fd> {
    /// Use the global `/proc`. This is unsafe against most attacks, and should
    /// only ever really be used for debugging purposes only, such as in
    /// [`FdExt::as_unsafe_path_unchecked`].
    ///
    /// [`FdExt::as_unsafe_path_unchecked`]: crate::utils::FdExt::as_unsafe_path_unchecked
    UnsafeGlobal,

    /// Use this [`BorrowedFd`] as the rootfs of a proc and operate relative to
    /// it. This is still somewhat unsafe, depending on what kernel features are
    /// available.
    UnsafeFd(BorrowedFd<'fd>),
}

impl<'fd> RawProcfsRoot<'fd> {
    /// Convert this to a [`MaybeOwnedFd`].
    ///
    /// For [`RawProcfsRoot::UnsafeGlobal`], this requires opening `/proc` and
    /// thus allocating a new file handle. For all other variants this should be
    /// a very cheap reference conversion.
    pub(crate) fn try_into_maybe_owned_fd<'a>(&'a self) -> Result<MaybeOwnedFd<'a, OwnedFd>, Error>
    where
        'a: 'fd,
    {
        let fd = match self {
            Self::UnsafeGlobal => MaybeOwnedFd::OwnedFd(
                syscalls::openat(
                    syscalls::BADFD,
                    "/proc",
                    OpenFlags::O_PATH | OpenFlags::O_DIRECTORY,
                    0,
                )
                .map_err(|err| ErrorImpl::RawOsError {
                    operation: "open /proc handle".into(),
                    source: err,
                })?,
            ),
            Self::UnsafeFd(fd) => MaybeOwnedFd::BorrowedFd(*fd),
        };
        procfs::verify_is_procfs_root(fd.as_fd())?;
        Ok(fd)
    }

    /// `accessat(procfs_root, path, Access:EXISTS, AtFlags::SYMLINK_NOFOLLOW)`
    ///
    /// Should only be used as an indicative check (namely to see if
    /// `/proc/thread-self` exists), and this has no protections against
    /// malicious components regardless of what kind of handle it is.
    ///
    /// The only user of this is [`ProcfsBase::into_path`] which only uses it to
    /// decide whether `/proc/thread-self` exists.
    ///
    /// [`ProcfsBase::into_path`]: crate::procfs::ProcfsBase::into_path
    pub(crate) fn exists_unchecked(&self, path: impl AsRef<Path>) -> Result<(), Error> {
        syscalls::accessat(
            self.try_into_maybe_owned_fd()?.as_fd(),
            path,
            Access::EXISTS,
            AtFlags::SYMLINK_NOFOLLOW,
        )
        .map_err(|err| {
            ErrorImpl::RawOsError {
                operation: "check if subpath exists in raw procfs".into(),
                source: err,
            }
            .into()
        })
    }

    /// Open a subpath within this [`RawProcfsRoot`] using `openat2`.
    ///
    /// `RESOLVE_NO_MAGICLINKS | RESOLVE_NO_XDEV | RESOLVE_BENEATH` are all
    /// auto-applied.
    fn openat2_beneath(&self, path: impl AsRef<Path>, oflags: OpenFlags) -> Result<OwnedFd, Error> {
        let path = path.as_ref();

        syscalls::openat2(
            self.try_into_maybe_owned_fd()?.as_fd(),
            path,
            OpenHow {
                flags: oflags.bits() as _,
                mode: 0,
                resolve: (ResolveFlags::RESOLVE_NO_MAGICLINKS
                    | ResolveFlags::RESOLVE_NO_XDEV
                    | ResolveFlags::RESOLVE_BENEATH)
                    .bits(),
            },
        )
        .map_err(|err| {
            ErrorImpl::RawOsError {
                operation: "open raw procfs subpath".into(),
                source: err,
            }
            .into()
        })
    }

    /// Open a subpath within this [`RawProcfsRoot`] using `openat`.
    ///
    /// A best-effort attempt is made to try to avoid getting tricked by
    /// overmounts, but this method does not guarantee protection against
    /// bind-mount overmounts.
    fn opath_beneath_unchecked(
        &self,
        path: impl AsRef<Path>,
        oflags: OpenFlags,
    ) -> Result<OwnedFd, Error> {
        let path = path.as_ref();
        let proc_rootfd = self.try_into_maybe_owned_fd()?;
        let proc_rootfd = proc_rootfd.as_fd();

        // We split the open into O_PATH+reopen below, which means if O_NOFOLLOW
        // is requested (which it always is), we need to apply it to the initial
        // O_PATH and not the re-open. If the target is not a symlink,
        // everything works fine -- if the target was a symlink the re-open will
        // fail with -ELOOP (the same as a one-shot open).
        let (opath_oflags, oflags) = (
            oflags & OpenFlags::O_NOFOLLOW,
            oflags & !OpenFlags::O_NOFOLLOW,
        );

        // This is technically not safe, but there really is not much we can do
        // in practice -- we would need to have a separate copy of the procfs
        // resolver code without any mount-id-related protections (or add an
        // unsafe_disable_mnt_id_checks argument), and even then it would not
        // practically protect against attacks.
        //
        // An attacker could still bind-mount their own /proc/thread-self/fdinfo
        // (after opening hundreds of handles to /proc) on top of our
        // /proc/thread-self/fdinfo, at which point they could trivially fake
        // fdinfo without the need for symlinks or tmpfs.
        //
        // At this point, we are just trying to minimise the damage a trivial
        // attack on top of a static procfs path can do. An attacker that can
        // actively bind-mount on top of /proc/thread-self/fdinfo cannot be
        // protected against without openat2(2) or STATX_MNT_ID.

        // In order to avoid being tricked into following a trivial symlink or
        // bind-mount to a filesystem object that could DoS us when we try to
        // O_RDONLY open it below (such as a stale NFS handle), first open it
        // with O_PATH then double-check that it is a procfs inode.
        let opath = syscalls::openat(proc_rootfd, path, OpenFlags::O_PATH | opath_oflags, 0)
            .map_err(|err| ErrorImpl::RawOsError {
                operation: "preliminary open raw procfs subpath to check fstype".into(),
                source: err,
            })?;
        // As below, we can't use verify_same_procfs_mnt.
        procfs::verify_is_procfs(&opath)?;

        // We can't do FdExt::reopen() here because this code is potentially
        // called within ProcfsHandle. However, we can just re-open through
        // /proc/thread-self/fd/$n directly -- this is not entirely safe
        // against bind-mounts but this will make it harder for an attacker
        // (they would need to predict the fd number of the transient file
        // we just opened, and have the ability to bind-mount over
        // magic-links -- which is something that a lot of tools do not
        // support).
        let file = syscalls::openat_follow(
            proc_rootfd,
            proc_threadself_subpath(*self, &format!("fd/{}", opath.as_raw_fd())),
            oflags,
            0,
        )
        .map_err(|err| ErrorImpl::RawOsError {
            operation: "re-open raw procfs subpath".into(),
            source: err,
        })?;
        // As below, we can't use verify_same_procfs_mnt.
        procfs::verify_is_procfs(&file)?;

        // Finally, verify that the inode numbers match. This is not
        // strictly "necessary" (since the opath could be an
        // attacker-controlled procfs file), but this could at least detect
        // sloppy /proc/self/fd/* overmounts.
        if opath.metadata()?.ino() != file.metadata()?.ino() {
            Err(ErrorImpl::SafetyViolation {
                    description: "fd has an inconsistent inode number after re-opening -- probably a manipulated procfs".into(),
                })?;
        }
        Ok(file)
    }

    /// Open a subpath within this [`RawProcfsRoot`].
    ///
    /// As this method is only really used for `fdinfo`, trailing symlinks are
    /// not followed (i.e. [`OpenFlags::O_NOFOLLOW`] is always implied).
    pub(crate) fn open_beneath(
        &self,
        path: impl AsRef<Path>,
        mut oflags: OpenFlags,
    ) -> Result<OwnedFd, Error> {
        let path = path.as_ref();
        oflags.insert(OpenFlags::O_NOFOLLOW);

        let fd = self.openat2_beneath(path, oflags).or_else(|err| {
            // If an error occurred, it could be due to openat2(2) being
            // disabled via seccomp or just being unsupported. We check this via
            // a dummy openat2(2) chall -- if that fails then we fallback to
            // O_PATH, otherwise we assume openat2(2) failed for a good reason
            // and return that error outright.
            if syscalls::openat2::openat2_is_not_supported() {
                self.opath_beneath_unchecked(path, oflags)
            } else {
                Err(err)
            }
        })?;

        // As this is called from within fetch_mnt_id as a fallback, the only
        // thing we can do here is verify that it is actually procfs. However,
        // in practice it will be quite difficult for an attacker to over-mount
        // every fdinfo file for a process.
        procfs::verify_is_procfs(&fd)?;
        Ok(fd)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::ErrorKind;

    use pretty_assertions::assert_matches;

    #[test]
    fn exists_unchecked() {
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .exists_unchecked("nonexist")
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ENOENT))),
            r#"exists_unchecked("nonexist") -> ENOENT"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .exists_unchecked("uptime")
                .map_err(|err| err.kind()),
            Ok(()),
            r#"exists_unchecked("uptime") -> Ok"#
        );
    }

    #[test]
    fn open_beneath() {
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .open_beneath("nonexist", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ENOENT))),
            r#"open_beneath("nonexist") -> ENOENT"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .open_beneath("self", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ELOOP))),
            r#"open_beneath("self") -> ELOOP"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .open_beneath("self/cwd", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ELOOP))),
            r#"open_beneath("self/cwd") -> ELOOP"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .open_beneath("self/status", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Ok(_),
            r#"open_beneath("self/status") -> Ok"#
        );
    }

    #[test]
    fn openat2_beneath() {
        if syscalls::openat2::openat2_is_not_supported() {
            return; // skip
        }
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .openat2_beneath("nonexist", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ENOENT))),
            r#"openat2_beneath("nonexist") -> ENOENT"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .openat2_beneath("self", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ELOOP))),
            r#"openat2_beneath("self") -> ELOOP"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .openat2_beneath("self/cwd", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ELOOP))),
            r#"openat2_beneath("self/cwd") -> ELOOP"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .openat2_beneath("self/status", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Ok(_),
            r#"openat2_beneath("self/status") -> Ok"#
        );
    }

    #[test]
    fn opath_beneath_unchecked() {
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .opath_beneath_unchecked("nonexist", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ENOENT))),
            r#"opath_beneath_unchecked("nonexist") -> ENOENT"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .opath_beneath_unchecked("self", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ELOOP))),
            r#"opath_beneath_unchecked("self") -> ELOOP"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .opath_beneath_unchecked("self/cwd", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Err(ErrorKind::OsError(Some(libc::ELOOP))),
            r#"opath_beneath_unchecked("self/cwd") -> ELOOP"#
        );
        assert_matches!(
            RawProcfsRoot::UnsafeGlobal
                .opath_beneath_unchecked("self/status", OpenFlags::O_RDONLY)
                .map_err(|err| err.kind()),
            Ok(_),
            r#"opath_beneath_unchecked("self/status") -> Ok"#
        );
    }
}