filepath.Join won't protect against path traversal: breaking down os.OpenInRoot and GO-2026-4970 in GoArticle · digest for November 3
Architectural cutaway of a protected file container blocking Path Traversal attempts at the OS kernel level in Go.
Article5 sections≈ 7 min

filepath.Join won't protect against path traversal: breaking down os.OpenInRoot and GO-2026-4970 in Go

If you ask an average Go developer how to safely read a file whose name was passed by an external user in an HTTP request, the answer will almost certainly be boilerplate: "Take the base upload directory baseDir, join it with the filename via filepath.Join, and validate with filepath.Clean so there are no relative traversals like ../."

That classic recipe has been copied from one tutorial to another for a decade and a half. Yet in real production, it creates only a deceptive illusion of security. Simple lexical string manipulation ignores the physical nature of filesystems. As soon as a user uploads an archive containing a symbolic link or triggers a multithreaded race condition, your service obligingly reads the server's private keys or /etc/passwd.

To close this fundamental gap, the language authors added new low-level mechanisms to the standard os package: the os.OpenInRoot function and the os.Root type. Yet even in this implementation, security researchers uncovered a critical vulnerability: GO-2026-4970. Let's break down how this works from the ground up.

Why is the familiar filepath.Join(baseDir, userInput) helpless against sophisticated Path Traversal?

Two classic attack vectors are at play here:

  1. Hidden symbolic links (symlinks): imagine that inside /var/data/uploads there is a file avatar.png that is actually a symlink pointing to /etc/shadow. filepath.Join("/var/data/uploads", "avatar.png") will return a completely legitimate string /var/data/uploads/avatar.png. From a string parser's perspective, the path is strictly inside the allowed folder! Yet the subsequent os.Open() call transparently follows the link and hands the attacker system password hashes.
  2. Filesystem race conditions (TOCTOU — Time-of-Check to Time-of-Use): experienced engineers try to work around symlinks by calling filepath.EvalSymlinks before opening the file. But in multithreaded web services, a few microseconds pass between checking the path and physically calling os.Open. In a concurrent request, an attacker manages to delete the verified file and replace it with a symlink to the system root. Check passed, file opened, system compromised.

Trying to solve synchronization in user space is pointless: security must be guaranteed by the operating system kernel at the moment the file descriptor is resolved.

System level: how os.OpenInRoot works

os.OpenInRoot(dir, path) and os.OpenRoot(dir) move boundary enforcement from string manipulation down to kernel system calls.

On modern Linux versions (starting from kernel 5.6), this uses the openat2 syscall with the RESOLVE_BENEATH flag. That flag instructs the kernel's Virtual File System (VFS) to block any attempt to traverse above the directory identified by the base descriptor. If a path contains ../ or a symlink leading outside the filesystem subtree, the kernel immediately aborts the operation with EXDEV before a file descriptor is ever created.

os.OpenInRoot(baseDir, name) is designed for one-off operations: it opens a specific file, rejecting any escape attempts while still resolving internal symlinks if they stay within baseDir.

If a service needs to perform a series of operations — create a subdirectory, write temporary files, and read metadata — os.OpenRoot(dir) is used. It returns an *os.Root object that holds an open descriptor to the base folder and exposes safe Open, Create, OpenFile, Remove, and Stat methods.

Vulnerability GO-2026-4970: the trailing slash loophole

Kernel protection might seem invulnerable. In summer 2026, however, a critical security flaw was discovered in Go's standard library, tracked as GO-2026-4970 (CVE-2026-39822, Issue #79005).

The vulnerability triggered under a very specific combination of conditions:

  • inside an os.Root directory, there was a legitimate symbolic link to an external directory (for example, shared -> /opt/shared/data);
  • the user passed a path to that link with a mandatory trailing slash: root.Open("shared/").

Due to a subtlety in Go runtime path parsing, the trailing slash caused the kernel parser to interpret the access not as the symlink file itself, but as the directory it pointed to. As a result, RESOLVE_BENEATH was bypassed, and an attacker gained read access to files outside the sandbox.

The Go team promptly patched the flaw in toolchain point releases 1.25.12, 1.26.5, and pre-release 1.27.0-rc.2 (patch CL 797880). If your services use os.Root, updating the compiler version is critically mandatory.

Refactoring code: moving to os.OpenInRoot and os.OpenRoot

Let's look at what migrating from vulnerable lexical code to canonical safe Go style looks like:

package main

import (
    "fmt"
    "io"
    "os"
    "path/filepath"
)

// UNSAFE: vulnerable to symlinks and TOCTOU races
func unsafeReadFile(baseDir, userFilename string) ([]byte, error) {
    // filepath.Join will not protect against planted symlinks to /etc/passwd
    targetPath := filepath.Join(baseDir, userFilename)
    return os.ReadFile(targetPath)
}

// SAFE: atomic open via os.OpenInRoot
func safeReadSingleFile(baseDir, userFilename string) ([]byte, error) {
    // The OS kernel guarantees reading won't escape baseDir
    file, err := os.OpenInRoot(baseDir, userFilename)
    if err != nil {
        return nil, fmt.Errorf("access denied or invalid path: %w", err)
    }
    defer file.Close()

    return io.ReadAll(file)
}

And here is an example of safely working with a session directory via an os.Root descriptor:

// SAFE: isolated series of operations inside a directory
func safeProcessUploads(uploadDir, filename string, data []byte) error {
    root, err := os.OpenRoot(uploadDir)
    if err != nil {
        return fmt.Errorf("failed to lock directory root: %w", err)
    }
    defer root.Close()

    // All file methods are called relative to the open root
    out, err := root.Create(filename)
    if err != nil {
        return fmt.Errorf("failed to create file: %w", err)
    }
    defer out.Close()

    _, err = out.Write(data)
    return err
}

Documented boundaries of os.Root protection

When adopting os.Root, it's important to clearly understand the boundaries of its responsibility. It is a path isolation tool, not a full container like Docker:

  • Mount points: the method does not block traversals across mounted filesystems (mount points and Linux bind mounts) if they are physically located inside a trusted directory.
  • Pseudo-filesystems: if /proc or /dev is accidentally mounted inside the root, a client can gain access to system devices.
  • WebAssembly builds: when compiling for GOOS=js or GOOS=wasip1, hardware/kernel syscall support is absent. The Go runtime emulates path checks in user space, so protection in the browser remains potentially susceptible to races.
Minimum Go toolchain version

Make sure the build runtime in your CI/CD pipelines uses Go version 1.25.12 or 1.26.5 or newer. Using os.OpenInRoot on older builds leaves the directory traversal loophole via trailing slashes on symlinks open.

Moving to os.OpenInRoot permanently closes an entire class of Zip Slip and Path Traversal vulnerabilities. Forget filepath.Join when handling user-supplied paths — kernel descriptors work more reliably than any regular expressions.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 3