kevent

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 27, 2021 License: Apache-2.0 Imports: 31 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 (
	// SerializeHandles indicates if handles are serialized as part of the process' state
	SerializeHandles bool
	// SerializeThreads indicates if threads are serialized as part of the process' state
	SerializeThreads bool
	// SerializeImages indicates if images are serialized as part of the process' state
	SerializeImages bool
	// SerializePE indicates if PE metadata are serialized as part of the process' state
	SerializePE bool
	// SerializeEnvs indicates if the environment variables are serialized as part of the process's state
	SerializeEnvs bool
)
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 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.

func (*Formatter) Format 

func (f *Formatter) Format(kevt *Kevent) []byte

Format applies the template on the provided kernel event.

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 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, v string)

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

func (Kevent) IsNetworkTCP 

func (kevt Kevent) IsNetworkTCP() bool

IsNetworkTCP determines whether the kevent pertains to network TCP events.

func (Kevent) IsNetworkUDP 

func (kevt Kevent) IsNetworkUDP() bool

IsNetworkUDP determines whether the kevent pertains to network UDP events.

func (*Kevent) MarshalJSON 

func (kevt *Kevent) MarshalJSON() []byte

MarshalJSON produces a JSON payload for this kevent.

func (*Kevent) MarshalRaw 

func (kevt *Kevent) MarshalRaw() []byte

MarshalRaw produces a byte stream of the kernel event suitable for writing to disk.

func (*Kevent) Release 

func (kevt *Kevent) Release()

Release returns an event to the pool.

func (*Kevent) String 

func (kevt *Kevent) String() string

String returns event's string representation.

func (*Kevent) UnmarshalRaw 

func (kevt *Kevent) UnmarshalRaw(b []byte, ver kcapver.Version) error

UnmarshalRaw recovers the state of the kernel event from the byte stream.

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 NewKparam 

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

NewKparam creates a new event parameter. Since the parameter type is already categorized, we can coerce the value to the appropriate representation (e.g. hex, IP address, user security identifier, etc.)

func NewKparamFromKcap 

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

NewKparamFromKcap builds a kparam instance from the restored state.

func (*Kparam) Release 

func (k *Kparam) Release()

Release returns the param to the pool.

func (Kparam) String 

func (k Kparam) String() string

String returns the string representation of the parameter value.

type Kparams 

type Kparams map[string]*Kparam

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

func (Kparams) Append 

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

Append adds a new parameter with 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 specified name, type and value from the kcap state.

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) 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) 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.

type Metadata 

type Metadata map[string]string

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 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
)

type Sequencer 

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

Sequencer is responsible for incrementing, getting and persisting the kevent sequence number in the Windows registry.

func NewSequencer 

func NewSequencer() *Sequencer

NewSequencer creates a fresh kevent sequencer. If the `KeventSeq` value is present under the volatile key, the current sequence number is initialized to the last stored sequence. The sequencer schedules a ticker that periodically dumps the current sequence number into the registry value.

func (*Sequencer) Close 

func (s *Sequencer) Close() error

Close shutdowns the event sequencer.

func (*Sequencer) Get 

func (s *Sequencer) Get() uint64

Get returns the current sequence number.

func (*Sequencer) Increment 

func (s *Sequencer) Increment()

Increment increments the sequence number atomically.

func (*Sequencer) Reset 

func (s *Sequencer) Reset() error

Reset removes the sequence value from the registry and sets the sequence number to zero.

func (*Sequencer) Store 

func (s *Sequencer) Store() error

Store saves the current sequence value in the registry.

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.