botfs

Documentation

Index

• Constants
• func ConfigureACL(path string, owner *user.User, opts *ACLOptions) error
• func Create(path string, isDir bool, symlinksMode SymlinksMode) error
• func GetOwner(fileInfo fs.FileInfo) (*user.User, error)
• func HasACLSupport() bool
• func HasSecureWriteSupport() bool
• func IsOwnedBy(fileInfo fs.FileInfo, user *user.User) (bool, error)
• func Read(path string, symlinksMode SymlinksMode) ([]byte, error)
• func VerifyACL(path string, opts *ACLOptions) error
• func Write(path string, data []byte, symlinksMode SymlinksMode) error
• type ACLMode
• type ACLOptions
• type OpenMode
• type SymlinksMode

Constants

const (
	// DefaultMode is the preferred permissions mode for bot files.
	DefaultMode fs.FileMode = 0600

	// DefaultDirMode is the preferred permissions mode for bot directories.
	// Directories need the execute bit set for most operations on their
	// contents to succeed.
	DefaultDirMode fs.FileMode = 0700

	// ReadMode is the mode with which files should be opened for reading and
	// writing.
	ReadMode OpenMode = OpenMode(os.O_CREATE | os.O_RDONLY)

	// WriteMode is the mode with which files should be opened specifically
	// for writing.
	WriteMode OpenMode = OpenMode(os.O_CREATE | os.O_WRONLY | os.O_TRUNC)
)

const Openat2MinKernel = "5.6.0"

Openat2MinKernel is the kernel release that adds support for the openat2() syscall.

Functions

func ConfigureACL

func ConfigureACL(path string, owner *user.User, opts *ACLOptions) error

ConfigureACL configures ACLs of the given file to allow writes from the bot user.

func Create

func Create(path string, isDir bool, symlinksMode SymlinksMode) error

Create attempts to create the given file or directory with the given symlinks mode.

func GetOwner

func GetOwner(fileInfo fs.FileInfo) (*user.User, error)

GetOwner attempts to retrieve the owner of the given file. This is not supported on all platforms and will return a trace.NotImplemented in that case.

func HasACLSupport

func HasACLSupport() bool

HasACLSupport determines if this binary / system supports ACLs.

func HasSecureWriteSupport

func HasSecureWriteSupport() bool

HasSecureWriteSupport determines if `CreateSecure()` should be supported on this OS / kernel version. Note that it just checks the kernel version, so this should be treated as a fallible hint.

We've encountered this being incorrect in environments where access to the kernel is hampered e.g. seccomp/apparmor/container runtimes.

func IsOwnedBy

func IsOwnedBy(fileInfo fs.FileInfo, user *user.User) (bool, error)

IsOwnedBy checks that the file at the given path is owned by the given user. Returns a trace.NotImplemented() on unsupported platforms.

func Read

func Read(path string, symlinksMode SymlinksMode) ([]byte, error)

Read reads the contents of the given file into memory.

func VerifyACL

func VerifyACL(path string, opts *ACLOptions) error

VerifyACL verifies whether the ACL of the given file allows writes from the bot user. Errors may optionally be used as more informational warnings; ConfigureACL can be used to correct them, assuming the user has permissions.

func Write

func Write(path string, data []byte, symlinksMode SymlinksMode) error

Write stores the given data to the file at the given path.

Types

type ACLMode

type ACLMode string

ACLMode is an enum type listing various ACL behavior modes.

const (
	// ACLOff disables ACLs
	ACLOff ACLMode = "off"

	// ACLTry attempts to use ACLs but falls back to no ACLs with a warning if
	// unavailable.
	ACLTry ACLMode = "try"

	// ACLRequired enables ACL support and fails if ACLs are unavailable.
	ACLRequired ACLMode = "required"
)

type ACLOptions

type ACLOptions struct {
	// BotUser is the bot user that should have write access to this entry
	BotUser *user.User

	// ReaderUser is the user that should have read access to the file. This
	// may be nil if the reader user is not known.
	ReaderUser *user.User
}

ACLOptions contains parameters needed to configure ACLs

type OpenMode

type OpenMode int

OpenMode is a mode for opening files.

type SymlinksMode

type SymlinksMode string

SymlinksMode is an enum type listing various symlink behavior modes.

const (
	// SymlinksInsecure does allow resolving symlink paths and does not issue
	// any symlink-related warnings.
	SymlinksInsecure SymlinksMode = "insecure"

	// SymlinksTrySecure attempts to write files securely and avoid symlink
	// attacks, but falls back with a warning if the necessary OS / kernel
	// support is missing.
	SymlinksTrySecure SymlinksMode = "try-secure"

	// SymlinksSecure attempts to write files securely and fails with an error
	// if the operation fails. This should be the default on systems where we
	// expect it to be supported.
	SymlinksSecure SymlinksMode = "secure"
)