types

Documentation

Overview

Package types defines the on-wire data model shared by tracer, enricher, exporter, and klctl. Structures mirror protobuf/event.proto but are kept hand-maintained so internal code paths do not need generated stubs.

Index

• Constants
• func ByteShift[T ~uint16 | ~uint32 | ~uint64 | ~int64](v T, n uint) byte
• func UUIDv7() string
• type CapabilityReport
  • func (r *CapabilityReport) HookAvailable(kind, name string) (HookCap, bool)
• type ContainerBootstrapSummary
• type ContainerLifecycleEvent
• type ContainerMeta
• type Correlation
• type CredTransition
• type DeviationEvent
• type GraphEdge
• type HistoricalContext
• type HistoryEntry
• type HookCap
• type IntentEvent
• type KernelInfo
• type ProcessAncestor
• type ResolvedPath
• type Severity
  • func SeverityFromString(s string) Severity
  • func (s Severity) AtLeast(threshold Severity) bool
  • func (s Severity) String() string
• type SyscallArg
• type SyscallEvent

Constants

const WireSchemaVersion = "v2"

WireSchemaVersion identifies the on-wire event-format generation this build produces and consumes. Because proto3 field additions are already additive, the token exists specifically to flag breaking layout steps (per-CPU delta headers, intent state-machine variants, repeated ResolvedPath on IntentEvent) — consumers mismatched on this token should refuse rather than silently mis-parse frames.

v2: event_type moved to byte 0 of the wire header; compact frames (16-byte header + args, EVENT_COMPACT_UNARY()) share the bulk_file ringbuf with full frames and are dispatched off byte 0.

Functions

func ByteShift

func ByteShift[T ~uint16 | ~uint32 | ~uint64 | ~int64](v T, n uint) byte

ByteShift returns byte(v >> n). Exists so the intentional 8-bit truncation used in byte-packing (UUID layout, count-min sketch seeds, IPv4 octet formatting, …) is gosec-suppressed in one place rather than at every call site.

#nosec G115 -- intentional 8-bit truncation for byte packing

func UUIDv7

func UUIDv7() string

UUIDv7 generates a time-ordered 128-bit identifier as a 36-char hyphenated hex string. Format follows RFC 9562 §5.7: 48-bit unix ms timestamp | 4-bit version (7) | 12-bit rand_a | 2-bit variant (10) | 62-bit rand_b.

The 74 random bits (rand_a + rand_b) come from math/rand/v2's top-level generator, which is goroutine-safe and lock-free (per-P runtime source, no getrandom syscall). This is deliberately NOT crypto-random: event IDs are internal correlation handles, not security tokens, and are produced once per hot-path event across eight ring-pump goroutines — a global mutex plus two getrandom(2) calls per event (the previous design) dominated the ID cost. Uniqueness within a millisecond is carried by the 74 random bits (collision probability is negligible at any realistic event rate); strict intra-millisecond monotonic ordering is not relied on anywhere (WAL ordering uses a separate monotonic Seq counter).

Types

type CapabilityReport

type CapabilityReport struct {
	NodeID  string            `json:"node_id"`
	Kernel  KernelInfo        `json:"kernel"`
	Helpers map[string]string `json:"helpers,omitempty"` // e.g. bpf_d_path=yes
	Hooks   []HookCap         `json:"hooks,omitempty"`
}

CapabilityReport is emitted by Agent.Capabilities.

func (*CapabilityReport) HookAvailable

func (r *CapabilityReport) HookAvailable(kind, name string) (HookCap, bool)

HookAvailable returns the first HookCap matching kind+name, if any.

type ContainerBootstrapSummary

type ContainerBootstrapSummary struct {
	StartNS          uint64   `json:"start_ns"`
	FirstExecs       []string `json:"first_execs,omitempty"`
	FirstReads       []string `json:"first_reads,omitempty"`
	FirstPeers       []string `json:"first_peers,omitempty"`
	BootstrapOngoing bool     `json:"bootstrap_ongoing"`
}

type ContainerLifecycleEvent

type ContainerLifecycleEvent struct {
	TimestampNS uint64        `json:"timestamp_ns"`
	Kind        string        `json:"kind"` // CREATE|START|STOP|DESTROY
	Meta        ContainerMeta `json:"meta"`
	RootPID     int32         `json:"root_pid,omitempty"`
}

ContainerLifecycleEvent — emitted on create/destroy.

type ContainerMeta

type ContainerMeta struct {
	Cluster     string            `json:"cluster,omitempty"`
	NodeName    string            `json:"node_name,omitempty"`
	Namespace   string            `json:"namespace,omitempty"`
	Pod         string            `json:"pod,omitempty"`
	Container   string            `json:"container,omitempty"`
	ContainerID string            `json:"container_id,omitempty"`
	Image       string            `json:"image,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	PidNS       uint32            `json:"pidns,omitempty"`
	MntNS       uint32            `json:"mntns,omitempty"`
	NetNS       uint32            `json:"netns,omitempty"`
}

ContainerMeta is the K8s/container enrichment attached to every primary event.

type Correlation

type Correlation struct {
	Kind    string  `json:"kind"`
	Summary string  `json:"summary,omitempty"`
	RefID   string  `json:"ref_id,omitempty"`
	Score   float64 `json:"score,omitempty"`
}

type CredTransition

type CredTransition struct {
	TSNS  uint64 `json:"ts_ns"`
	From  string `json:"from"`
	To    string `json:"to"`
	Cause string `json:"cause"`
}

type DeviationEvent

type DeviationEvent struct {
	DeviationID      string        `json:"deviation_id"`
	ProfileID        string        `json:"profile_id"`
	Kind             string        `json:"kind"` // new_exec|new_connect_target|new_file_path|rare_syscall|markov_anomaly
	DeviationScore   float64       `json:"deviation_score"`
	Evidence         string        `json:"evidence,omitempty"`
	RelatedIntentIDs []string      `json:"related_intent_ids,omitempty"`
	Meta             ContainerMeta `json:"meta"`
}

DeviationEvent reports observed behavior that diverges from the learned baseline profile for a workload.

type GraphEdge

type GraphEdge struct {
	EdgeID     string            `json:"edge_id"`
	Kind       string            `json:"kind"` // FORK|EXEC|IPC_CONNECT|FILE_TOUCH|SIGNAL|PTRACE|MOUNT_SHARE
	SrcNode    string            `json:"src_node"`
	DstNode    string            `json:"dst_node"`
	TSNS       uint64            `json:"ts_ns"`
	SessionID  string            `json:"session_id,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

GraphEdge is a directed relation in the causal session graph linking processes, files, sockets, and other kernel objects across a session.

type HistoricalContext

type HistoricalContext struct {
	Ancestors       []ProcessAncestor          `json:"ancestors,omitempty"`
	RecentProcess   []HistoryEntry             `json:"recent_process,omitempty"`
	RecentContainer []HistoryEntry             `json:"recent_container,omitempty"`
	Correlations    []Correlation              `json:"correlations,omitempty"`
	Bootstrap       *ContainerBootstrapSummary `json:"bootstrap,omitempty"`
	CredTimeline    []CredTransition           `json:"cred_timeline,omitempty"`
}

HistoricalContext bundles the recent process/container history attached to a primary event to support after-the-fact correlation.

type HistoryEntry

type HistoryEntry struct {
	TSNS    uint64 `json:"ts_ns"`
	Kind    string `json:"kind"`
	Summary string `json:"summary,omitempty"`
	RefID   string `json:"ref_id,omitempty"`
}

type HookCap

type HookCap struct {
	Kind               string   `json:"kind"` // syscall_tracepoint|lsm_bpf|kprobe|tracepoint
	Name               string   `json:"name"`
	Available          bool     `json:"available"`
	UnavailableReason  string   `json:"unavailable_reason,omitempty"`
	ArgSchema          []string `json:"arg_schema,omitempty"`
	FallbackSuggestion string   `json:"fallback_suggestion,omitempty"`
}

HookCap records one probe result.

type IntentEvent

type IntentEvent struct {
	IntentID             string             `json:"intent_id"`
	Kind                 string             `json:"kind"` // FileRead|FileWrite|NetworkExchange|...
	StartNS              uint64             `json:"start_ns"`
	EndNS                uint64             `json:"end_ns"`
	ContributingEventIDs []string           `json:"contributing_event_ids,omitempty"`
	Attributes           map[string]string  `json:"attributes,omitempty"`
	Meta                 ContainerMeta      `json:"meta"`
	Severity             Severity           `json:"severity,omitempty"`
	Confidence           float64            `json:"confidence,omitempty"`
	History              *HistoricalContext `json:"history,omitempty"`
}

IntentEvent represents a higher-level action aggregated from one or more raw syscall events (e.g. FileRead, FileWrite, NetworkExchange).

type KernelInfo

type KernelInfo struct {
	Version   string   `json:"version"`
	LSMs      []string `json:"lsms,omitempty"`
	CgroupVer string   `json:"cgroup_ver,omitempty"`
	HasBTF    bool     `json:"has_btf"`
	Lockdown  string   `json:"lockdown,omitempty"`
}

KernelInfo describes the kernel the agent is running on.

type ProcessAncestor

type ProcessAncestor struct {
	PID         int32  `json:"pid"`
	Binary      string `json:"binary,omitempty"`
	ArgvHash    string `json:"argv_hash,omitempty"`
	ExecTSNS    uint64 `json:"exec_ts_ns,omitempty"`
	ContainerID string `json:"container_id,omitempty"`
}

type ResolvedPath

type ResolvedPath struct {
	ContainerAbs     string `json:"container_abs,omitempty"`
	HostAbs          string `json:"host_abs,omitempty"`
	Inode            uint64 `json:"inode,omitempty"`
	DevMajor         uint32 `json:"dev_major,omitempty"`
	DevMinor         uint32 `json:"dev_minor,omitempty"`
	MountID          string `json:"mount_id,omitempty"`
	FollowedSymlink  bool   `json:"followed_symlink,omitempty"`
	PathUnresolved   bool   `json:"path_unresolved,omitempty"`
	UnresolvedReason string `json:"unresolved_reason,omitempty"`
	DentryHint       string `json:"dentry_hint,omitempty"`
}

ResolvedPath captures both container-relative and host-absolute views of a filesystem path along with the inode and device that uniquely identify it.

type Severity

type Severity int32

Severity categorizes how urgently an event should be surfaced.

const (
	SeverityUnknown Severity = iota
	SeverityLow
	SeverityMedium
	SeverityHigh
	SeverityCritical
)

func SeverityFromString

func SeverityFromString(s string) Severity

SeverityFromString parses severity names used by YAML policies.

func (Severity) AtLeast

func (s Severity) AtLeast(threshold Severity) bool

AtLeast returns true if s meets or exceeds threshold.

func (Severity) String

func (s Severity) String() string

type SyscallArg

type SyscallArg struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value,omitempty"`
	Raw   []byte `json:"raw,omitempty"`
}

SyscallArg is a single decoded syscall argument.

type SyscallEvent

type SyscallEvent struct {
	TimestampNS uint64 `json:"timestamp_ns"`
	EventID     string `json:"event_id"`
	CPUID       uint32 `json:"cpu_id"`
	HostPID     int32  `json:"host_pid"`
	HostTID     int32  `json:"host_tid"`
	HostPPID    int32  `json:"host_ppid"`
	PID         int32  `json:"pid"`
	TID         int32  `json:"tid"`
	UID         uint32 `json:"uid"`
	GID         uint32 `json:"gid"`
	Comm        string `json:"comm,omitempty"`
	ExePath     string `json:"exe_path,omitempty"`
	// CgroupID is the cgroupv2 inode for the task that produced this
	// event. The enricher prefers this over (PidNS, MntNS()) for
	// container attribution because cgroup is per-task and survives
	// hostPID/hostNetwork/hostMnt sharing scenarios that collapse
	// the NS pair onto host inodes.
	CgroupID uint64 `json:"cgroup_id,omitempty"`

	SyscallID   int32        `json:"syscall_id"`
	SyscallName string       `json:"syscall_name"`
	Args        []SyscallArg `json:"args,omitempty"`
	RetVal      int32        `json:"retval"`
	RetCode     string       `json:"retcode,omitempty"`
	DurationNS  uint64       `json:"duration_ns,omitempty"`

	// CoalescedCount / CoalescedBytes carry the in-kernel coalescing trailer:
	// the number of events, and bytes they requested, in the window that just
	// closed for this event's coalesce key. The window's first event was
	// emitted (and already observed); the remaining CoalescedCount-1 were
	// suppressed and are visible to userspace only through this field.
	//
	// Zero means "no trailer on this event", not "no events" — an event that
	// opens a window carries none. Consumers that count volume must fold this
	// in, or a burst of 500 reads collapsed into one event is counted once.
	// The same values are also mirrored into Args as coalesced_count /
	// coalesced_bytes for wire visibility; these fields exist so the hot path
	// does not have to scan Args.
	CoalescedCount uint32 `json:"coalesced_count,omitempty"`
	CoalescedBytes uint64 `json:"coalesced_bytes,omitempty"`

	Category  string   `json:"category,omitempty"`
	Operation string   `json:"operation,omitempty"`
	Resource  string   `json:"resource,omitempty"`
	Severity  Severity `json:"severity,omitempty"`

	Meta    ContainerMeta      `json:"meta"`
	History *HistoricalContext `json:"history,omitempty"`
}

SyscallEvent is the unified primary event.