fs

Documentation

Overview

Package securejoin is an implementation of the hopefully-soon-to-be-included SecureJoin helper that is meant to be part of the "path/filepath" package. The purpose of this project is to provide a PoC implementation to make the SecureJoin proposal (https://github.com/golang/go/issues/20126) more tangible.

Index

• func IsNotExist(err error) bool
• func New(workingDir string) billy.Filesystem
• func SecureJoin(root, unsafePath string) (string, error)
• func SecureJoinVFS(root, unsafePath string, vfs VFS) (string, error)
• type OS
  • func (fs *OS) Chroot(path string) (billy.Filesystem, error)
  • func (fs *OS) Create(filename string) (billy.File, error)
  • func (fs *OS) Join(elem ...string) string
  • func (fs *OS) Lstat(filename string) (os.FileInfo, error)
  • func (fs *OS) MkdirAll(path string, perm os.FileMode) error
  • func (fs *OS) Open(filename string) (billy.File, error)
  • func (fs *OS) OpenFile(filename string, flag int, perm os.FileMode) (billy.File, error)
  • func (fs *OS) ReadDir(path string) ([]os.FileInfo, error)
  • func (fs *OS) Readlink(link string) (string, error)
  • func (fs *OS) Remove(filename string) error
  • func (fs *OS) RemoveAll(path string) error
  • func (fs *OS) Rename(from, to string) error
  • func (fs *OS) Root() string
  • func (fs *OS) Stat(filename string) (os.FileInfo, error)
  • func (fs *OS) Symlink(target, link string) error
  • func (fs *OS) TempFile(dir, prefix string) (billy.File, error)
• type VFS

Functions

func IsNotExist

func IsNotExist(err error) bool

IsNotExist tells you if err is an error that implies that either the path accessed does not exist (or path components don't exist). This is effectively a more broad version of os.IsNotExist.

func New

func New(workingDir string) billy.Filesystem

New returns a new OS filesystem using the workingDir as prefix for relative paths. It also ensures that operations are kept within that working dir.

func SecureJoin

func SecureJoin(root, unsafePath string) (string, error)

SecureJoin is a wrapper around SecureJoinVFS that just uses the os.* library of functions as the VFS. If in doubt, use this function over SecureJoinVFS.

func SecureJoinVFS

func SecureJoinVFS(root, unsafePath string, vfs VFS) (string, error)

SecureJoinVFS joins the two given path components (similar to Join) except that the returned path is guaranteed to be scoped inside the provided root path (when evaluated). Any symbolic links in the path are evaluated with the given root treated as the root of the filesystem, similar to a chroot. The filesystem state is evaluated through the given VFS interface (if nil, the standard os.* family of functions are used).

Note that the guarantees provided by this function only apply if the path components in the returned string are not modified (in other words are not replaced with symlinks on the filesystem) after this function has returned. Such a symlink race is necessarily out-of-scope of SecureJoin.

Types

type OS

type OS struct {
	// contains filtered or unexported fields
}

OS is a fs implementation based on the OS filesystem which has some changes in behaviour when compared to the upstream go-git/go-billy/v5/osfs:

- Chroot doesn't return a chrooted filesystem but returns a new OS filesystem. - Relative paths are forced to descend from the working dir. - Symlinks don't have its targets modified, and therefore can point to locations outside the working dir or to non-existent paths. - OpenFile honours the FileMode passed as argument. - ReadLink and Lstat does not follow symlinks as most other funcs do. However, it ensures that:

a) The filename is located within the current dir.
b) The dir in which filename is based, is located within the current dir.

func (*OS) Chroot

func (fs *OS) Chroot(path string) (billy.Filesystem, error)

Chroot returns a new OS filesystem, with working directory set to path.

func (*OS) Create

func (fs *OS) Create(filename string) (billy.File, error)

func (*OS) Join

func (fs *OS) Join(elem ...string) string

func (*OS) Lstat

func (fs *OS) Lstat(filename string) (os.FileInfo, error)

func (*OS) MkdirAll

func (fs *OS) MkdirAll(path string, perm os.FileMode) error

func (*OS) Open

func (fs *OS) Open(filename string) (billy.File, error)

func (*OS) OpenFile

func (fs *OS) OpenFile(filename string, flag int, perm os.FileMode) (billy.File, error)

func (*OS) ReadDir

func (fs *OS) ReadDir(path string) ([]os.FileInfo, error)

func (*OS) Readlink

func (fs *OS) Readlink(link string) (string, error)

func (*OS) Remove

func (fs *OS) Remove(filename string) error

func (*OS) RemoveAll

func (fs *OS) RemoveAll(path string) error

func (*OS) Rename

func (fs *OS) Rename(from, to string) error

func (*OS) Root

func (fs *OS) Root() string

Root returns the current working dir of the billy.Filesystem. This is required in order for this implementation to be a drop-in replacement for other upstream implementations (e.g. memory and osfs).

func (*OS) Stat

func (fs *OS) Stat(filename string) (os.FileInfo, error)

func (*OS) Symlink

func (fs *OS) Symlink(target, link string) error

func (*OS) TempFile

func (fs *OS) TempFile(dir, prefix string) (billy.File, error)

TempFile creates a temporary file. If dir is empty, the file will be created within the OS Temporary dir. If dir is provided it must descend from the current working dir.

type VFS

type VFS interface {
	// Lstat returns a FileInfo describing the named file. If the file is a
	// symbolic link, the returned FileInfo describes the symbolic link. Lstat
	// makes no attempt to follow the link. These semantics are identical to
	// os.Lstat.
	Lstat(name string) (os.FileInfo, error)

	// Readlink returns the destination of the named symbolic link. These
	// semantics are identical to os.Readlink.
	Readlink(name string) (string, error)
}

VFS is the minimal interface necessary to use SecureJoinVFS. A nil VFS is equivalent to using the standard os.* family of functions. This is mainly used for the purposes of mock testing, but also can be used to otherwise use SecureJoin with VFS-like system.