Documentation
¶
Overview ¶
Package normalize turns a decoded kernel event (the sensor's raw, pre-identity output) into the canonical telemetry.TelemetryEnvelope the whole data plane consumes (A1, #622). It is PURE and DETERMINISTIC: the same DecodedEvent always yields the same envelope, including its derived entity ids and event id, so ingest is idempotent (A3) and golden fixtures are stable. It owns no I/O and no clock — the collector stamps ObservedAt and resolves the kernel OccurredAt before calling Normalize; ReceivedAt is stamped later at ingest via TelemetryEnvelope.StampReceived.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DecodedEvent ¶
type DecodedEvent struct {
Class detection.Class
AgentID shared.ID
AgentSessionID shared.ID
AssetID shared.ID
BootID shared.ID
StreamID shared.ID
SensorID string
SensorVersion string
Sequence uint64
// OccurredAt is the KERNEL source time of the event; zero when the sensor could not read a kernel
// timestamp (the normalizer then falls back to ObservedAt and records the quality flag).
OccurredAt time.Time
// ObservedAt is when the collector decoded the event (userspace); it is required.
ObservedAt time.Time
Resource telemetry.ResourceContext
Coverage telemetry.CoverageFlags
Process *DecodedProcess
Network *DecodedNetwork
File *DecodedFile
Privilege *DecodedPrivilege
}
DecodedEvent is the sensor decode output the normalizer consumes: the raw per-class fields plus the identity, sequencing, timestamps, and placement the sensor already knows. Exactly one payload pointer is set — the one matching Class. The eBPF decode side (internal/infrastructure/ebpf) builds this from a kernel record; the normalizer never touches the kernel or the wire.
type DecodedFile ¶
type DecodedFile struct {
Op string // "open" | "write" | "rename"
Path string
Device uint64
Inode uint64
ContentHash string
PathTruncated bool
PID int
ProcStartTimeNanos uint64
Comm string
}
DecodedFile carries the raw file fields plus device+inode for a stable target id.
type DecodedNetwork ¶
type DecodedNetwork struct {
Kind string // "connect" | "sendmsg"
Proto string
Direction string
LocalAddr string
LocalPort int
RemoteAddr string
RemotePort int
PID int
ProcStartTimeNanos uint64
Comm string
}
DecodedNetwork carries the raw flow fields. ProcStartTimeNanos (resolved by the sensor's process table) lets the normalizer link the flow to a stable ProcessEntityID; 0 leaves the link empty (honest).
type DecodedPrivilege ¶
type DecodedPrivilege struct {
Kind string // "setuid" | "setresuid" | "capset"
PID int
ProcStartTimeNanos uint64
Comm string
FromUID int
ToUID int
Cap string
}
DecodedPrivilege carries the raw privilege-change fields.
type DecodedProcess ¶
type DecodedProcess struct {
Kind string // "exec" | "fork"
PID int
PPID int
StartTimeNanos uint64 // this process's kernel start time; 0 => unknown
ParentStartTimeNanos uint64 // the parent's kernel start time; 0 => unknown
Comm string
Path string
Args []string
ArgsTruncated bool
PathTruncated bool
UID int
}
DecodedProcess carries the raw process fields including the parent pid and the kernel start times the normalizer needs to derive stable entity ids (the fields D4 was missing).
type Normalizer ¶
type Normalizer struct{}
Normalizer maps DecodedEvent → telemetry.TelemetryEnvelope. It is stateless; a zero value is ready to use. It is a type (not just a function) so a future caller can inject it behind an interface without a signature change.
func (Normalizer) Normalize ¶
func (Normalizer) Normalize(d DecodedEvent) (telemetry.TelemetryEnvelope, error)
Normalize produces the canonical envelope for one decoded event, deriving stable entity ids, resolving the source timestamp, recording coverage/quality honesty, and validating the result. It returns a wrapped shared.ErrValidation for any malformed input so the caller maps it to a 4xx at the edge.
Source Files