From 0399521acf57bb431c621b27ed2f9bf5f960c906 Mon Sep 17 00:00:00 2001 From: rabbitstack Date: Thu, 14 May 2026 18:58:57 +0200 Subject: [PATCH] refactor(event): Rename key handle parameter to KCB --- internal/etw/processors/registry_windows.go | 30 ++++++++--------- .../etw/processors/registry_windows_test.go | 32 +++++++++---------- .../transformers/replace/replace_test.go | 7 ++-- pkg/event/param_decoder_windows.go | 2 +- pkg/event/params/params_windows.go | 2 ++ pkg/filter/accessor_windows.go | 4 +-- pkg/filter/fields/fields_windows.go | 6 ++-- pkg/filter/filter_test.go | 2 +- 8 files changed, 44 insertions(+), 41 deletions(-) diff --git a/internal/etw/processors/registry_windows.go b/internal/etw/processors/registry_windows.go index 0ae5cf8f6..80567675b 100644 --- a/internal/etw/processors/registry_windows.go +++ b/internal/etw/processors/registry_windows.go @@ -112,12 +112,12 @@ func (r *registryProcessor) ProcessEvent(e *event.Event) (*event.Event, bool, er func (r *registryProcessor) processEvent(e *event.Event) (*event.Event, error) { switch e.Type { case event.RegKCBRundown, event.RegCreateKCB: - khandle := e.Params.MustGetUint64(params.RegKeyHandle) - r.keys[khandle] = e.Params.MustGetString(params.RegPath) + kcb := e.Params.MustGetUint64(params.RegKCB) + r.keys[kcb] = e.Params.MustGetString(params.RegPath) kcbCount.Add(1) case event.RegDeleteKCB: - khandle := e.Params.MustGetUint64(params.RegKeyHandle) - delete(r.keys, khandle) + kcb := e.Params.MustGetUint64(params.RegKCB) + delete(r.keys, kcb) kcbCount.Add(-1) default: if e.IsRegSetValueInternal() { @@ -126,9 +126,9 @@ func (r *registryProcessor) processEvent(e *event.Event) (*event.Event, error) { return e, nil } - khandle := e.Params.MustGetUint64(params.RegKeyHandle) + kcb := e.Params.MustGetUint64(params.RegKCB) // we have to obey a straightforward algorithm to connect relative - // key names to their root keys. If key handle is equal to zero we + // key names to their root keys. If the KCB is equal to zero we // have a full key name and don't have to go further resolving the // missing part. Otherwise, we have to lookup existing KCBs to try // finding the matching base key name and concatenate to its relative @@ -136,15 +136,15 @@ func (r *registryProcessor) processEvent(e *event.Event) (*event.Event, error) { // last resort is to scan process' handles and check if any of the // key handles contain the partial key name. In this case we assume // the correct key is encountered. - keyName := e.Params.MustGetString(params.RegPath) - if khandle != 0 { - if baseKey, ok := r.keys[khandle]; ok { - keyName = baseKey + "\\" + keyName + path := e.Params.MustGetString(params.RegPath) + if kcb != 0 { + if baseKey, ok := r.keys[kcb]; ok { + path = baseKey + "\\" + path } else { kcbMissCount.Add(1) - keyName = r.findMatchingKey(e.PID, keyName) + path = r.findMatchingKey(e.PID, path) } - if err := e.Params.SetValue(params.RegPath, keyName); err != nil { + if err := e.Params.SetValue(params.RegPath, path); err != nil { return e, err } } @@ -180,12 +180,12 @@ func (r *registryProcessor) processEvent(e *event.Event) (*event.Event, error) { } // values within hidden keys cannot be read - if strings.HasSuffix(keyName, "\\") { + if strings.HasSuffix(path, "\\") { return e, nil } // get the type/value of the registry key and append to parameters - rootkey, subkey := key.Format(keyName) + rootkey, subkey := key.Format(path) if rootkey == key.Invalid { return e, nil } @@ -197,7 +197,7 @@ func (r *registryProcessor) processEvent(e *event.Event) (*event.Event, error) { if ok && (errno.Is(os.ErrNotExist) || err == windows.ERROR_ACCESS_DENIED) { return e, nil } - return e, ErrReadValue(rootkey.String(), keyName, err) + return e, ErrReadValue(rootkey.String(), path, err) } e.AppendEnum(params.RegValueType, typ, key.RegistryValueTypes) diff --git a/internal/etw/processors/registry_windows_test.go b/internal/etw/processors/registry_windows_test.go index 425a53bfb..25fd6aa7e 100644 --- a/internal/etw/processors/registry_windows_test.go +++ b/internal/etw/processors/registry_windows_test.go @@ -50,8 +50,8 @@ func TestRegistryProcessor(t *testing.T) { Type: event.RegKCBRundown, Category: event.Registry, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.UnicodeString, Value: `\REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\bthserv\Parameters`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(18446666033549154696)}, + params.RegPath: {Name: params.RegPath, Type: params.UnicodeString, Value: `\REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\bthserv\Parameters`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(18446666033549154696)}, }, }, nil, @@ -71,8 +71,8 @@ func TestRegistryProcessor(t *testing.T) { Type: event.RegDeleteKCB, Category: event.Registry, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.UnicodeString, Value: `\REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\bthserv\Parameters`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(18446666033549154696)}, + params.RegPath: {Name: params.RegPath, Type: params.UnicodeString, Value: `\REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\bthserv\Parameters`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(18446666033549154696)}, }, }, func(p Processor) { @@ -93,8 +93,8 @@ func TestRegistryProcessor(t *testing.T) { Type: event.RegOpenKey, Category: event.Registry, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\bthserv\Parameters`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(0)}, + params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\bthserv\Parameters`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(0)}, }, }, nil, @@ -112,8 +112,8 @@ func TestRegistryProcessor(t *testing.T) { Type: event.RegOpenKey, Category: event.Registry, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `Pid`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(18446666033549154696)}, + params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `Pid`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(18446666033549154696)}, }, }, func(p Processor) { @@ -134,8 +134,8 @@ func TestRegistryProcessor(t *testing.T) { Category: event.Registry, PID: 23234, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `Pid`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(18446666033549154696)}, + params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `Pid`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(18446666033549154696)}, }, }, nil, @@ -157,8 +157,8 @@ func TestRegistryProcessor(t *testing.T) { Category: event.Registry, PID: 23234, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\REGISTRY\MACHINE\SYSTEM\CurrentControlSet\Control\Windows\Directory`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(0)}, + params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\REGISTRY\MACHINE\SYSTEM\CurrentControlSet\Control\Windows\Directory`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(0)}, }, }, nil, @@ -179,8 +179,8 @@ func TestRegistryProcessor(t *testing.T) { Category: event.Registry, PID: 23234, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\REGISTRY\MACHINE\SYSTEM\CurrentControlSet\Control\Windows\Directory`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(0)}, + params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\REGISTRY\MACHINE\SYSTEM\CurrentControlSet\Control\Windows\Directory`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(0)}, }, }, func(p Processor) { @@ -192,7 +192,7 @@ func TestRegistryProcessor(t *testing.T) { params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\SessionId`}, params.RegData: {Name: params.RegData, Type: params.UnicodeString, Value: "{ABD9EA10-87F6-11EB-9ED5-645D86501328}"}, params.RegValueType: {Name: params.RegValueType, Type: params.Enum, Value: uint32(1), Enum: key.RegistryValueTypes}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(0)}}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(0)}}, }, "Directory": { Type: event.RegSetValueInternal, @@ -201,7 +201,7 @@ func TestRegistryProcessor(t *testing.T) { params.RegPath: {Name: params.RegPath, Type: params.Key, Value: `\Directory`}, params.RegData: {Name: params.RegData, Type: params.UnicodeString, Value: "%SYSTEMROOT%"}, params.RegValueType: {Name: params.RegValueType, Type: params.Enum, Value: uint32(2), Enum: key.RegistryValueTypes}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Uint64, Value: uint64(0)}}, + params.RegKCB: {Name: params.RegKCB, Type: params.Uint64, Value: uint64(0)}}, }, } }, diff --git a/pkg/aggregator/transformers/replace/replace_test.go b/pkg/aggregator/transformers/replace/replace_test.go index 8a48c99e5..e17d705d1 100644 --- a/pkg/aggregator/transformers/replace/replace_test.go +++ b/pkg/aggregator/transformers/replace/replace_test.go @@ -19,12 +19,13 @@ package replace import ( + "testing" + "github.com/rabbitstack/fibratus/pkg/aggregator/transformers" "github.com/rabbitstack/fibratus/pkg/event" "github.com/rabbitstack/fibratus/pkg/event/params" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "testing" ) func TestTransform(t *testing.T) { @@ -33,8 +34,8 @@ func TestTransform(t *testing.T) { Tid: 2484, PID: 859, Params: event.Params{ - params.RegPath: {Name: params.RegPath, Type: params.UnicodeString, Value: `HKEY_LOCAL_MACHINE\SYSTEM\Setup\Pid`}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Address, Value: uint64(18446666033449935464)}, + params.RegPath: {Name: params.RegPath, Type: params.UnicodeString, Value: `HKEY_LOCAL_MACHINE\SYSTEM\Setup\Pid`}, + params.RegKCB: {Name: params.RegKCB, Type: params.Address, Value: uint64(18446666033449935464)}, }, } diff --git a/pkg/event/param_decoder_windows.go b/pkg/event/param_decoder_windows.go index ed5b09ddd..271325088 100644 --- a/pkg/event/param_decoder_windows.go +++ b/pkg/event/param_decoder_windows.go @@ -55,7 +55,7 @@ func (d *ParamDecoder) DecodeRegistry(r *etw.EventRecord, e *Event) { // skip InitialTime (uint64) e.AppendParam(params.NTStatus, params.Status, r.ReadUint32(8)) // skip Index/InfoClass (uint32) - e.AppendParam(params.RegKeyHandle, params.Address, r.ReadUint64(16)) + e.AppendParam(params.RegKCB, params.Address, r.ReadUint64(16)) e.AppendParam(params.RegPath, params.Key, r.ConsumeUTF16String(24)) } diff --git a/pkg/event/params/params_windows.go b/pkg/event/params/params_windows.go index 2fa1b90c4..19c86c030 100644 --- a/pkg/event/params/params_windows.go +++ b/pkg/event/params/params_windows.go @@ -143,6 +143,8 @@ const ( // RegKeyHandle identifies the parameter name for the registry key handle. RegKeyHandle = "key_handle" + // RegKCB identifies the parameter name for the registry key control block. + RegKCB = "kcb" // RegPath represents the parameter name for the fully qualified key path. RegPath = "key_path" // RegValue identifies the parameter name that contains the value diff --git a/pkg/filter/accessor_windows.go b/pkg/filter/accessor_windows.go index b8cd26191..32314ea37 100644 --- a/pkg/filter/accessor_windows.go +++ b/pkg/filter/accessor_windows.go @@ -910,8 +910,8 @@ func (r *registryAccessor) Get(f Field, e *event.Event) (params.Value, error) { } else { return filepath.Base(e.GetParamAsString(params.RegPath)), nil } - case fields.RegistryKeyHandle: - return e.GetParamAsString(params.RegKeyHandle), nil + case fields.RegistryKCB: + return e.GetParamAsString(params.RegKCB), nil case fields.RegistryValue: if e.IsRegSetValue() { return filepath.Base(filepath.Base(e.GetParamAsString(params.RegPath))), nil diff --git a/pkg/filter/fields/fields_windows.go b/pkg/filter/fields/fields_windows.go index c83e3e992..5db7fcff7 100644 --- a/pkg/filter/fields/fields_windows.go +++ b/pkg/filter/fields/fields_windows.go @@ -502,8 +502,8 @@ const ( RegistryPath Field = "registry.path" // RegistryKeyName represents the registry key name RegistryKeyName Field = "registry.key.name" - // RegistryKeyHandle represents the registry KCB address - RegistryKeyHandle Field = "registry.key.handle" + // RegistryKCB represents the registry KCB address + RegistryKCB Field = "registry.kcb" // RegistryValue represents the registry value name field RegistryValue Field = "registry.value" // RegistryValueType represents the registry value type field @@ -1202,7 +1202,7 @@ var fields = map[Field]FieldInfo{ RegistryPath: {RegistryPath, "fully qualified registry path", params.UnicodeString, []string{"registry.path = 'HKEY_LOCAL_MACHINE\\SYSTEM'"}, nil, nil}, RegistryKeyName: {RegistryKeyName, "registry key name", params.UnicodeString, []string{"registry.key.name = 'CurrentControlSet'"}, nil, nil}, - RegistryKeyHandle: {RegistryKeyHandle, "registry key object address", params.Address, []string{"registry.key.handle = 'FFFFB905D60C2268'"}, nil, nil}, + RegistryKCB: {RegistryKCB, "registry KCB address", params.Address, []string{"registry.kcb = 'FFFFB905D60C2268'"}, nil, nil}, RegistryValue: {RegistryValue, "registry value name", params.UnicodeString, []string{"registry.value = 'Epoch'"}, nil, nil}, RegistryValueType: {RegistryValueType, "type of registry value", params.UnicodeString, []string{"registry.value.type = 'REG_SZ'"}, nil, nil}, RegistryData: {RegistryData, "registry value captured data", params.Object, []string{"registry.data = '%SystemRoot%'"}, nil, nil}, diff --git a/pkg/filter/filter_test.go b/pkg/filter/filter_test.go index 8333a5f9e..a856d9d5d 100644 --- a/pkg/filter/filter_test.go +++ b/pkg/filter/filter_test.go @@ -958,7 +958,7 @@ func TestRegistryFilter(t *testing.T) { params.RegData: {Name: params.RegData, Type: params.Uint32, Value: uint32(10234)}, params.RegValueType: {Name: params.RegValueType, Type: params.AnsiString, Value: "DWORD"}, params.NTStatus: {Name: params.NTStatus, Type: params.AnsiString, Value: "success"}, - params.RegKeyHandle: {Name: params.RegKeyHandle, Type: params.Address, Value: uint64(18446666033449935464)}, + params.RegKCB: {Name: params.RegKCB, Type: params.Address, Value: uint64(18446666033449935464)}, }, }