### Strict Path Safety (for `procfs`) ###
`libpathrs` also provides a set of primitives to safely interact with `procfs`.
This is very important for some programs (such as container runtimes), because
`/proc` has several key system administration purposes that make it different
to other filesystems. It particular, `/proc` is used:
1. As a mechanism for doing certain filesystem operations through
`/proc/self/fd/...` (and other similar magic-links) that cannot be done by
other means.
1. As a source of true information about processes and the general system (such
as by looking `/proc/$pid/status`).
1. As an administrative tool for managing processes (such as setting LSM labels
like `/proc/self/attr/apparmor/exec`).
These operations have stronger requirements than regular filesystems. For (1)
we need to open the magic-link for real (magic-links are symlinks that are not
resolved lexically, they are in-kernel objects that warp you to other files
without doing a regular path lookup) which much harder to do safely (even with
`openat2`). For (2) and (3) we have the requirement that we need to open a
specific file, not just any file within `/proc` (if there are overmounts or
symlinks) which is not the case `pathrs_inroot_resolve()`. As a result, it is
necessary to take far more care when doing operations of `/proc` and
`libpathrs` provides very useful helper to do this. Failure to do so can lead
to security issues such as those in [CVE-2019-16884][cve-2019-16884] and
[CVE-2019-19921][cve-2019-19921].
In addition, with the [new mount API][lwn-newmount] ([`fsopen(2)`] and
[`open_tree(2)`] in particular, added in Linux 5.2), it is possible to get a
totally private `procfs` handle that can be used without worrying about racing
mount operations. `libpathrs` will try to use this if it can (this usually
requires root).
[cve-2019-16884]: https://nvd.nist.gov/vuln/detail/CVE-2019-16884
[cve-2019-19921]: https://nvd.nist.gov/vuln/detail/CVE-2019-19921
[lwn-newmount]: https://lwn.net/Articles/759499/
[`open_tree(2)`]: https://www.man7.org/linux/man-pages/man2/open_tree.2.html
[`fsopen(2)`]: https://www.man7.org/linux/man-pages/man2/fsopen.2.html
### Examples ###
The most common usage of the procfs API is writing to specific files in
`/proc`. The following are two examples that are adapted from real code in
container runtimes:
#### Rust ####
```rust
use pathrs::{
flags::OpenFlags,
procfs::{ProcfsBase, ProcfsHandle},
};
/// Configure the current process's AppArmor label.
fn write_apparmor_label(label: impl AsRef<[u8]>) -> Result<(), Error> {
ProcfsHandle::new()?
.open(
ProcfsBase::ProcSelf,
"attr/apparmor/exec",
// You should always use O_NOFOLLOW unless you are dealing with
// magic-links or otherwise really need to operate on a trailing
// symlink.
OpenFlags::O_WRONLY | OpenFlags::O_NOFOLLOW,
)?
.write_all(label.as_ref())?;
Ok(())
}
```
```rust
use std::path::Path;
use pathrs::{
flags::OpenFlags,
procfs::{ProcfsBase, ProcfsHandle},
};
/// Configure the given sysctl.
fn write_sysctl(name: impl AsRef<str>, value: impl AsRef<[u8]>) -> Result<(), Error> {
// /proc/sys/<key/name>
let key_path = Path::new("sys").join(name.as_ref().replace(".", "/"));
ProcfsHandle::new()?
.open(
ProcfsBase::ProcRoot,
key_path,
OpenFlags::O_WRONLY | OpenFlags::O_NOFOLLOW,
)?
.write_all(value.as_ref())?;
// If you need to do lots of these operations, you should use
// ProcfsHandleBuilder::unmasked() to create a temporary handle.
Ok(())
}
```
#### C #####
```c
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <pathrs.h>
/*
* Safely set the AppArmor exec label for the current process. This is
* something runc does while configuring the container process.
*/
int write_apparmor_label(const char *label)
{
int fd, err;
fd = pathrs_proc_open(PATHRS_PROC_SELF, "attr/apparmor/exec",
O_WRONLY|O_NOFOLLOW);
if (IS_PATHRS_ERR(fd)) {
pathrs_error_t *error = pathrs_errorinfo(fd);
/* ... print the error ... */
pathrs_errorinfo_free(error);
return -1;
}
err = write(fd, label, strlen(label));
close(fd);
return err;
}
```
```c
#define _GNU_SOURCE
#include <unistd.h>
#include <fcntl.h>
#include <stdio.h>
#include <string.h>
#include <pathrs.h>
/*
* Safely configure the given sysctl.
*/
int write_sysctl(const char *name, const char *value)
{
int fd, err;
char *path = NULL;
if (asprintf(&path, "sys/%s", name))
return -1;
for (char *p = path; *p; p++)
if (*p == '.')
*p = '/';
fd = pathrs_proc_open(PATHRS_PROC_ROOT, path,
O_WRONLY|O_NOFOLLOW);
free(path);
if (IS_PATHRS_ERR(fd)) {
pathrs_error_t *error = pathrs_errorinfo(fd);
/* ... print the error ... */
pathrs_errorinfo_free(error);
return -1;
}
err = write(fd, value, strlen(value));
close(fd);
return err;
}
```
#### Go ####
```go
import (
"cyphar.com/go-pathrs/procfs"
"golang.org/x/sys/unix"
)
// Configure the current process's AppArmor label.
func writeAppArmorLabel(label string) error {
proc, err := procfs.Open()
if err != nil {
return err
}
defer proc.Close()
// You should always use O_NOFOLLOW unless you are dealing with
// magic-links or otherwise really need to operate on a trailing
// symlink.
file, err := proc.OpenSelf("attr/apparmor/exec", unix.O_WRONLY|unix.O_NOFOLLOW)
if err != nil {
return err
}
defer file.Close()
_, err = file.WriteString(label)
return err
}
```
```go
import (
"strings"
"cyphar.com/go-pathrs/procfs"
"golang.org/x/sys/unix"
)
// Configure the given sysctl.
func writeSysctl(name, value string) error {
proc, err := procfs.Open()
if err != nil {
return err
}
defer proc.Close()
// /proc/sys/<key/name>
keyPath := "sys/" + strings.ReplaceAll(name, ".", "/")
file, err := proc.OpenRoot(keyPath, unix.O_WRONLY|unix.O_NOFOLLOW)
if err != nil {
return err
}
defer file.Close()
_, err = file.WriteString(value)
// If you need to do lots of these operations, you should use
// procfs.Open(procfs.UnmaskedProcRoot) to create a temporary handle.
return err
}
```
- - -
Another very powerful primitive is safe magic-link operations, which allow you
to operate on certain files with guarantees from the kernel that the object is
what you expect. Note that this operation (opening a magic-link) is the hardest
for us to secure and thus your security relies on you having privileges to be
able to call [`fsopen(2)`].
[`fsopen(2)`]: https://www.man7.org/linux/man-pages/man2/fsopen.2.html
#### Rust ####
```rust
use std::fs::File;
use pathrs::{
flags::OpenFlags,
procfs::{ProcfsBase, ProcfsHandle},
};
/// Safely get an fd to /proc/self/exe.
fn get_self_exe() -> Result<File, Error> {
let file = ProcfsHandle::new()?.open(
ProcfsBase::ProcSelf,
"exe",
OpenFlags::O_PATH, // no O_NOFOLLOW!
)?;
Ok(file)
}
```
#### C ####
```c
#include <unistd.h>
#include <fcntl.h>
#include <pathrs.h>
/*
* Safely get an fd to /proc/self/exe. This is something runc does to re-exec
* itself during the container setup process.
*/
int get_self_exe(void)
{
/* This follows the trailing magic-link! */
int fd = pathrs_proc_open(PATHRS_PROC_SELF, "exe", O_PATH);
if (IS_PATHRS_ERR(fd)) {
pathrs_error_t *error = pathrs_errorinfo(fd);
/* ... print the error ... */
pathrs_errorinfo_free(error);
return -1;
}
return fd;
}
```
#### Go ####
```go
import (
"os"
"cyphar.com/go-pathrs/procfs"
"golang.org/x/sys/unix"
)
// Safely get an fd to /proc/self/exe. This is something runc
// does to re-exec itself during the container setup process.
func getSelfExe() (*os.File, error) {
proc, err := procfs.Open()
if err != nil {
return nil, err
}
defer proc.Close()
// This follows the trailing magic-link -- no O_NOFOLLOW!
return proc.OpenSelf("exe", unix.O_PATH)
}
```
- - -
In some (rare) cases, you need to get the "real" path for a file descriptor.
This path MUST NOT be used for actual filesystem operations because it's
possible for an attacker to move the file or change one of the path components
to a symlink, which could lead to you operating on files you didn't expect
(including host files). Similarly, you should not use the pathname for
permissive security decisions because the attacker can always rename the file.
#### Rust ####
```rust
use std::{
os::fd::{AsFd, AsRawFd},
path::PathBuf,
};
use pathrs::procfs::{ProcfsBase, ProcfsHandle};
/// Get an *unstable* and *unsafe* path string for a file descriptor.
fn get_unsafe_path(fd: impl AsFd) -> Result<PathBuf, Error> {
let path = ProcfsHandle::new()?.readlink(
ProcfsBase::ProcThreadSelf,
format!("fd/{}", fd.as_fd().as_raw_fd()),
)?;
Ok(path)
}
```
#### C ####
```c
#define _GNU_SOURCE
#include <unistd.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <pathrs.h>
/*
* Get an *unstable* and *unsafe* path string for a file descriptor.
*
* In most cases, this kind of function would be used for diagnostic purposes
* (such as in error messages, to provide context about what file the error is
* in relation to).
*/
char *get_unsafe_path(int fd)
{
char *fdpath;
if (asprintf(&fdpath, "fd/%d", fd) < 0)
return NULL;
int linkbuf_size = 128;
char *linkbuf = malloc(size);
if (!linkbuf)
goto err;
for (;;) {
int len = pathrs_proc_readlink(PATHRS_PROC_THREAD_SELF,
fdpath, linkbuf, linkbuf_size);
if (IS_PATHRS_ERR(len)) {
pathrs_error_t *error = pathrs_errorinfo(fd);
/* ... print the error ... */
pathrs_errorinfo_free(error);
goto err;
}
if (len <= linkbuf_size)
break;
linkbuf_size = len;
linkbuf = realloc(linkbuf, linkbuf_size);
if (!linkbuf)
goto err;
}
free(fdpath);
return linkbuf;
err:
free(fdpath);
free(linkbuf);
return NULL;
}
```
#### Go ####
```go
import (
"fmt"
"cyphar.com/go-pathrs/procfs"
)
// Get an *unstable* and *unsafe* path string for a file descriptor.
//
// In most cases, this kind of function would be used for diagnostic
// purposes (such as in error messages, to provide context about what
// file the error is in relation to).
func getUnsafePath(fd int) (string, error) {
proc, err := procfs.Open()
if err != nil {
return "", err
}
defer proc.Close()
return proc.Readlink(procfs.ProcThreadSelf, fmt.Sprintf("fd/%d", fd))
}
```