perf: Eventset masks (#241)

Author: rabbitstack

go.mod

@@ -41,6 +41,7 @@ require (
 )
 
 require (
+	github.com/bits-and-blooms/bitset v1.13.0 // indirect
 	github.com/rivo/uniseg v0.4.2 // indirect
 	github.com/rogpeppe/go-internal v1.11.0 // indirect
 	golang.org/x/arch v0.6.0 // indirect

go.sum

@@ -26,6 +26,8 @@ github.com/armon/consul-api v0.0.0-20180202201655-eb2c6b5be1b6/go.mod h1:grANhF5
 github.com/aws/aws-sdk-go v1.34.13/go.mod h1:5zCpMtNQVjRREroY7sYe8lOMRSxkhG6MZveU8YkpAk0=
 github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q=
 github.com/beorn7/perks v1.0.0/go.mod h1:KWe93zE9D1o94FZ5RNwFwVgaQK1VOXiVxmqh+CedLV8=
+github.com/bits-and-blooms/bitset v1.13.0 h1:bAQ9OPNFYbGHV6Nez0tmNI0RiEu7/hxlYJRUA0wFAVE=
+github.com/bits-and-blooms/bitset v1.13.0/go.mod h1:7hO7Gc7Pp1vODcmWvKMRA9BNmbv6a/7QIWpPxHddWR8=
 github.com/briandowns/spinner v1.12.0 h1:72O0PzqGJb6G3KgrcIOtL/JAGGZ5ptOMCn9cUHmqsmw=
 github.com/briandowns/spinner v1.12.0/go.mod h1:QOuQk7x+EaDASo80FEXwlwiA+j/PPIcX3FScO+3/ZPQ=
 github.com/cespare/xxhash v1.1.0/go.mod h1:XrSqR1VqqWfGrhpAt58auRo0WTKS1nRRg3ghfAqPWnc=

pkg/config/kstream.go

@@ -22,6 +22,7 @@
 package config
 
 import (
+	"golang.org/x/sys/windows"
 	"runtime"
 	"time"
 
@@ -95,7 +96,8 @@ type KstreamConfig struct {
 	// ExcludedImages are process image names that will be rejected if they generate a kernel event.
 	ExcludedImages []string `json:"blacklist.images" yaml:"blacklist.images"`
 
-	excludedKtypes map[ktypes.Ktype]bool
+	eventsetMasks ktypes.EventsetMasks
+
 	excludedImages map[string]bool
 }
 
@@ -117,12 +119,11 @@ func (c *KstreamConfig) initFromViper(v *viper.Viper) {
 	c.ExcludedKevents = v.GetStringSlice(excludedEvents)
 	c.ExcludedImages = v.GetStringSlice(excludedImages)
 
-	c.excludedKtypes = make(map[ktypes.Ktype]bool)
 	c.excludedImages = make(map[string]bool)
 
 	for _, name := range c.ExcludedKevents {
 		if ktype := ktypes.KeventNameToKtype(name); ktype != ktypes.UnknownKtype {
-			c.excludedKtypes[ktype] = true
+			c.eventsetMasks.Set(ktype)
 		}
 	}
 	for _, name := range c.ExcludedImages {
@@ -132,12 +133,11 @@ func (c *KstreamConfig) initFromViper(v *viper.Viper) {
 
 // Init is an exported method to allow initializing exclusion maps from external modules.
 func (c *KstreamConfig) Init() {
-	c.excludedKtypes = make(map[ktypes.Ktype]bool)
 	c.excludedImages = make(map[string]bool)
 	for _, name := range c.ExcludedKevents {
 		for _, ktype := range ktypes.KeventNameToKtypes(name) {
 			if ktype != ktypes.UnknownKtype {
-				c.excludedKtypes[ktype] = true
+				c.eventsetMasks.Set(ktype)
 			}
 		}
 	}
@@ -146,10 +146,10 @@ func (c *KstreamConfig) Init() {
 	}
 }
 
-// ExcludeKevent determines whether the supplied event type is present in the list of
-// excluded event types.
-func (c *KstreamConfig) ExcludeKevent(ktype ktypes.Ktype) bool {
-	return c.excludedKtypes[ktype]
+// ExcludeKevent determines whether the supplied provider GUID
+// and the hook identifier are in the bitset of excluded events.
+func (c *KstreamConfig) ExcludeKevent(guid windows.GUID, hookID uint16) bool {
+	return c.eventsetMasks.Test(guid, hookID)
 }
 
 // ExcludeImage determines whether the process generating event is present in the

pkg/config/kstream_test.go

@@ -56,8 +56,8 @@ func TestKstreamConfig(t *testing.T) {
 	assert.False(t, c.Kstream.EnableImageKevents)
 	assert.False(t, c.Kstream.EnableFileIOKevents)
 
-	assert.True(t, c.Kstream.ExcludeKevent(ktypes.CloseHandle))
-	assert.False(t, c.Kstream.ExcludeKevent(ktypes.CreateProcess))
+	assert.True(t, c.Kstream.ExcludeKevent(ktypes.CloseHandle.GUID(), ktypes.CloseHandle.HookID()))
+	assert.False(t, c.Kstream.ExcludeKevent(ktypes.CreateProcess.GUID(), ktypes.CreateProcess.HookID()))
 
 	assert.True(t, c.Kstream.ExcludeImage(&pstypes.PS{Name: "svchost.exe"}))
 	assert.False(t, c.Kstream.ExcludeImage(&pstypes.PS{Name: "explorer.exe"}))

pkg/kevent/ktypes/eventset.go

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2021-2022 by Nedim Sabic Sabic
+ * https://www.fibratus.io
+ * All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ktypes
+
+import (
+	"github.com/bits-and-blooms/bitset"
+	"golang.org/x/sys/windows"
+)
+
+// EventsetMasks allows efficient testing
+// of a group of bitsets containing event
+// hook identifiers. For each provider
+// is represented by a GUID, a dedicated
+// bitset is defined.
+type EventsetMasks struct {
+	masks [ProvidersCount]bitset.BitSet
+}
+
+// Set puts a new event type into the bitset.
+func (e *EventsetMasks) Set(ktype Ktype) {
+	i := e.bitsetIndex(ktype.GUID())
+	if i < 0 {
+		panic("invalid bitset index")
+	}
+	e.masks[i].Set(uint(ktype.HookID()))
+}
+
+// Test checks if the given provider GUID and
+// hook identifier are present in the bitset.
+func (e *EventsetMasks) Test(guid windows.GUID, hookID uint16) bool {
+	i := e.bitsetIndex(guid)
+	if i < 0 {
+		return false
+	}
+	return e.masks[i].Test(uint(hookID))
+}
+
+// Clear clears the bitset for a given provider GUID.
+func (e *EventsetMasks) Clear(guid windows.GUID) {
+	i := e.bitsetIndex(guid)
+	if i < 0 {
+		panic("invalid bitset index")
+	}
+	e.masks[i].ClearAll()
+}
+
+func (e *EventsetMasks) bitsetIndex(guid windows.GUID) int {
+	switch guid {
+	case ProcessEventGUID:
+		return 0
+	case ThreadEventGUID:
+		return 1
+	case ImageEventGUID:
+		return 2
+	case FileEventGUID:
+		return 3
+	case RegistryEventGUID:
+		return 4
+	case NetworkEventGUID:
+		return 5
+	case HandleEventGUID:
+		return 6
+	case MemEventGUID:
+		return 7
+	case AuditAPIEventGUID:
+		return 8
+	case DNSEventGUID:
+		return 9
+	}
+	return -1
+}

pkg/kevent/ktypes/eventset_test.go

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2021-2022 by Nedim Sabic Sabic
+ * https://www.fibratus.io
+ * All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ktypes
+
+import (
+	"github.com/rabbitstack/fibratus/pkg/sys/etw"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+func TestEventsetMasks(t *testing.T) {
+	var masks EventsetMasks
+	masks.Set(TerminateThread)
+	masks.Set(CreateThread)
+	masks.Set(TerminateProcess)
+
+	require.True(t, masks.Test(ThreadEventGUID, TerminateThread.HookID()))
+	require.True(t, masks.Test(ThreadEventGUID, CreateThread.HookID()))
+	require.False(t, masks.Test(ThreadEventGUID, ThreadRundown.HookID()))
+	require.True(t, masks.Test(ProcessEventGUID, TerminateProcess.HookID()))
+	require.False(t, masks.Test(ProcessEventGUID, CreateProcess.HookID()))
+
+	masks.Clear(ThreadEventGUID)
+
+	require.False(t, masks.Test(ThreadEventGUID, TerminateThread.HookID()))
+	require.False(t, masks.Test(ThreadEventGUID, CreateThread.HookID()))
+}
+
+func BenchmarkEventsetMasks(b *testing.B) {
+	b.ReportAllocs()
+
+	var masks EventsetMasks
+	masks.Set(TerminateThread)
+	masks.Set(CreateThread)
+	masks.Set(TerminateProcess)
+	masks.Set(CreateFile)
+	
+	evt := etw.EventRecord{Header: etw.EventHeader{ProviderID: ThreadEventGUID, EventDescriptor: etw.EventDescriptor{Opcode: 2}}}
+
+	for i := 0; i < b.N; i++ {
+		if !masks.Test(evt.Header.ProviderID, uint16(evt.Header.EventDescriptor.Opcode)) {
+			panic("mask should be present")
+		}
+	}
+}
+
+func BenchmarkStdlibMap(b *testing.B) {
+	b.ReportAllocs()
+
+	evts := make(map[Ktype]bool)
+	evts[TerminateThread] = true
+	evts[CreateThread] = true
+	evts[TerminateProcess] = true
+	evts[CreateFile] = true
+
+	evt := etw.EventRecord{Header: etw.EventHeader{ProviderID: ThreadEventGUID, EventDescriptor: etw.EventDescriptor{Opcode: 2}}}
+	kt := NewFromEventRecord(&evt)
+
+	for i := 0; i < b.N; i++ {
+		if !evts[kt] {
+			panic("event should be present")
+		}
+	}
+}

pkg/kevent/ktypes/ktypes_windows.go

@@ -25,18 +25,34 @@ import (
 	"golang.org/x/sys/windows"
 )
 
+// ProvidersCount designates the number of interesting providers.
+// Remember to increment if a new event source is introduced.
+const ProvidersCount = 10
+
 // Ktype identifies an event type. It comprises the event GUID + hook ID to uniquely identify the event
 type Ktype [18]byte
 
 var (
-	// ProcessEventGUID represents process event GUID
+	// ProcessEventGUID represents process provider event GUID
 	ProcessEventGUID = windows.GUID{Data1: 0x3d6fa8d0, Data2: 0xfe05, Data3: 0x11d0, Data4: [8]byte{0x9d, 0xda, 0x0, 0xc0, 0x4f, 0xd7, 0xba, 0x7c}}
-	// ThreadEventGUID represents thread evens GUID
+	// ThreadEventGUID represents thread provider event GUID
 	ThreadEventGUID = windows.GUID{Data1: 0x3d6fa8d1, Data2: 0xfe05, Data3: 0x11d0, Data4: [8]byte{0x9d, 0xda, 0x0, 0xc0, 0x4f, 0xd7, 0xba, 0x7c}}
-	// FileEventGUID represents file event GUID
+	// ImageEventGUID represents image provider event GUID
+	ImageEventGUID = windows.GUID{Data1: 0x2cb15d1d, Data2: 0x5fc1, Data3: 0x11d2, Data4: [8]byte{0xab, 0xe1, 0x0, 0xa0, 0xc9, 0x11, 0xf5, 0x18}}
+	// FileEventGUID represents file provider event GUID
 	FileEventGUID = windows.GUID{Data1: 0x90cbdc39, Data2: 0x4a3e, Data3: 0x11d1, Data4: [8]byte{0x84, 0xf4, 0x0, 0x0, 0xf8, 0x04, 0x64, 0xe3}}
-	// RegistryEventGUID represents registry event GUID
+	// RegistryEventGUID represents registry provider event GUID
 	RegistryEventGUID = windows.GUID{Data1: 0xae53722e, Data2: 0xc863, Data3: 0x11d2, Data4: [8]byte{0x86, 0x59, 0x0, 0xc0, 0x4f, 0xa3, 0x21, 0xa1}}
+	// NetworkEventGUID represents network provider event GUID
+	NetworkEventGUID = windows.GUID{Data1: 0x9a280ac0, Data2: 0xc8e0, Data3: 0x11d1, Data4: [8]byte{0x84, 0xe2, 0x0, 0xc0, 0x4f, 0xb9, 0x98, 0xa2}}
+	// HandleEventGUID represents handle provider event GUID
+	HandleEventGUID = windows.GUID{Data1: 0x89497f50, Data2: 0xeffe, Data3: 0x4440, Data4: [8]byte{0x8c, 0xf2, 0xce, 0x6b, 0x1c, 0xdc, 0xac, 0xa7}}
+	// MemEventGUID represents memory provider event GUID
+	MemEventGUID = windows.GUID{Data1: 0x3d6fa8d3, Data2: 0xfe05, Data3: 0x11d0, Data4: [8]byte{0x9d, 0xda, 0x00, 0xc0, 0x4f, 0xd7, 0xba, 0x7c}}
+	// AuditAPIEventGUID represents audit API calls event GUID
+	AuditAPIEventGUID = windows.GUID{Data1: 0xe02a841c, Data2: 0x75a3, Data3: 0x4fa7, Data4: [8]byte{0xaf, 0xc8, 0xae, 0x09, 0xcf, 0x9b, 0x7f, 0x23}}
+	// DNSEventGUID represents DNS provider event GUID
+	DNSEventGUID = windows.GUID{Data1: 0x1c95126e, Data2: 0x7eea, Data3: 0x49a9, Data4: [8]byte{0xa3, 0xfe, 0xa3, 0x78, 0xb0, 0x3d, 0xdb, 0x4d}}
 )
 
 var (
@@ -183,12 +199,7 @@ var (
 
 // NewFromEventRecord creates a new event type from ETW event record.
 func NewFromEventRecord(ev *etw.EventRecord) Ktype {
-	switch ev.Header.ProviderID {
-	case etw.KernelAuditAPICallsGUID, etw.DNSClientGUID:
-		return pack(ev.Header.ProviderID, ev.Header.EventDescriptor.ID)
-	default:
-		return pack(ev.Header.ProviderID, uint16(ev.Header.EventDescriptor.Opcode))
-	}
+	return pack(ev.Header.ProviderID, ev.HookID())
 }
 
 // String returns the string representation of the event type. Returns an empty string

pkg/kstream/consumer_windows.go

@@ -201,15 +201,15 @@ func (k *consumer) processEvent(ev *etw.EventRecord) error {
 	if kevent.IsCurrentProcDropped(ev.Header.ProcessID) {
 		return nil
 	}
+	if k.config.Kstream.ExcludeKevent(ev.Header.ProviderID, ev.HookID()) {
+		excludedKevents.Add(1)
+		return nil
+	}
 	ktype := ktypes.NewFromEventRecord(ev)
 	if !ktype.Exists() {
 		keventsUnknown.Add(1)
 		return nil
 	}
-	if k.config.Kstream.ExcludeKevent(ktype) {
-		excludedKevents.Add(1)
-		return nil
-	}
 	keventsProcessed.Add(1)
 	evt := kevent.New(k.sequencer.Get(), ktype, ev)
 	// Dispatch each event to the processor chain.

pkg/sys/etw/types.go

@@ -554,6 +554,14 @@ func (e *EventRecord) Version() uint8 {
 	return e.Header.EventDescriptor.Version
 }
 
+// HookID returns either the opcode or the event ID.
+func (e *EventRecord) HookID() uint16 {
+	if e.Header.EventDescriptor.Opcode > 0 {
+		return uint16(e.Header.EventDescriptor.Opcode)
+	}
+	return e.Header.EventDescriptor.ID
+}
+
 // ReadByte reads the byte from the buffer at the specified offset.
 func (e *EventRecord) ReadByte(offset uint16) byte {
 	if offset > e.BufferLen {