seccheck

package
v0.0.0-...-989fa2c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 26, 2023 License: Apache-2.0, MIT Imports: 14 Imported by: 0

Documentation

Overview

Package seccheck defines a structure for dynamically-configured security checks in the sentry.

Index

Constants

View Source
const DefaultSessionName = "Default"

DefaultSessionName is the name of the only session that can exist in the system for now. When multiple sessions are supported, this can be removed.

View Source
const (
	// FieldSyscallExecveEnvv is an optional field to collect list of environment
	// variables. Start after FieldSyscallPath because execveat(2) can collect
	// path from FD.
	FieldSyscallExecveEnvv = FieldSyscallPath + 1
)

Fields for execve*(2) syscalls.

Variables

View Source
var Points = map[string]PointDesc{}

Points is a map with all the trace points registered in the system.

View Source
var Sinks = map[string]SinkDesc{}

Sinks is a map with all the sinks registered in the system.

Functions

func Create

func Create(conf *SessionConfig, force bool) error

Create reads the session configuration and applies it to the system.

func Delete

func Delete(name string) error

Delete deletes an existing session.

func Initialize

func Initialize()

Initialize initializes the Points available in the system. Must be called prior to using any of them.

func List

func List(out *[]SessionConfig)

List lists all existing sessions.

func RegisterSink

func RegisterSink(sink SinkDesc)

RegisterSink registers a new sink to make it discoverable.

func SetupSinks

func SetupSinks(sinks []SinkConfig) ([]*os.File, error)

SetupSinks runs the setup step of all sinks in the configuration.

Types

type Field

type Field uint

Field represents the index of a single optional field to be collect for a Point.

const (
	FieldCtxtContainerID Field = iota
	FieldCtxtCredentials
	FieldCtxtCwd
	FieldCtxtProcessName
	FieldCtxtThreadGroupID
	FieldCtxtThreadGroupStartTime
	FieldCtxtThreadID
	FieldCtxtThreadStartTime
	FieldCtxtTime
)

FieldCtxtX represents a data field that comes from the Context.

const (
	// FieldContainerStartEnv is an optional field to collect list of environment
	// variables set for the container start process.
	FieldContainerStartEnv Field = iota
)

Fields for container/start point.

const (
	// FieldSentryExecveBinaryInfo is an optional field to collect information
	// about the binary being executed.
	FieldSentryExecveBinaryInfo Field = iota
)

Fields for sentry/execve point.

const (
	// FieldSyscallPath is an optional field to collect path from an FD. Given
	// that many syscalls operate on FDs, this const is used across syscalls.
	FieldSyscallPath Field = iota
)

Fields that are common for many syscalls.

type FieldDesc

type FieldDesc struct {
	// ID is the numeric identifier of the field.
	ID Field
	// Name is the unique field name.
	Name string
}

FieldDesc describes an optional/context field that is available to be configured.

type FieldMask

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

FieldMask is a bitmask with a single bit representing an optional field to be collected. The meaning of each bit varies per point. The mask is currently limited to 64 fields. If more are needed, FieldMask can be expanded to support additional fields.

func MakeFieldMask

func MakeFieldMask(fields ...Field) FieldMask

MakeFieldMask creates a FieldMask from a set of Fields.

func (*FieldMask) Add

func (fm *FieldMask) Add(field Field)

Add adds a Field to the mask.

func (*FieldMask) Contains

func (fm *FieldMask) Contains(field Field) bool

Contains returns true if the mask contains the Field.

func (*FieldMask) Empty

func (fm *FieldMask) Empty() bool

Empty returns true if no bits are set.

func (*FieldMask) Remove

func (fm *FieldMask) Remove(field Field)

Remove removes a Field from the mask.

type FieldSet

type FieldSet struct {
	// Local indicates which optional fields from the Point that needs to be
	// collected, e.g. resolving path from an FD, or collecting a large field.
	Local FieldMask

	// Context indicates which optional fields from the Context that needs to be
	// collected, e.g. PID, credentials, current time.
	Context FieldMask
}

FieldSet contains all optional fields to be collected by a given Point.

type Point

type Point uint

A Point represents a checkpoint, a point at which a security check occurs.

const (
	PointClone Point = iota
	PointContainerStart
	PointExecve
	PointExitNotifyParent
	PointTaskExit
)

PointX represents the checkpoint X.

func GetPointForSyscall

func GetPointForSyscall(typ SyscallType, sysno uintptr) Point

GetPointForSyscall translates the syscall number to the corresponding Point.

type PointConfig

type PointConfig struct {
	// Name is the point to be enabled. The point must exist in the system.
	Name string `json:"name,omitempty"`
	// OptionalFields is the list of optional fields to collect from the point.
	OptionalFields []string `json:"optional_fields,omitempty"`
	// ContextFields is the list of context fields to collect.
	ContextFields []string `json:"context_fields,omitempty"`
}

PointConfig describes a point to be enabled in a given session.

type PointDesc

type PointDesc struct {
	// ID is the point unique identifier.
	ID Point
	// Name is the point unique name. Convention is to use the following format:
	// namespace/name
	// Examples: container/start, sentry/clone, etc.
	Name string
	// OptionalFields is a list of fields that are available in the point, but not
	// collected unless specified when the Point is configured.
	// Examples: fd_path, data for read/write Points, etc.
	OptionalFields []FieldDesc
	// ContextFields is a list of fields that can be collected from the context,
	// but are not collected unless specified when the Point is configured.
	// Examples: container_id, PID, etc.
	ContextFields []FieldDesc
}

PointDesc describes a Point that is available to be configured. Schema for these points are defined in pkg/sentry/seccheck/points/.

type PointReq

type PointReq struct {
	Pt     Point
	Fields FieldSet
}

PointReq indicates what Point a corresponding Sink runs at, and what information it requires at those Points.

type SessionConfig

type SessionConfig struct {
	// Name is the unique session name.
	Name string `json:"name,omitempty"`
	// Points is the set of points to enable in this session.
	Points []PointConfig `json:"points,omitempty"`
	// IgnoreMissing skips point and optional/context fields not found. This can
	// be used to apply a single configuration file with newer points/fields with
	// older versions which do not have them yet. Note that it may hide typos in
	// the configuration.
	//
	// This field does NOT apply to sinks.
	IgnoreMissing bool `json:"ignore_missing,omitempty"`
	// Sinks are the sinks that will process the points enabled above.
	Sinks []SinkConfig `json:"sinks,omitempty"`
}

SessionConfig describes a new session configuration. A session consists of a set of points to be enabled and sinks where the points are sent to.

type Sink

type Sink interface {
	// Name return the sink name.
	Name() string
	// Status returns the sink runtime status.
	Status() SinkStatus
	// Stop requests the sink to stop.
	Stop()

	Clone(ctx context.Context, fields FieldSet, info *pb.CloneInfo) error
	Execve(ctx context.Context, fields FieldSet, info *pb.ExecveInfo) error
	ExitNotifyParent(ctx context.Context, fields FieldSet, info *pb.ExitNotifyParentInfo) error
	TaskExit(context.Context, FieldSet, *pb.TaskExit) error

	ContainerStart(context.Context, FieldSet, *pb.Start) error

	Syscall(context.Context, FieldSet, *pb.ContextData, pb.MessageType, proto.Message) error
	RawSyscall(context.Context, FieldSet, *pb.Syscall) error
}

A Sink performs security checks at checkpoints.

Each Sink method X is called at checkpoint X; if the method may return a non-nil error and does so, it causes the checked operation to fail immediately (without calling subsequent Sinks) and return the error. The info argument contains information relevant to the check. The mask argument indicates what fields in info are valid; the mask should usually be a superset of fields requested by the Sink's corresponding PointReq, but may be missing requested fields in some cases (e.g. if the Sink is registered concurrently with invocations of checkpoints).

func SeqAtomicLoadSinkSlice

func SeqAtomicLoadSinkSlice(seq *sync.SeqCount, ptr *[]Sink) []Sink

SeqAtomicLoad returns a copy of *ptr, ensuring that the read does not race with any writer critical sections in seq.

func SeqAtomicTryLoadSinkSlice

func SeqAtomicTryLoadSinkSlice(seq *sync.SeqCount, epoch sync.SeqCountEpoch, ptr *[]Sink) (val []Sink, ok bool)

SeqAtomicTryLoad returns a copy of *ptr while in a reader critical section in seq initiated by a call to seq.BeginRead() that returned epoch. If the read would race with a writer critical section, SeqAtomicTryLoad returns (unspecified, false).

type SinkConfig

type SinkConfig struct {
	// Name is the sink to be created. The sink must exist in the system.
	Name string `json:"name,omitempty"`
	// Config is a opaque json object that is passed to the sink.
	Config map[string]any `json:"config,omitempty"`
	// IgnoreSetupError makes errors during sink setup to be ignored. Otherwise,
	// failures will prevent the container from starting.
	IgnoreSetupError bool `json:"ignore_setup_error,omitempty"`
	// Status is the runtime status for the sink.
	Status SinkStatus `json:"status,omitempty"`
	// FD is the endpoint returned from Setup. It may be nil.
	FD *fd.FD `json:"-"`
}

SinkConfig describes the sink that will process the points in a given session.

type SinkDefaults

type SinkDefaults struct{}

SinkDefaults may be embedded by implementations of Sink to obtain no-op implementations of Sink methods that may be explicitly overridden.

func (SinkDefaults) Clone

Clone implements Sink.Clone.

func (SinkDefaults) ContainerStart

func (SinkDefaults) ContainerStart(context.Context, FieldSet, *pb.Start) error

ContainerStart implements Sink.ContainerStart.

func (SinkDefaults) Execve

Execve implements Sink.Execve.

func (SinkDefaults) ExitNotifyParent

ExitNotifyParent implements Sink.ExitNotifyParent.

func (SinkDefaults) RawSyscall

RawSyscall implements Sink.RawSyscall.

func (SinkDefaults) Status

func (SinkDefaults) Status() SinkStatus

Status implements Sink.Status.

func (SinkDefaults) Stop

func (SinkDefaults) Stop()

Stop implements Sink.Stop.

func (SinkDefaults) Syscall

Syscall implements Sink.Syscall.

func (SinkDefaults) TaskExit

TaskExit implements Sink.TaskExit.

type SinkDesc

type SinkDesc struct {
	// Name is a unique identifier for the sink.
	Name string
	// Setup is called outside the protection of the sandbox. This is done to
	// allow the sink to do whatever is necessary to set it up. If it returns a
	// file, this file is donated to the sandbox and passed to the sink when New
	// is called. config is an opaque json object passed to the sink.
	Setup func(config map[string]any) (*os.File, error)
	// New creates a new sink. config is an opaque json object passed to the sink.
	// endpoing is a file descriptor to the file returned in Setup. It's set to -1
	// if Setup returned nil.
	New func(config map[string]any, endpoint *fd.FD) (Sink, error)
}

SinkDesc describes a sink that is available to be configured.

type SinkStatus

type SinkStatus struct {
	// DroppedCount is the number of trace points dropped.
	DroppedCount uint64
}

SinkStatus represents stats about each Sink instance.

type State

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

State is the type of global, and is separated out for testing.

var Global State

Global is the method receiver of all seccheck functions.

func (*State) AddSyscallFlagListener

func (s *State) AddSyscallFlagListener(listener SyscallFlagListener)

AddSyscallFlagListener adds a listener to the State.

The listener will be notified whenever syscall point enablement changes.

func (*State) AppendSink

func (s *State) AppendSink(c Sink, reqs []PointReq)

AppendSink registers the given Sink to execute at checkpoints. The Sink will execute after all previously-registered sinks, and only if those Sinks return a nil error.

func (*State) Enabled

func (s *State) Enabled(p Point) bool

Enabled returns true if any Sink is registered for the given checkpoint.

func (*State) GetFieldSet

func (s *State) GetFieldSet(p Point) FieldSet

GetFieldSet returns the FieldSet that has been configured for a given Point.

func (*State) SentToSinks

func (s *State) SentToSinks(fn func(c Sink) error) error

SentToSinks iterates over all sinks and calls fn for each one of them.

func (*State) SyscallEnabled

func (s *State) SyscallEnabled(typ SyscallType, sysno uintptr) bool

SyscallEnabled checks if the corresponding point for the syscall is enabled.

type SyscallFlagListener

type SyscallFlagListener interface {
	// UpdateSecCheck is called each time the system call point enablement may have changed.
	// This is called with seccheck.State.mu held, so it is expected to be fast and not re-entrant
	// with seccheck.State functions that attempt to re-lock it.
	UpdateSecCheck(state *State)
}

SyscallFlagListener is an interface that is notified when syscall point enablement changes.

It is used to notify the kernel's syscall table about syscall points, without introducing a direct dependency on it.

type SyscallType

type SyscallType int

SyscallType is an enum that denotes different types of syscall points. There are 2 types of syscall point: fully-schematized and raw. Schematizes are points that have syscall specific format, e.g. open => {path, flags, mode}. Raw uses a generic schema that contains syscall number and 6 arguments. Each of these type have a corresponding enter and exit points. Exit points include return value and errno information.

const (
	// SyscallEnter represents schematized/enter syscall.
	SyscallEnter SyscallType = iota
	// SyscallExit represents schematized/exit syscall.
	SyscallExit
	// SyscallRawEnter represents raw/enter syscall.
	SyscallRawEnter
	// SyscallRawExit represents raw/exit syscall.
	SyscallRawExit
)

Directories

Path Synopsis
points
sinks
null
Package null defines a seccheck.Sink that does nothing with the trace points, akin to /dev/null.
Package null defines a seccheck.Sink that does nothing with the trace points, akin to /dev/null.
remote
Package remote defines a seccheck.Sink that serializes points to a remote process.
Package remote defines a seccheck.Sink that serializes points to a remote process.
remote/wire
Package wire defines structs used in the wire format for the remote checker.
Package wire defines structs used in the wire format for the remote checker.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL