Categorygithub.com/rabbitstack/fibratuspkgkevent
package
2.0.0+incompatible
Repository: https://github.com/rabbitstack/fibratus.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
30
Dependents
43
Files
1.8k SLOC

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

# Packages

No description provided by the author

# Functions

Empty return a pristine event instance.
NewBatch produces a new batch from the group of events.
NewFormatter builds a new instance of event's formatter.
NewFromKcap recovers the event instance from the capture byte buffer.
NewKparamFromKcap builds a kparam instance from the restored state.
NewQueue constructs a new queue with the given channel size.
WithEnum appends the parameter with the enum mapping.
WithFlags appends the parameter with a list of bitmask flags.

# Constants

CamelCase represents parameter names with camel case naming style (e.g.
DotCase style uses a dot to separate multi-word parameter names (e.g.
PascalCase renders parameter name with pascal case naming style (e.g.
RuleGroupKey identifies the group to which the triggered rule pertains.
RuleNameKey identifies the rule that was triggered by the event.
RuleSequenceByKey represents the join field value in sequence rules.
SnakeCase is the default parameter's name case style.
YaraMatchesKey is the tag name for the yara matches JSON representation.

# Variables

DNSOptsFlags describes DNS query/response options.
DNSRecordTypes describes DNS record type values.
DNSResponseCodes describes DNS response codes.
FileAttributeFlags describes file attribute flags.
FileCreateOptionsFlags describes file create options flags.
FileShareModeFlags describes file share mask flags.
MemAllocationFlags describes virtual allocation/free type flags.
MemProtectionFlags represents memory protection option flags.
ParamKVDelimiter specifies the character that delimits parameter's key from its value.
ParamNameCaseStyle designates the case style for kernel parameter names.
PsAccessRightFlags describes flags for the process access rights.
Template is the default Go template used for formatting events in textual format.
ThreadAccessRightFlags describes flags for the thread access rights.
TimestampFormat is the Go valid format for the event timestamp.
ViewProtectionFlags describes section protection flags.
ViewSectionTypes describes possible values for process mapped sections.

# Structs

Batch contains a sequence of kernel events.
Formatter deals with producing event's output that is dictated by the template.
Kevent encapsulates event's state and provides a set of methods for accessing and manipulating event parameters, process state, and other metadata.
Kparam defines the layout of the kernel event parameter.
ParamFlag defines the mapping between the flag value and its symbolical name.
Queue is the channel-backed data structure for pushing captured events and invoking listeners.

# Interfaces

Listener is the minimal interface that all event listeners need to implement.

# Type aliases

Kparams is the type that represents the sequence of kernel event parameters.
Metadata is a type alias for event metadata.
MetadataKey represents the type definition for the metadata keys.
ParamCaseStyle is the type definition for parameter name case style.
ParamEnum defines the type for the event parameter enumeration values.
ParamFlags represents the type alias for the event parameter flags.
ParamOption represents the option for the parameter literal constructor.