1// SPDX-License-Identifier: BSD-3-Clause
 2
 3// Copyright (C) 2014-2015 Docker Inc & Go Authors. All rights reserved.
 4// Copyright (C) 2017-2024 SUSE LLC. All rights reserved.
 5// Use of this source code is governed by a BSD-style
 6// license that can be found in the LICENSE file.
 7
 8// Package securejoin implements a set of helpers to make it easier to write Go
 9// code that is safe against symlink-related escape attacks. The primary idea
10// is to let you resolve a path within a rootfs directory as if the rootfs was
11// a chroot.
12//
13// securejoin has two APIs, a "legacy" API and a "modern" API.
14//
15// The legacy API is [SecureJoin] and [SecureJoinVFS]. These methods are
16// **not** safe against race conditions where an attacker changes the
17// filesystem after (or during) the [SecureJoin] operation.
18//
19// The new API is available in the [pathrs-lite] subpackage, and provide
20// protections against racing attackers as well as several other key
21// protections against attacks often seen by container runtimes. As the name
22// suggests, [pathrs-lite] is a stripped down (pure Go) reimplementation of
23// [libpathrs]. The main APIs provided are [OpenInRoot], [MkdirAll], and
24// [procfs.Handle] -- other APIs are not planned to be ported. The long-term
25// goal is for users to migrate to [libpathrs] which is more fully-featured.
26//
27// securejoin has been used by several container runtimes (Docker, runc,
28// Kubernetes, etc) for quite a few years as a de-facto standard for operating
29// on container filesystem paths "safely". However, most users still use the
30// legacy API which is unsafe against various attacks (there is a fairly long
31// history of CVEs in dependent as a result). Users should switch to the modern
32// API as soon as possible (or even better, switch to libpathrs).
33//
34// This project was initially intended to be included in the Go standard
35// library, but it was rejected (see https://go.dev/issue/20126). Much later,
36// [os.Root] was added to the Go stdlib that shares some of the goals of
37// filepath-securejoin. However, its design is intended to work like
38// openat2(RESOLVE_BENEATH) which does not fit the usecase of container
39// runtimes and most system tools.
40//
41// [pathrs-lite]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite
42// [libpathrs]: https://github.com/openSUSE/libpathrs
43// [OpenInRoot]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite#OpenInRoot
44// [MkdirAll]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite#MkdirAll
45// [procfs.Handle]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite/procfs#Handle
46// [os.Root]: https:///pkg.go.dev/os#Root
47package securejoin