fspolicy

Documentation

Index

• Variables
• type FSPolicy
  • func New(workBaseDir string, allowedRoots []string, blockSymlinks bool) (FSPolicy, error)
  • func (p FSPolicy) AllowedRoots() []string
  • func (p FSPolicy) BlockSymlinks() bool
  • func (p FSPolicy) EnsureDirResolved(absDir string, maxNewDirs int) (created int, err error)
  • func (p FSPolicy) HasAllowedRoots() bool
  • func (p FSPolicy) RequireExistingRegularFileResolved(absPath string) (fs.FileInfo, error)
  • func (p FSPolicy) ResolvePath(inputPath, defaultIfEmpty string) (string, error)
  • func (p FSPolicy) VerifyDirResolved(absDir string) error
  • func (p FSPolicy) WorkBaseDir() string

Variables

var (
	// ErrInvalidPath is returned for empty/whitespace paths or paths containing NUL bytes.
	ErrInvalidPath = errors.New("invalid path")

	// ErrOutsideAllowedRoots indicates a path (after best-effort canonicalization)
	// is not inside any configured allowed root.
	ErrOutsideAllowedRoots = errors.New("path is outside allowed roots")

	// ErrSymlinkDisallowed indicates the policy forbids symlink traversal / operation.
	ErrSymlinkDisallowed = errors.New("symlinks are disallowed by policy")
)

Types

type FSPolicy

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

FSPolicy centralizes filesystem path resolution and hardening.

Key rules:

• If allowedRoots is empty => allow all paths.
• Relative paths resolve against workBaseDir.
• Allowed-root checks are performed against a best-effort symlink-resolved path, but ResolvePath returns a lexical absolute path so Lstat-based checks can still detect symlink inputs.
• If blockSymlinks is true, directory traversal refuses symlink components and file operations can refuse symlink files (depending on caller and method).

func New

func New(workBaseDir string, allowedRoots []string, blockSymlinks bool) (FSPolicy, error)

New initializes a hardened filesystem policy. It canonicalizes allowed roots and work base dir and validates that base dir exists. If workBaseDir is empty:

• if allowedRoots is set => defaults to allowedRoots[0]
• else => defaults to process CWD

func (FSPolicy) AllowedRoots

func (p FSPolicy) AllowedRoots() []string

AllowedRoots returns a copy of the canonical allowed roots slice.

func (FSPolicy) BlockSymlinks

func (p FSPolicy) BlockSymlinks() bool

func (FSPolicy) EnsureDirResolved

func (p FSPolicy) EnsureDirResolved(absDir string, maxNewDirs int) (created int, err error)

EnsureDirResolved ensures an already-resolved absolute directory exists. It does NOT call ResolvePath again; callers should pass a value returned from ResolvePath (or otherwise already policy-checked).

If BlockSymlinks is true, it creates missing components one-at-a-time, refusing symlink traversal. MaxNewDirs: 0 => unlimited.

func (FSPolicy) HasAllowedRoots

func (p FSPolicy) HasAllowedRoots() bool

func (FSPolicy) RequireExistingRegularFileResolved

func (p FSPolicy) RequireExistingRegularFileResolved(absPath string) (fs.FileInfo, error)

RequireExistingRegularFileResolved requires an already-resolved absolute path exists and is a regular file. It does NOT call ResolvePath again; callers should pass a value returned from ResolvePath (or otherwise already policy-checked).

If BlockSymlinks is true, it refuses symlink parent components and a symlink final file.

func (FSPolicy) ResolvePath

func (p FSPolicy) ResolvePath(inputPath, defaultIfEmpty string) (string, error)

ResolvePath resolves inputPath (absolute or relative) into an absolute lexical path. DefaultIfEmpty is used if inputPath is blank.

func (FSPolicy) VerifyDirResolved

func (p FSPolicy) VerifyDirResolved(absDir string) error

VerifyDirResolved verifies an already-resolved absolute directory path. It does NOT call ResolvePath again; callers should pass a value returned from ResolvePath (or otherwise already policy-checked).

If BlockSymlinks is true, it refuses any symlink components in the path.

func (FSPolicy) WorkBaseDir

func (p FSPolicy) WorkBaseDir() string