groundtruth

type Correlation ¶

type Correlation string

Correlation records whether an event was bound to a known Wardyn run.

const (
	// CorrelationMapped means the event's container/cgroup resolved to a run.
	CorrelationMapped Correlation = "mapped"
	// CorrelationUnmapped means it did not. Such events are NEVER silently
	// dropped — they are emitted with run_id NULL so the blindness is visible
	// in the audit stream (an unmapped kernel event near a run is a signal).
	CorrelationUnmapped Correlation = "unmapped"
)

type Correlator ¶

type Correlator interface {
	// RunForContainer returns the run id for a container id (any prefix length
	// Tetragon emits) and whether it is a Wardyn-managed agent container. ok
	// is false for unknown / non-Wardyn containers.
	RunForContainer(containerID string) (runID uuid.UUID, ok bool)
}

Correlator resolves a container id and/or kernel cgroup id to a Wardyn run. The ingest sidecar implements this by listing docker containers labelled wardyn.managed=true and indexing them by container id (and, where available, cgroup id). It is the only knowledge this package has about how correlation happens — keeping the mapper target-agnostic and unit-testable.

type EventData ¶

type EventData struct {
	// Stream is always Stream ("ebpf").
	Stream string `json:"stream"`
	// Subtype is the fine-grained kernel-event kind.
	Subtype Subtype `json:"subtype"`
	// CgroupID is the kernel cgroup id of the observed process (0 if unknown).
	CgroupID uint64 `json:"cgroup_id,omitempty"`
	// ContainerID is the (truncated) container id the event was attributed to.
	ContainerID string `json:"container_id,omitempty"`
	// Argv is the full process command line for exec events.
	Argv []string `json:"argv,omitempty"`
	// Dst is "ip:port" for network_connect events.
	Dst string `json:"dst,omitempty"`
	// Path is the written file path for file_write events.
	Path string `json:"path,omitempty"`
	// Loader is true when the exec'd binary is a dynamic linker (ld-linux /
	// ld-musl). This is the ld-linux/mmap bypass surfaced honestly: such an
	// exec can load+run an arbitrary ELF the execve hook never named, so the
	// argv of an ld-linux invocation is the real program. We FLAG it, we do
	// not claim to block it.
	Loader bool `json:"loader,omitempty"`
	// Correlation is "mapped" or "unmapped".
	Correlation Correlation `json:"correlation"`
	// Reason carries a free-form explanation for sensor.blind / failure cases.
	Reason string `json:"reason,omitempty"`
}

EventData is the JSON shape stored in audit_events.data for every event from this stream (audit_events.data is JSONB; this requires NO schema change). It is deliberately small and stable so SIEM rules can rely on it.

type Mapper ¶

type Mapper struct {
	// contains filtered or unexported fields
}

Mapper converts a Tetragon JSON event into a Wardyn AuditEvent. It is stateless apart from the injected Correlator and a clock-free design (the ingest sidecar / control plane stamp the time). It is safe for concurrent use when the Correlator is.

func NewMapper(corr Correlator) *Mapper

func (m *Mapper) Map(ev TetragonEvent) (types.AuditEvent, bool)

func (m *Mapper) MapLine(line []byte) (types.AuditEvent, bool)

type Subtype ¶

type Subtype string

Subtype is the fine-grained kernel-event kind carried in data.subtype. It is stable, machine-readable, and one-to-one with the action where applicable.

const (
	SubtypeProcessExec    Subtype = "process_exec"
	SubtypeNetworkConnect Subtype = "network_connect"
	SubtypeFileWrite      Subtype = "file_write"
)

type TetragonArg ¶

type TetragonArg struct {
	FileArg   *TetragonFileArg `json:"file_arg,omitempty"`
	PathArg   *TetragonFileArg `json:"path_arg,omitempty"`
	StringArg string           `json:"string_arg,omitempty"`
	SockArg   *TetragonSockArg `json:"sock_arg,omitempty"`
}

TetragonArg is one kprobe argument. Tetragon emits typed argument objects; we read the path-bearing shapes (file_arg.path, path_arg.path, string_arg) and the socket shape (sock_arg, a KprobeSock) used for connect detection.

type TetragonEvent ¶

type TetragonEvent struct {
	ProcessExec   *TetragonProcessExec   `json:"process_exec,omitempty"`
	ProcessKprobe *TetragonProcessKprobe `json:"process_kprobe,omitempty"`
}

TetragonEvent is one line of the Tetragon JSON export. Exactly one of the event-kind fields is set per line. We map process_exec and process_kprobe; the kprobe handler multiplexes file-writes (security_file_permission / fd_install) and network connects (tcp_connect / security_socket_connect / __sys_connect) by function name + argument shape. Other kinds are ignored by the mapper (returns ok=false).

type TetragonFileArg ¶

type TetragonFileArg struct {
	Path string `json:"path,omitempty"`
}

TetragonFileArg carries a path-bearing argument.

type TetragonProcess ¶

type TetragonProcess struct {
	Binary    string `json:"binary,omitempty"`
	Arguments string `json:"arguments,omitempty"`
	CgroupID  uint64 `json:"cgroup_id,string,omitempty"`
	Docker    string `json:"docker,omitempty"` // container id (truncated)
}

TetragonProcess is the common process descriptor across event kinds. We read the binary, arguments, and container/cgroup correlation handles.

type TetragonProcessExec ¶

type TetragonProcessExec struct {
	Process *TetragonProcess `json:"process,omitempty"`
}

TetragonProcessExec carries a process execve.

type TetragonProcessKprobe ¶

type TetragonProcessKprobe struct {
	Process      *TetragonProcess `json:"process,omitempty"`
	FunctionName string           `json:"function_name,omitempty"`
	Args         []TetragonArg    `json:"args,omitempty"`
}

TetragonProcessKprobe carries a kprobe hit — the workhorse event kind for everything other than exec. The FunctionName identifies the hooked kernel function; the Args carry the typed argument objects. We use it for two things:

• sensitive file writes (security_file_permission / __x64_sys_write-style TracingPolicy): the path is in a file_arg / path_arg / string_arg.
• outbound network connects (tcp_connect / security_socket_connect / __sys_connect TracingPolicy): the destination is in a sock_arg.

type TetragonSockArg ¶

type TetragonSockArg struct {
	DAddr string `json:"daddr,omitempty"` // destination address
	DPort int    `json:"dport,omitempty"` // destination port
}

TetragonSockArg is Tetragon's KprobeSock argument, emitted by a connect kprobe. Field names match Tetragon's protojson output. We read only the destination tuple (daddr/dport) used for connect detection.