profile

Documentation

Index

• Constants
• Variables
• func CanonicalRoot(path string) (string, error)
• func PathWithin(path, root string) bool
• type Access
• type CompileReport
• type Guarantees
  • func GuaranteesFromBits(bits uint64) Guarantees
  • func (g Guarantees) Bits() uint64
• type Home
• type Isolation
• type Profile
  • func NewProfile(config ProfileConfig) (*Profile, error)
  • func Restrict(base, ceiling *Profile) (*Profile, error)
  • func (p *Profile) AccessFor(kind, scope string) (uint8, error)
  • func (p *Profile) AccessVersion() uint16
  • func (p *Profile) Fingerprint() string
  • func (p *Profile) Settings() Settings
  • func (p *Profile) Validate() error
• type ProfileConfig
• type ReportEntry
• type RootAccess
• type Settings

Constants

const (
	LevelNone uint8 = iota
	LevelDegraded
	LevelFull
)

const (
	GuaranteeProcessBoundary uint64 = 1 << iota
	GuaranteeWriteBoundary
	GuaranteeReadBoundary
	GuaranteeEnvScrub
	GuaranteeNetworkBoundary
	GuaranteeAddressNetwork
	GuaranteeResourceLimits
	GuaranteeTargetNetwork
)

Variables

var ErrInvalidProfile = errors.New("sandbox: invalid profile")

ErrInvalidProfile identifies malformed, unconstructed, or inconsistent profiles. Details are wrapped for diagnostics; callers may use errors.Is.

Functions

func CanonicalRoot

func CanonicalRoot(path string) (string, error)

CanonicalRoot resolves path to an absolute, symlink-free, existing directory. It is the canonicalization every configured root is held to.

func PathWithin

func PathWithin(path, root string) bool

PathWithin reports whether path is root itself or lies beneath it.

Types

type Access

type Access uint8

Access is the requested authority for one profile capability.

const (
	Deny  Access = 0
	Gated Access = 1
	Allow Access = 2
)

type CompileReport

type CompileReport struct {
	Entries []ReportEntry
}

CompileReport records enforced, narrowed, and unavailable features.

type Guarantees

type Guarantees struct {
	ProcessBoundary bool
	WriteBoundary   bool
	ReadBoundary    bool
	EnvScrub        bool
	NetworkBoundary bool
	AddressNetwork  bool
	ResourceLimits  bool
	TargetNetwork   bool
}

Guarantees reports properties actually enforced by the selected backend.

func GuaranteesFromBits

func GuaranteesFromBits(bits uint64) Guarantees

GuaranteesFromBits expands a backend guarantee bitmask into its named form.

func (Guarantees) Bits

func (g Guarantees) Bits() uint64

Bits packs named guarantees back into the bitmask backends report.

type Home

type Home uint8

Home selects the HOME value exposed to a child process.

const (
	IsolatedHome Home = iota
	RealHome
)

type Isolation

type Isolation uint8

Isolation selects whether process authority is OS-confined.

const (
	Sandboxed Isolation = iota
	Unconfined
)

type Profile

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

Profile is an immutable, normalized access profile.

func NewProfile

func NewProfile(config ProfileConfig) (*Profile, error)

NewProfile validates, canonicalizes, and owns a copy of config.

func Restrict

func Restrict(base, ceiling *Profile) (*Profile, error)

Restrict returns the component-wise intersection of base and ceiling.

func (*Profile) AccessFor

func (p *Profile) AccessFor(kind, scope string) (uint8, error)

AccessFor returns the fixed numeric Access value for a normalized kind/scope.

func (*Profile) AccessVersion

func (p *Profile) AccessVersion() uint16

AccessVersion reports the primitive profile ABI. An unconstructed Profile reports zero, which consumers must reject as unsupported.

func (*Profile) Fingerprint

func (p *Profile) Fingerprint() string

Fingerprint returns the deterministic digest of all normalized authority.

func (*Profile) Settings

func (p *Profile) Settings() Settings

Settings returns the normalized authority of a validated Profile. An unconstructed or invalid Profile reports the zero Settings, whose Version is zero and which callers must reject as unsupported.

func (*Profile) Validate

func (p *Profile) Validate() error

Validate reports whether p was constructed by NewProfile and carries the current ABI. It returns ErrInvalidProfile for a nil, zero, or stale Profile.

type ProfileConfig

type ProfileConfig struct {
	WorkspaceRoot   string
	WorkspaceRead   Access
	WorkspaceWrite  Access
	HostRead        Access
	HostWrite       Access
	Network         Access
	Command         Access
	Home            Home
	Isolation       Isolation
	AdditionalRoots []RootAccess
	AckUnconfined   bool
}

ProfileConfig contains every consumer-selected sandbox authority value.

type ReportEntry

type ReportEntry struct {
	Feature string
	Status  string
	Detail  string
}

ReportEntry records how one requested feature was compiled by a backend.

type RootAccess

type RootAccess struct {
	Path  string
	Read  Access
	Write Access
}

RootAccess describes read and write authority for one additional root.

type Settings

type Settings struct {
	Version            uint16
	WorkspaceRoot      string
	WorkspaceRead      Access
	WorkspaceWrite     Access
	HostRead           Access
	HostWrite          Access
	Network            Access
	Command            Access
	Home               Home
	Isolation          Isolation
	AdditionalRoots    []RootAccess
	AckUnconfined      bool
	RequiredGuarantees uint64
	Fingerprint        string
}

Settings is the normalized, read-only view of every authority value a Profile carries. It exists so packages outside this one can compile a Profile without reaching into its unexported fields, which keeps the Profile itself immutable: Settings is a copy, and mutating it cannot affect the Profile it came from.