seccheck

package
v0.0.0-...-5477640 Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2024 License: Apache-2.0, MIT Imports: 15 Imported by: 22

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 SeqAtomicStoreSeqedSinkSlice 

func SeqAtomicStoreSeqedSinkSlice(ptr *[]Sink, val []Sink)

SeqAtomicStoreSeqed sets *ptr to a copy of val.

Preconditions: ptr is protected by a SeqCount that will be in a writer critical section throughout the call to SeqAtomicStore.

func SeqAtomicStoreSinkSlice 

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

SeqAtomicStore sets *ptr to a copy of val, ensuring that any racing reader critical sections are forced to retry.

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 

func (SinkDefaults) Clone(context.Context, FieldSet, *pb.CloneInfo) error

Clone implements Sink.Clone.

func (SinkDefaults) ContainerStart 

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

ContainerStart implements Sink.ContainerStart.

func (SinkDefaults) Execve 

func (SinkDefaults) Execve(context.Context, FieldSet, *pb.ExecveInfo) error

Execve implements Sink.Execve.

func (SinkDefaults) ExitNotifyParent 

func (SinkDefaults) ExitNotifyParent(context.Context, FieldSet, *pb.ExitNotifyParentInfo) error

ExitNotifyParent implements Sink.ExitNotifyParent.

func (SinkDefaults) RawSyscall 

func (SinkDefaults) RawSyscall(context.Context, FieldSet, *pb.Syscall) error

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 

func (SinkDefaults) Syscall(context.Context, FieldSet, *pb.ContextData, pb.MessageType, proto.Message) error

Syscall implements Sink.Syscall.

func (SinkDefaults) TaskExit 

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

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
)

Source Files

View all Source files

Directories

Path Synopsis
points
points_go_proto
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.