kevent

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2023 License: Apache-2.0 Imports: 23 Imported by: 0

README

Kevent is the fundamental data structure for transporting kernel events.

Each kernel event structure contains a series of canonical fields that describe the nature of the event such as its name, the process identifier that generated the event and such. The following is the list of all canonical fields.

  • Sequence is a monotonically increasing integer value that uniquely identifies an event. The sequence value is guaranteed to increment monotonically as long as the machine is not rebooted. After the restart, the sequence is restored to the zero value.
  • PID represents the process identifier that triggered the kernel event.
  • TID is the thread identifier connected to the kernel event.
  • CPU designates the logical CPU core on which the event was originated.
  • Name is the human-readable event name such as CreateProcess or RegOpenKey.
  • Timestamp denotes the timestamp expressed in nanosecond precision as the instant the event occurred.
  • Category designates the category to which the event pertains, e.g. file or thread. Each particular category is explained thoroughly in the next sections.
  • Description is a short explanation about the purpose of the event. For example, CreateFile kernel event creates or opens a file, directory, I/O device, pipe, console buffer or other block/pseudo device.
  • Host represents the host name where the event was produced.

Parameters

Also called as kparams in Fibratus parlance, contain each of the event's parameters. Internally, they are modeled as a collection of key/value pairs where the key is mapped to the structure consisting of parameter name, parameter type and the value. An example of the parameter tuple could be the dip parameter that denotes a destination IP address with value 172.17.0.2 and therefore IPv4 type. Additionally, parameter types can be scalar values, strings, slices, enumerations, and timestamps among others.

Process state

Each event stores the process state that represents an extended information about the process including its allocated resources such as handles, dynamically-linked libraries, exported environment variables and other attributes. The process state internals are thoroughly explained in the Process events section.

Metadata

Metadata are an arbitrary sequence of tags in form of key/value pairs that you can squash into the event on behalf of transformers. A tag can be virtually any string data that you find meaningful to either identify the event or apply filtering/grouping once event is persisted in the data store.

Documentation

Overview

Package kevent defines the fundamental data structures that underpin the state of every kernel event pushed from the consumer.

Index

Constants

This section is empty.

Variables

View Source 
var ParamKVDelimiter = "➜ "

ParamKVDelimiter specifies the character that delimits parameter's key from its value

View Source 
var ParamNameCaseStyle = SnakeCase

ParamNameCaseStyle designates the case style for kernel parameter names

View Source 
var Template = `` /* 1903-byte string literal not displayed */

Template is the default Go template used for formatting events in textual format.

View Source 
var TimestampFormat string

TimestampFormat is the Go valid format for the kernel event timestamp

Functions

This section is empty.

Types

type Batch 

type Batch struct {
	Events []*Kevent
}

Batch contains a sequence of kernel events.

func NewBatch 

func NewBatch(evts ...*Kevent) *Batch

NewBatch produces a new batch from the group of events.

func (*Batch) Len 

func (b *Batch) Len() int64

Len returns the length of the batch.

func (*Batch) MarshalJSON 

func (b *Batch) MarshalJSON() []byte

MarshalJSON serializes the batch of events to JSON format.

func (*Batch) Release 

func (b *Batch) Release()

Release releases all events from the batch and returns them to the pool.

type Formatter 

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

Formatter deals with producing event's output that is dictated by the template.

func NewFormatter 

func NewFormatter(template string) (*Formatter, error)

NewFormatter builds a new instance of event's formatter.

type Kevent 

type Kevent struct {
	// Seq is monotonically incremented kernel event sequence.
	Seq uint64 `json:"seq"`
	// PID is the identifier of the process that generated the event.
	PID uint32 `json:"pid"`
	// Tid is the thread identifier of the thread that generated the event.
	Tid uint32 `json:"tid"`
	// Type is the internal representation of the kernel event. This field should be ignored by serializers.
	Type ktypes.Ktype `json:"-"`
	// CPU designates the processor logical core where the event was originated.
	CPU uint8 `json:"cpu"`
	// Name is the human friendly name of the kernel event.
	Name string `json:"name"`
	// Category designates the category to which this event pertains.
	Category ktypes.Category `json:"category"`
	// Description is the short explanation that describes the purpose of the event.
	Description string `json:"description"`
	// Host is the machine name that reported the generated event.
	Host string `json:"host"`
	// Timestamp represents the temporal occurrence of the event.
	Timestamp time.Time `json:"timestamp"`
	// Kparams stores the collection of kernel event parameters.
	Kparams Kparams `json:"params"`
	// Metadata represents any tags that are meaningful to this event.
	Metadata Metadata `json:"metadata"`
	// PS represents process' metadata and its allocated resources such as handles, DLLs, etc.
	PS *pstypes.PS `json:"ps,omitempty"`
}

Kevent encapsulates kernel event's payload.

func Empty added in v1.4.0 

func Empty() *Kevent

Empty return a pristine kernel event instance.

func New 

func New(seq uint64, pid, tid uint32, cpu uint8, ktype ktypes.Ktype, ts time.Time, kpars Kparams) *Kevent

New constructs a new kernel event instance.

func NewFromKcap 

func NewFromKcap(buf []byte) (*Kevent, error)

NewFromKcap recovers the kernel event instance from the kcapture byte buffer.

func (*Kevent) AddMeta 

func (kevt *Kevent) AddMeta(k MetadataKey, v any)

AddMeta appends a key/value pair to event's metadata.

func (*Kevent) Release 

func (kevt *Kevent) Release()

Release returns an event to the pool.

func (*Kevent) RenderCustomTemplate added in v1.8.0 

func (kevt *Kevent) RenderCustomTemplate(tmpl *template.Template) ([]byte, error)

RenderCustomTemplate returns the event string representation after applying the given Go template.

func (*Kevent) RenderDefaultTemplate added in v1.8.0 

func (kevt *Kevent) RenderDefaultTemplate() ([]byte, error)

RenderDefaultTemplate returns the event string representation after applying the default Go template.

func (*Kevent) SequenceBy added in v1.10.0 

func (kevt *Kevent) SequenceBy() any

SequenceBy returns the BY statement join field from event metadata.

func (*Kevent) String 

func (kevt *Kevent) String() string

String returns event's string representation.

type Kparam 

type Kparam struct {
	// Type is the type of the parameter. For example, `sport` parameter has the `Port` type although its value
	// is the uint16 numeric type.
	Type kparams.Type `json:"-"`
	// Value is the container for parameter values. To access the underlying value use the appropriate `Get` methods.
	Value kparams.Value `json:"value"`
	// Name represents the name of the parameter (e.g. pid, sport).
	Name string `json:"name"`
}

Kparam defines the layout of the kernel event parameter.

func NewKparamFromKcap 

func NewKparamFromKcap(name string, typ kparams.Type, value kparams.Value) *Kparam

NewKparamFromKcap builds a kparam instance from the restored state.

type Kparams 

type Kparams map[string]*Kparam

Kparams is the type that represents the sequence of kernel event parameters

func KparamsFromSlice added in v1.6.0 

func KparamsFromSlice(pars ...*Kparam) Kparams

KparamsFromSlice creates the params map from the variadic param list.

func NewKparamBuilder added in v1.8.0 

func NewKparamBuilder(n int) Kparams

NewKparamBuilder yields a new event parameter builder.

func (Kparams) Append 

func (kpars Kparams) Append(name string, typ kparams.Type, value kparams.Value) Kparams

Append adds a new parameter with the specified name, type and value.

func (Kparams) AppendFromKcap 

func (kpars Kparams) AppendFromKcap(name string, typ kparams.Type, value kparams.Value) Kparams

AppendFromKcap adds a new parameter with the specified name, type and value from the kcap state.

func (Kparams) Build added in v1.8.0 

func (kpars Kparams) Build() Kparams

Build returns all appended parameters.

func (Kparams) Contains 

func (kpars Kparams) Contains(name string) bool

Contains determines whether the specified parameter name exists.

func (Kparams) Find 

func (kpars Kparams) Find(name string) *Kparam

Find returns the kparam with specified name. If it is not found, nil value is returned.

func (Kparams) Get 

func (kpars Kparams) Get(name string) (kparams.Value, error)

Get returns the raw value for given parameter name. It is the responsibility of the caller to probe type assertion on the value before yielding its underlying type.

func (Kparams) GetDouble 

func (kpars Kparams) GetDouble(name string) (float64, error)

GetDouble returns the underlying double (float64) value from the parameter.

func (Kparams) GetFloat 

func (kpars Kparams) GetFloat(name string) (float32, error)

GetFloat returns the underlying float value from the parameter.

func (Kparams) GetHex 

func (kpars Kparams) GetHex(name string) (kparams.Hex, error)

GetHex returns the generic hexadecimal type for the specified parameter name.

func (Kparams) GetHexAsUint32 

func (kpars Kparams) GetHexAsUint32(name string) (uint32, error)

GetHexAsUint32 returns the number hexadecimal representation as uint32 value.

func (Kparams) GetHexAsUint64 

func (kpars Kparams) GetHexAsUint64(name string) (uint64, error)

GetHexAsUint64 returns the number hexadecimal representation as uint64 value.

func (Kparams) GetHexAsUint8 

func (kpars Kparams) GetHexAsUint8(name string) (uint8, error)

GetHexAsUint8 returns the number hexadecimal representation as uint8 value.

func (Kparams) GetIP 

func (kpars Kparams) GetIP(name string) (net.IP, error)

GetIP returns either the IPv4 or IPv6 address from the parameter.

func (Kparams) GetIPv4 

func (kpars Kparams) GetIPv4(name string) (net.IP, error)

GetIPv4 returns the underlying IPv4 address from the parameter.

func (Kparams) GetIPv6 

func (kpars Kparams) GetIPv6(name string) (net.IP, error)

GetIPv6 returns the underlying IPv6 address from the parameter.

func (Kparams) GetInt16 

func (kpars Kparams) GetInt16(name string) (int16, error)

GetInt16 returns the underlying int16 value from the parameter.

func (Kparams) GetInt32 

func (kpars Kparams) GetInt32(name string) (int32, error)

GetInt32 returns the underlying int32 value from the parameter.

func (Kparams) GetInt64 

func (kpars Kparams) GetInt64(name string) (int64, error)

GetInt64 returns the underlying int64 value from the parameter.

func (Kparams) GetInt8 

func (kpars Kparams) GetInt8(name string) (int8, error)

GetInt8 returns the underlying int8 value from the parameter.

func (Kparams) GetPid 

func (kpars Kparams) GetPid() (uint32, error)

GetPid returns the pid from the parameter.

func (Kparams) GetPpid 

func (kpars Kparams) GetPpid() (uint32, error)

GetPpid returns the parent pid from the parameter.

func (Kparams) GetSlice 

func (kpars Kparams) GetSlice(name string) (kparams.Value, error)

GetSlice returns the slice of generic values from the parameter.

func (Kparams) GetString 

func (kpars Kparams) GetString(name string) (string, error)

GetString returns the underlying string value from the parameter.

func (Kparams) GetStringSlice 

func (kpars Kparams) GetStringSlice(name string) ([]string, error)

GetStringSlice returns the string slice from the event parameter.

func (Kparams) GetTid 

func (kpars Kparams) GetTid() (uint32, error)

GetTid returns the thread id from the parameter.

func (Kparams) GetTime 

func (kpars Kparams) GetTime(name string) (time.Time, error)

GetTime returns the underlying time structure from the parameter.

func (Kparams) GetUint16 

func (kpars Kparams) GetUint16(name string) (uint16, error)

GetUint16 returns the underlying int16 value from the parameter.

func (Kparams) GetUint32 

func (kpars Kparams) GetUint32(name string) (uint32, error)

GetUint32 returns the underlying uint32 value from the parameter.

func (Kparams) GetUint64 

func (kpars Kparams) GetUint64(name string) (uint64, error)

GetUint64 returns the underlying uint64 value from the parameter.

func (Kparams) GetUint8 

func (kpars Kparams) GetUint8(name string) (uint8, error)

GetUint8 returns the underlying uint8 value from the parameter.

func (Kparams) Len 

func (kpars Kparams) Len() int

Len returns the number of parameters.

func (Kparams) MustGetPid added in v1.6.0 

func (kpars Kparams) MustGetPid() uint32

MustGetPid returns the pid parameter. It panics if an error occurs while trying to get the pid parameter.

func (Kparams) MustGetString added in v1.6.0 

func (kpars Kparams) MustGetString(name string) string

MustGetString returns the string parameter or panics if an error occurs while trying to get the parameter.

func (Kparams) MustGetTime added in v1.10.0 

func (kpars Kparams) MustGetTime(name string) time.Time

MustGetTime returns the underlying time structure from the parameter or panics if any errors occur.

func (Kparams) MustGetUint32 added in v1.6.0 

func (kpars Kparams) MustGetUint32(name string) uint32

MustGetUint32 returns the underlying uint32 value parameter. It panics if an error occurs while trying to get the parameter.

func (Kparams) Remove 

func (kpars Kparams) Remove(name string)

Remove deletes the specified parameter from the map.

func (Kparams) Set 

func (kpars Kparams) Set(name string, value kparams.Value, typ kparams.Type) error

Set replaces the value that is indexed at existing parameter name. It will return an error if the supplied parameter is not present.

func (Kparams) SetValue added in v1.6.0 

func (kpars Kparams) SetValue(name string, value kparams.Value) error

SetValue replaces the value for the given parameter name. It will return an error if the supplied parameter is not present in the parameter map.

func (Kparams) String 

func (kpars Kparams) String() string

String returns the string representation of the event parameters. Parameter names are rendered according to the currently active parameter style case.

func (Kparams) TryGetHexAsUint32 added in v1.6.0 

func (kpars Kparams) TryGetHexAsUint32(name string) (uint32, error)

TryGetHexAsUint32 attempts to get the uint8 value from its hexadecimal representation. If the param is present, but doesn't have the hex type, then the param value is directly coerced into uint32 scalar.

func (Kparams) TryGetHexAsUint64 added in v1.6.0 

func (kpars Kparams) TryGetHexAsUint64(name string) (uint64, error)

TryGetHexAsUint64 attempts to get the uint64 value from its hexadecimal representation. If the param is present, but doesn't have the hex type, then the param value is directly coerced into uint64 scalar.

func (Kparams) TryGetHexAsUint8 added in v1.6.0 

func (kpars Kparams) TryGetHexAsUint8(name string) (uint8, error)

TryGetHexAsUint8 attempts to get the uint8 value from its hexadecimal representation. If the param is present, but doesn't have the hex type, then the param value is directly coerced into uint8 scalar.

type Metadata 

type Metadata map[MetadataKey]any

Metadata is a type alias for event metadata. Any tag, i.e. key/value pair could be attached to metadata.

func (Metadata) String 

func (md Metadata) String() string

String turns kernel event's metadata into string.

type MetadataKey added in v1.5.0 

type MetadataKey string

MetadataKey represents the type definition for the metadata keys 

const (
	// YaraMatchesKey is the tag name for the yara matches JSON representation
	YaraMatchesKey MetadataKey = "yara.matches"
	// RuleNameKey identifies the rule that was triggered by the event
	RuleNameKey MetadataKey = "rule.name"
	// RuleGroupKey identifies the group to which the triggered rule pertains
	RuleGroupKey      MetadataKey = "rule.group"
	RuleSequenceByKey MetadataKey = "rule.seq.by"
)

func (MetadataKey) String added in v1.5.0 

func (key MetadataKey) String() string

type ParamCaseStyle 

type ParamCaseStyle uint8

ParamCaseStyle is the type definition for parameter name case style 

const (
	// SnakeCase is the default parameter's name case style. Multi-word parameters are delimited by underscore symbol (e.g. process_object)
	SnakeCase ParamCaseStyle = 1
	// DotCase style uses a dot to separate multi-word parameter names (e.g. process.object)
	DotCase ParamCaseStyle = 2
	// PascalCase renders parameter name with pascal case naming style (e.g. ProcessObject)
	PascalCase ParamCaseStyle = 3
	// CamelCase represents parameter names with camel case naming style (e.g. processObject)
	CamelCase ParamCaseStyle = 4
)

Source Files

View all Source files

Directories

Path Synopsis

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.