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 ¶
- func RunIntegration(ctx context.Context, cfg IntegrationConfig, node string, ...) error
- type Collector
- type Health
- type Identity
- type IntegrationConfig
- type InventoryLookup
- type Observation
- type Receiver
- type Resolver
- type Start
- type StartHandler
- type Stats
- type Stop
- type StopHandler
- type StopObservation
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.
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 Observation ¶ added in v0.3.310
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 ¶
QueueDrops counts locally discarded events when the consumer cannot keep up.
type Resolver ¶
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 ¶
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
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
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.
Source Files
¶
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. |