refactor(event): Rename key handle parameter to KCB

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,25 +126,25 @@ 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
 		// path. If none of the aforementioned checks are successful, our
 		// 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)
 

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

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

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

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

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

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},

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