runtimeevent

package
v0.1.5 Latest Latest
Warning

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

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

Documentation

Overview

Package runtimeevent defines the normalized, attributed runtime event plane shared by every producer (the managers' poll sources) and every consumer (attribution, monitor sinks, reporters).

The package is deliberately dependency-light and side-effect free: it holds the event schema and the source/sink seam interfaces.

Index

Constants

View Source 
const (
	SourceReasonInitializationFailed  = "InitializationFailed"
	SourceReasonReaderFailed          = "ReaderFailed"
	SourceReasonUnexpectedExit        = "UnexpectedExit"
	SourceReasonDependencyUnavailable = "DependencyUnavailable"
	SourceReasonStarting              = "Starting"
	SourceReasonReady                 = "Ready"
)
View Source 
const ReasonCountMapFull = "count_map_full"

ReasonCountMapFull is the LossFunc reason for observations a kernel program could not record because its per-cgroup count map had no room left.

Variables

This section is empty.

Functions

func SourceReady added in v0.1.3 

func SourceReady(ctx context.Context)

SourceReady reports that a source initialized from ctx is ready to produce events. Contexts without a readiness callback are valid.

func WithSourceReady added in v0.1.3 

func WithSourceReady(ctx context.Context, ready func()) context.Context

WithSourceReady installs the callback a source calls once it can produce events. A nil callback leaves ctx unchanged.

Types

type DNSFacts 

type DNSFacts struct {
	QName string `json:"qname"`
}

DNSFacts describes an observed DNS question. The name is what the workload asked to resolve, which is not proof that it connected: an answer can be cached or shared, and a workload dialling a bare address asks nothing.

type Event 

type Event struct {
	Kind     Kind      `json:"kind"`
	Time     time.Time `json:"time"`
	CgroupID uint64    `json:"cgroupID,omitempty"`
	PID      uint32    `json:"pid,omitempty"`
	Comm     string    `json:"comm,omitempty"`
	// Count > 1 for poll-sourced events that aggregate N kernel occurrences.
	// The decision is part of the counter key, so a Count never mixes allowed
	// and denied occurrences.
	Count uint32 `json:"count,omitempty"`

	// KernelDenied marks events actually denied at the kernel level.
	KernelDenied bool `json:"kernelDenied,omitempty"`

	// WouldDeny marks events that would have been blocked but whose policy is
	// in monitor mode. Written by pkg/monitor.
	WouldDeny bool `json:"wouldDeny,omitempty"`

	Net      *NetFacts      `json:"net,omitempty"`
	DNS      *DNSFacts      `json:"dns,omitempty"`
	Exec     *ExecFacts     `json:"exec,omitempty"`
	Open     *OpenFacts     `json:"open,omitempty"`
	Protocol *ProtocolFacts `json:"protocol,omitempty"`

	// Pod is filled by pkg/attribution. Sources may pre-fill Pod.UID as a
	// hint when they know the pod but not the cgroup (egress poll source).
	Pod PodIdentity `json:"pod,omitempty"`
}

Event is one normalized, attributed runtime observation. Exactly one facts pointer matching Kind is non-nil.

type ExecFacts 

type ExecFacts struct {
	Filename string `json:"filename"`
	// PolicyPath is an internal canonical alias used for matching while
	// Filename remains the resolved value shown to operators.
	PolicyPath string `json:"-"`

	// Argv is empty for sources that observe the exec without its arguments.
	// It is attacker-controlled text and can carry credentials passed as
	// flags, so it must not reach a Report without going through the
	// reporter's redaction.
	Argv []string `json:"argv,omitempty"`
}

ExecFacts describes a process execution.

type KernelDecision 

type KernelDecision uint32

KernelDecision mirrors the DECISION_ALLOW / DECISION_DENY defines in the C programs; keep the values in sync. 

const (
	DecisionAllow KernelDecision = 0
	DecisionDeny  KernelDecision = 1
)

type Kind 

type Kind string

Kind discriminates which facts pointer on an Event is populated. 

const (
	KindNet      Kind = "net"
	KindDNS      Kind = "dns"
	KindExec     Kind = "exec"
	KindOpen     Kind = "open"
	KindProtocol Kind = "protocol"
)

type LossFunc 

type LossFunc func(reason string, delta uint64)

LossFunc receives the increase in one kernel-side loss counter since the last poll.

type NetFacts 

type NetFacts struct {
	DestIP netip.Addr `json:"destIP"`
	// Domain is the DNS name DestIP was resolved from, empty when the kernel
	// never saw the address in a snooped answer.
	Domain string `json:"domain,omitempty"`
}

NetFacts describes an egress connection attempt.

type OpenFacts 

type OpenFacts struct {
	Path string `json:"path"`
	// PolicyPath has the same internal matching role as ExecFacts.PolicyPath.
	PolicyPath string `json:"-"`
}

OpenFacts describes a file open.

type PodIdentity 

type PodIdentity struct {
	UID            string            `json:"uid,omitempty"`
	Namespace      string            `json:"namespace,omitempty"`
	Name           string            `json:"name,omitempty"`
	Labels         map[string]string `json:"labels,omitempty"`
	Container      string            `json:"container,omitempty"`
	ContainerID    string            `json:"containerID,omitempty"`
	OwnerKind      string            `json:"ownerKind,omitempty"`
	OwnerName      string            `json:"ownerName,omitempty"`
	NodeName       string            `json:"nodeName,omitempty"`
	ServiceAccount string            `json:"serviceAccount,omitempty"`
}

PodIdentity is the workload attribution attached to an Event.

type PolicyStatusRecorder 

type PolicyStatusRecorder interface {
	RecordCondition(policyUID, policyName string, cond metav1.Condition)
}

PolicyStatusRecorder is implemented by controller.StatusWriter and consumed by the managers. policyName is what addresses the object, so a caller that knows it makes the condition flushable even for a policy the recorder has never seen an event for; an empty name leaves the recorder to find it.

type ProtocolFacts 

type ProtocolFacts struct {
	Protocol string `json:"protocol"`
	ALPN     string `json:"alpn,omitempty"`
}

ProtocolFacts describes the application protocol classified from the first data segment of an egress flow. ALPN is non-empty only for TLS.

type Sink 

type Sink interface {
	Name() string
	HandleEvent(ev Event)
}

Sink consumes events after the collector's stages have run. HandleEvent must be fast, non-blocking, and must never panic outward.

type Source 

type Source interface {
	Name() string
	// Run calls SourceReady after initialization, then sends events until ctx
	// is done. It must not close out.
	Run(ctx context.Context, out chan<- Event) error
}

Source produces events.

type SourceState added in v0.1.3 

type SourceState string

SourceState is the lifecycle state of an event source. 

const (
	SourceStateStarting    SourceState = "Starting"
	SourceStateAvailable   SourceState = "Available"
	SourceStateUnavailable SourceState = "Unavailable"
)

type SourceStatusFunc added in v0.1.3 

type SourceStatusFunc func(source string, state SourceState, reason string)

SourceStatusFunc observes source lifecycle changes. Reasons are stable diagnostic categories and must not include raw error text.

Source Files

View all Source files

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.