- Published on
Restrict Rust File Tools with cap-std Directory Capabilities
- Authors

- Name
- Mehdi Akiki
Article · Through the layers
The file tool has a sensible rule: only read files inside the current job directory. A directory capability gives the Rust helper a handle it can use for those reads. That is easier to follow through the code than a rule every caller must rebuild from path strings.
A tempting alternative is to resolve the requested path, check the result, then open the file.
There is a gap between those last two steps. If another process can change a directory entry during the gap, the file that gets opened may be different from the one that passed the check.
This is a possible failure in an ordinary file helper. We don't need to assume the agent has discovered a kernel exploit. We do need to ask who can change the paths the helper trusts.
The host report helper removes the model's destination argument entirely. A tool that must read user-selected files needs a different interface. This example limits the trusted helper's file access; the execution boundary around the agent remains a separate control.
A path is a request to look something up
Imagine a job containing input.txt and a symlink called current. The helper checks where current points. Later, it opens current again by name.
Checking and opening perform separate lookups. A rename or link change between them can matter. Keeping the earlier resolved string doesn't necessarily solve the problem either: an ancestor directory can change if the attacker controls it.
This family of mistakes is often called a time-of-check to time-of-use race. The name is longer than the basic idea. You approved one lookup and performed another.
Rejecting ../ is still useful input validation, but it doesn't answer what a symlink points to. Looking for suspicious characters also becomes an awkward way to express a filesystem policy.
For a trusted tool, a better starting point is an already-open directory and an API that keeps subsequent access inside the directory tree the tool was given.
Give the tool a directory capability
The Rust example uses cap-std, pinned to version 4.0.3. A directory capability is a handle through which the tool receives access to a particular directory tree. The helper can use that handle instead of starting each read from the host's unrestricted filesystem view.
Here is the small part that matters after trusted setup has created job:
use cap_std::{ambient_authority, fs::Dir};
use std::io;
use std::path::Path;
fn inspect_job(job: &Path) -> io::Result<()> {
let directory = Dir::open_ambient_dir(job, ambient_authority())?;
let text = directory.read_to_string("inside.txt")?;
assert_eq!(text, "dummy inside file");
assert!(directory.open("../outside.txt").is_err());
Ok(())
}
The trusted launcher chooses job. It must not accept an agent-supplied absolute directory and treat opening it as authorization.
The Dir reference describes the handle and its relative file operations. Keep accesses on that handle. Converting back to unrestricted std::fs operations would change the authority being used.
Trusted setup opens the job directory using the host process's filesystem access. The helper then receives that directory handle. The ambient_authority() marker makes that initial use of host access explicit; it doesn't create operating-system isolation.
What the demonstration actually checks
The complete Rust source creates a temporary directory containing a job folder and a dummy file outside it. The job contains permitted files, including a name with spaces.
Its read_input helper accepts a borrowed directory handle and a name. Every read uses directory.read_to_string(name). The checks cover normal reads, a missing file, a parent-directory traversal, and the absolute path to the dummy outside file. On Unix, it also creates a symlink inside the job pointing at the outside file and expects that read to fail.
That checks an existing symlink pointing outside the job. It doesn't reproduce a link being swapped while a read is in progress. The race at the start explains why separate path checks are fragile; the code here lets you inspect how the chosen API handles traversal and an outward link.
Review the error path with the same care as the successful read. If read_input fails and a caller retries with std::fs::read_to_string, the second call has silently switched back to the host process's filesystem authority. Return the read error or choose another explicitly authorized input. An unrestricted fallback makes the narrow helper optional at exactly the moment an attacker wants to avoid it.
A library cannot confine arbitrary Rust
If the agent can run arbitrary code in the same unrestricted host process, it can simply avoid the helper. Calling std::fs::read doesn't require permission from your Dir variable.
This technique belongs in the trusted tool serving a separately contained agent. The operating system still needs to restrict the agent's own filesystem access. The tool's directory capability narrows what the tool can do on its behalf.
Also decide who can alter the job directory, how it is mounted, whether other jobs can write into it, and what inherited handles the tool already has. A carefully chosen read API doesn't repair a shared writable workspace containing another customer's files.
Keep failure cases next to the permitted read
Before exposing the helper, check a normal file, a missing file, a parent traversal, and a link pointing outside the job. Include your supported platform and filesystem in remote verification; path behavior is a poor place to assume portability.
Keep the allowed operation visible too. A helper that denies every path has passed a security-looking test while breaking the product.
The useful change here is small enough to review: the helper receives one directory handle and performs its reads through it. You can follow that handle through the code. That is much easier than trusting every future caller to remember the same sequence of string checks.