Documentation ¶
Overview ¶
Package seccheck defines a structure for dynamically-configured security checks in the sentry.
Index ¶
- Constants
- Variables
- func Create(conf *SessionConfig, force bool) error
- func Delete(name string) error
- func Initialize()
- func List(out *[]SessionConfig)
- func RegisterSink(sink SinkDesc)
- func SetupSinks(sinks []SinkConfig) ([]*os.File, error)
- type Field
- type FieldDesc
- type FieldMask
- type FieldSet
- type Point
- type PointConfig
- type PointDesc
- type PointReq
- type SessionConfig
- type Sink
- type SinkConfig
- type SinkDefaults
- func (SinkDefaults) Clone(context.Context, FieldSet, *pb.CloneInfo) error
- func (SinkDefaults) ContainerStart(context.Context, FieldSet, *pb.Start) error
- func (SinkDefaults) Execve(context.Context, FieldSet, *pb.ExecveInfo) error
- func (SinkDefaults) ExitNotifyParent(context.Context, FieldSet, *pb.ExitNotifyParentInfo) error
- func (SinkDefaults) RawSyscall(context.Context, FieldSet, *pb.Syscall) error
- func (SinkDefaults) Status() SinkStatus
- func (SinkDefaults) Stop()
- func (SinkDefaults) Syscall(context.Context, FieldSet, *pb.ContextData, pb.MessageType, proto.Message) error
- func (SinkDefaults) TaskExit(context.Context, FieldSet, *pb.TaskExit) error
- type SinkDesc
- type SinkStatus
- type State
- func (s *State) AddSyscallFlagListener(listener SyscallFlagListener)
- func (s *State) AppendSink(c Sink, reqs []PointReq)
- func (s *State) Enabled(p Point) bool
- func (s *State) GetFieldSet(p Point) FieldSet
- func (s *State) SentToSinks(fn func(c Sink) error) error
- func (s *State) SyscallEnabled(typ SyscallType, sysno uintptr) bool
- type SyscallFlagListener
- type SyscallType
Constants ¶
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.
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 ¶
var Points = map[string]PointDesc{}
Points is a map with all the trace points registered in the system.
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 Initialize ¶
func Initialize()
Initialize initializes the Points available in the system. Must be called prior to using any of them.
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.
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 ¶
MakeFieldMask creates a FieldMask from a set of Fields.
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 ¶
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).
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) ContainerStart ¶
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 ¶
RawSyscall implements Sink.RawSyscall.
func (SinkDefaults) Syscall ¶
func (SinkDefaults) Syscall(context.Context, FieldSet, *pb.ContextData, pb.MessageType, proto.Message) error
Syscall implements Sink.Syscall.
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 ¶
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) GetFieldSet ¶
GetFieldSet returns the FieldSet that has been configured for a given Point.
func (*State) SentToSinks ¶
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 |
---|---|
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/server
Package server provides a common server implementation that can connect with remote.Remote.
|
Package server provides a common server implementation that can connect with remote.Remote. |
remote/test
Package test provides functionality used to test the remote sink.
|
Package test provides functionality used to test the remote sink. |
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. |