gvisor

package
v0.3.325 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package gvisor receives a narrow subset of gVisor's SecCheck remote sink. The first supported signal is container/start. The wire message contains command arguments and a working directory, so only allowlisted identity fields may leave the decoder.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunIntegration added in v0.3.310

func RunIntegration(ctx context.Context, cfg IntegrationConfig, node string, lookup InventoryLookup, emit func(context.Context, Observation)) error

RunIntegration is a convenience entrypoint for callers that do not need health.

Types

type Collector added in v0.3.325

type Collector struct {
	// StopLookup and EmitStop are required when StopObservations is enabled.
	// StopLookup must accept a container that has just exited and a Pod that
	// is being deleted; the start lookup rejects both.
	StopLookup InventoryLookup
	EmitStop   func(context.Context, StopObservation)
	// contains filtered or unexported fields
}

Collector owns process-local health counters across listener retries. One instance supports one Run call; Stats may be called concurrently.

func (*Collector) Run added in v0.3.325

func (c *Collector) Run(ctx context.Context, cfg IntegrationConfig, node string, lookup InventoryLookup, emit func(context.Context, Observation)) error

Run joins identity before queueing and immediately before emission. Lookup must honor its two-second deadline. Emit must be nonblocking (OTEL batch). Listener failures retry at 1, 2, 4, 8, 16, then 30 seconds, without replacing existing paths or acquiring trace sessions. Clients must reconnect themselves.

func (*Collector) Stats added in v0.3.325

func (c *Collector) Stats() Health

type Health added in v0.3.325

type Health struct {
	Receiver         Stats  `json:"receiver"`
	Running          bool   `json:"running"`
	RecheckRejected  uint64 `json:"recheck_rejected"`
	ExportSubmitted  uint64 `json:"export_submitted"`
	ListenerFailures uint64 `json:"listener_failures"`
	// StopExportSubmitted + StopRecheckRejected == Receiver.StopCallbacksCompleted.
	StopRecheckRejected uint64 `json:"stop_recheck_rejected"`
	StopExportSubmitted uint64 `json:"stop_export_submitted"`
}

Health distinguishes local admission, dispatch and export submission. Counts are not atomic as a group and never attest to remote OTLP delivery.

type Identity added in v0.3.310

type Identity struct {
	ContainerID    string
	SandboxID      string
	RuntimeHandler string
	Namespace      string
	PodName        string
	PodUID         string
	ContainerName  string
}

Identity contains only allowlisted local-runtime inventory fields. It does not authenticate the trace sender or identify an actor/session.

type IntegrationConfig added in v0.3.310

type IntegrationConfig struct {
	Enabled         bool   `mapstructure:"enabled"`
	SocketPath      string `mapstructure:"socketPath"`
	RuntimeEndpoint string `mapstructure:"runtimeEndpoint"`
	RuntimeHandler  string `mapstructure:"runtimeHandler"`
	// StopObservations additionally exports stops matched to a verified start
	// on the same trace connection. It requires the runsc trace session to
	// select sentry/task_exit and sentry/exit_notify_parent, plus the
	// thread_id, group_id and thread_group_start_time context fields.
	StopObservations bool `mapstructure:"stopObservations"`
}

IntegrationConfig enables a separate experimental observation source. Empty configuration performs no I/O. RuntimeEndpoint defaults to the node's CRI socket at the call site; RuntimeHandler defaults to runsc.

func (IntegrationConfig) Validate added in v0.3.310

func (c IntegrationConfig) Validate() error

type InventoryLookup added in v0.3.310

type InventoryLookup func(context.Context, string) (Identity, error)

type Observation added in v0.3.310

type Observation struct {
	Start
	Identity Identity
	Node     string
}

Observation is distinct from an exec event, profile entry or security alert. Container/start precedes application execution. ObservedAt is receiver time.

type Receiver

type Receiver struct {
	SocketPath string
	Resolve    Resolver
	OnStart    StartHandler
	// OnStop is optional. When nil, exit points are ignored as before. When
	// set, the receiver matches exits against verified starts on the same
	// connection and never infers a stop from a closed connection.
	OnStop StopHandler
	// contains filtered or unexported fields
}

Receiver is an experimental, opt-in SecCheck remote sink listener. It does not configure runsc or acquire its single Default trace session.

func (*Receiver) QueueDrops

func (r *Receiver) QueueDrops() uint64

QueueDrops counts locally discarded events when the consumer cannot keep up.

func (*Receiver) Run

func (r *Receiver) Run(ctx context.Context) error

Run listens until ctx is canceled. The socket parent must already exist, belong to this process, and be private; no existing socket is unlinked.

func (*Receiver) Stats added in v0.3.299

func (r *Receiver) Stats() Stats

Stats returns cumulative counts for this Receiver instance. A completed callback is not proof of successful output; callers must check their own I/O.

type Resolver

type Resolver func(containerID string) bool

Resolver checks a claimed container ID against the local runtime inventory. The receiver never attributes an unverified claim to a Kubernetes workload.

type Start

type Start struct {
	Source      string
	ContainerID string
	ObservedAt  time.Time
	Dropped     uint32 // Cumulative sender-reported drop count on this connection.
	// contains filtered or unexported fields
}

Start is the entire retained event. In particular, Args, Cwd, Env, and raw protobuf bytes must never be added to this type or passed to the callback.

type StartHandler

type StartHandler func(context.Context, Start)

StartHandler receives only runtime-verified start events. It must honor ctx cancellation, including interrupting any blocking I/O, so Run can finish.

type Stats added in v0.3.299

type Stats struct {
	ActiveConnections   int64  `json:"active_connections"`
	Listening           bool   `json:"listening"`
	CanceledStarts      uint64 `json:"canceled_starts"`
	AcceptedConnections uint64 `json:"accepted_connections"`
	RejectedConnections uint64 `json:"rejected_connections"`
	ClosedConnections   uint64 `json:"closed_connections"`
	Handshakes          uint64 `json:"handshakes"`
	HandshakeErrors     uint64 `json:"handshake_errors"`
	ReceivedFrames      uint64 `json:"received_frames"`
	ReadErrors          uint64 `json:"read_errors"`
	InterruptedReads    uint64 `json:"interrupted_reads"`
	InvalidFrames       uint64 `json:"invalid_frames"`
	UnresolvedStarts    uint64 `json:"unresolved_starts"`
	IgnoredFrames       uint64 `json:"ignored_frames"`
	VerifiedStarts      uint64 `json:"verified_starts"`
	CallbacksCompleted  uint64 `json:"callbacks_completed"`
	SenderDropFrames    uint64 `json:"sender_drop_frames"`
	QueueDrops          uint64 `json:"queue_drops"`

	// Stop matching, populated only when OnStop is set. VerifiedStops equals
	// StopQueueDrops + CanceledStops + StopCallbacksCompleted after Run returns.
	VerifiedStops          uint64 `json:"verified_stops"`
	DuplicateTerminals     uint64 `json:"duplicate_terminals"`
	NonterminalExits       uint64 `json:"nonterminal_exits"`
	UnobservedTerminations uint64 `json:"unobserved_terminations"`
	StopKeyMissing         uint64 `json:"stop_key_missing"`
	StopTrackingOverflow   uint64 `json:"stop_tracking_overflow"`
	StopQueueDrops         uint64 `json:"stop_queue_drops"`
	CanceledStops          uint64 `json:"canceled_stops"`
	StopCallbacksCompleted uint64 `json:"stop_callbacks_completed"`
}

Stats is a process-local diagnostic snapshot. During collection fields are read independently. After Run returns all receiver workers have finished. It contains no message payload, container identity or command arguments.

type Stop added in v0.3.325

type Stop struct {
	Source      string
	ContainerID string
	ObservedAt  time.Time
	Dropped     uint32 // Cumulative sender-reported drop count on this connection.
	ExitCode    int    // CRI-style: the exit code, or 128+signal when signaled.
	Signal      int    // Terminating signal, or zero for a normal exit.
}

Stop is the entire retained terminal event. Like Start, it carries no argv, cwd, environment, credentials, process name or raw protobuf bytes.

type StopHandler added in v0.3.325

type StopHandler func(context.Context, Stop)

StopHandler receives stops for containers whose start was runtime-verified on the same connection. It must honor ctx cancellation.

type StopObservation added in v0.3.325

type StopObservation struct {
	Stop
	Identity Identity
	Node     string
}

StopObservation is a container termination reported by the Sentry for the container's initial task. It is not a CRI state change: the runtime may still report the container as running for a few milliseconds.

Directories

Path Synopsis
Package cri resolves trace claims through a private, deadline-bound local CRI connection, independently of node-agent's host namespace enrichment.
Package cri resolves trace claims through a private, deadline-bound local CRI connection, independently of node-agent's host namespace enrichment.

Jump to

Keyboard shortcuts

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