feat: Driver loading events (#132)

rabbitstack · web-flow · commit f050bc2e016c · 2022-10-18T19:28:42.000+02:00
* introduce Antimalware Engine provider and LoadDriver events

* add LoadDriver event metainfo

* fix tests and build errors
diff --git a/configs/fibratus.yml b/configs/fibratus.yml
@@ -175,6 +175,13 @@ kstream:
   # collected by Kernel Logger provider
   #enable-handle: false
 
+  # Determines whether kernel Audit API calls events are collected
+  #enable-audit-api: true
+
+  # Determines whether the Microsoft Antimalware Engine events are collected. For the
+  # events to be collected it is necessary to enable Windows Defender realtime protection.
+  #enable-antimalware-engine: true
+
   # Determines if raw event buffer parsing is used instead of TDH (Trace Data Helper) API
   # raw-event-parsing: true
 
@@ -184,7 +191,6 @@ kstream:
     # Contains a list of kernel event names that are dropped from the event stream
     events:
       - CloseFile
-      - CloseHandle
     # Contains a list of case-sensitive process image names including the extension.
     # Any event originated by the image specified in this list is dropped from the event stream
     images:
diff --git a/pkg/config/config_windows.go b/pkg/config/config_windows.go
@@ -335,6 +335,8 @@ func (c *Config) addFlags() {
 		c.flags.Bool(enableFileIOKevents, true, "Determines whether disk I/O kernel events are collected by Kernel Logger provider")
 		c.flags.Bool(enableImageKevents, true, "Determines whether file I/O kernel events are collected by Kernel Logger provider")
 		c.flags.Bool(enableHandleKevents, false, "Determines whether object manager kernel events (handle creation/destruction) are collected by Kernel Logger provider")
+		c.flags.Bool(enableAuditAPIEvents, true, "Determines whether kernel audit API calls events are published")
+		c.flags.Bool(enableAntimalwareEngineEvents, true, "Determines whether antimalware engine events are published")
 		c.flags.Int(bufferSize, int(maxBufferSize), "Represents the amount of memory allocated for each event tracing session buffer, in kilobytes. The buffer size affects the rate at which buffers fill and must be flushed (small buffer size requires less memory but it increases the rate at which buffers must be flushed)")
 		c.flags.Int(minBuffers, int(defaultMinBuffers), "Determines the minimum number of buffers allocated for the event tracing session's buffer pool")
 		c.flags.Int(maxBuffers, int(defaultMaxBuffers), "Determines the maximum number of buffers allocated for the event tracing session's buffer pool")
diff --git a/pkg/config/kstream.go b/pkg/config/kstream.go
@@ -33,17 +33,19 @@ import (
 )
 
 const (
-	enableThreadKevents   = "kstream.enable-thread"
-	enableRegistryKevents = "kstream.enable-registry"
-	enableNetKevents      = "kstream.enable-net"
-	enableFileIOKevents   = "kstream.enable-fileio"
-	enableImageKevents    = "kstream.enable-image"
-	enableHandleKevents   = "kstream.enable-handle"
-	bufferSize            = "kstream.buffer-size"
-	minBuffers            = "kstream.min-buffers"
-	maxBuffers            = "kstream.max-buffers"
-	flushInterval         = "kstream.flush-interval"
-	rawEventParsing       = "kstream.raw-event-parsing"
+	enableThreadKevents           = "kstream.enable-thread"
+	enableRegistryKevents         = "kstream.enable-registry"
+	enableNetKevents              = "kstream.enable-net"
+	enableFileIOKevents           = "kstream.enable-fileio"
+	enableImageKevents            = "kstream.enable-image"
+	enableHandleKevents           = "kstream.enable-handle"
+	enableAuditAPIEvents          = "kstream.enable-audit-api"
+	enableAntimalwareEngineEvents = "kstream.enable-antimalware-engine"
+	bufferSize                    = "kstream.buffer-size"
+	minBuffers                    = "kstream.min-buffers"
+	maxBuffers                    = "kstream.max-buffers"
+	flushInterval                 = "kstream.flush-interval"
+	rawEventParsing               = "kstream.raw-event-parsing"
 
 	excludedEvents = "kstream.blacklist.events"
 	excludedImages = "kstream.blacklist.images"
@@ -71,6 +73,10 @@ type KstreamConfig struct {
 	EnableImageKevents bool `json:"enable-image" yaml:"enable-image"`
 	// EnableHandleKevents indicates whether handle creation/disposal events are enabled.
 	EnableHandleKevents bool `json:"enable-handle" yaml:"enable-handle"`
+	// EnableAuditAPIEvents indicates if kernel audit API calls events are enabled
+	EnableAuditAPIEvents bool `json:"enable-audit-api" yaml:"enable-audit-api"`
+	// EnableAntimalwareEngineEvents indicates if Antimalware Engine events are enabled
+	EnableAntimalwareEngineEvents bool `json:"enable-antimalware-engine" yaml:"enable-antimalware-engine"`
 	// BufferSize represents the amount of memory allocated for each event tracing session buffer, in kilobytes.
 	// The buffer size affects the rate at which buffers fill and must be flushed (small buffer size requires
 	// less memory but it increases the rate at which buffers must be flushed).
@@ -100,6 +106,8 @@ func (c *KstreamConfig) initFromViper(v *viper.Viper) {
 	c.EnableFileIOKevents = v.GetBool(enableFileIOKevents)
 	c.EnableImageKevents = v.GetBool(enableImageKevents)
 	c.EnableHandleKevents = v.GetBool(enableHandleKevents)
+	c.EnableAuditAPIEvents = v.GetBool(enableAuditAPIEvents)
+	c.EnableAntimalwareEngineEvents = v.GetBool(enableAntimalwareEngineEvents)
 	c.BufferSize = uint32(v.GetInt(bufferSize))
 	c.MinBuffers = uint32(v.GetInt(minBuffers))
 	c.MaxBuffers = uint32(v.GetInt(maxBuffers))
diff --git a/pkg/config/schema_windows.go b/pkg/config/schema_windows.go
@@ -153,6 +153,8 @@ var schema = `
 				"enable-fileio": 	{"type": "boolean"},
 				"enable-handle": 	{"type": "boolean"},
 				"enable-net": 		{"type": "boolean"},
+				"enable-audit-api": {"type": "boolean"},
+				"enable-antimalware-engine": {"type": "boolean"},
 				"raw-event-parsing":{"type": "boolean"},
 				"min-buffers": 		{"type": "integer", "minimum": 1, "maximum": {{ .MinBuffers }}},
 				"max-buffers": 		{"type": "integer", "minimum": 2, "maximum": {{ .MaxBuffers }}},
diff --git a/pkg/handle/types.go b/pkg/handle/types.go
@@ -66,6 +66,8 @@ const (
 	Process = "Process"
 	// SymbolicLink represents the symbolic link object
 	SymbolicLink = "SymbolicLink"
+	// Driver represents the device driver object
+	Driver = "Driver"
 	// Unknown is the unknown handle object
 	Unknown = "Unknown"
 )
diff --git a/pkg/kevent/kparam.go b/pkg/kevent/kparam.go
@@ -78,6 +78,17 @@ func NewKparamFromKcap(name string, typ kparams.Type, value kparams.Value) *Kpar
 	return &Kparam{Name: name, Type: typ, Value: value}
 }
 
+// NewKparamBuilder yields a new event parameter builder.
+func NewKparamBuilder(n int) Kparams {
+	kpars := make(Kparams, n)
+	return kpars
+}
+
+// Build returns all appended parameters.
+func (kpars Kparams) Build() Kparams {
+	return kpars
+}
+
 // Append adds a new parameter with the specified name, type and value.
 func (kpars Kparams) Append(name string, typ kparams.Type, value kparams.Value) Kparams {
 	kpars[name] = NewKparam(name, typ, value)
diff --git a/pkg/kevent/kparams/canonicalize.go b/pkg/kevent/kparams/canonicalize.go
@@ -30,6 +30,8 @@ const (
 	dirTableBase     = "DirectoryTableBase"
 	userSID          = "UserSID"
 	imageFileName    = "ImageFileName"
+	imageName        = "ImageName"
+	imagePath        = "ImagePath"
 	commandLine      = "CommandLine"
 
 	tthreadID       = "TThreadId"
@@ -105,6 +107,8 @@ func Canonicalize(name string) string {
 		return SessionID
 	case imageFileName:
 		return ProcessName
+	case imageName, imagePath:
+		return ImageFilename
 	case commandLine:
 		return Comm
 	case userSID:
diff --git a/pkg/kevent/ktypes/category.go b/pkg/kevent/ktypes/category.go
@@ -38,6 +38,8 @@ const (
 	Image Category = "image"
 	// Handle is the category for handle events
 	Handle Category = "handle"
+	// Driver is the category for driver events
+	Driver Category = "driver"
 	// Other is the category for uncategorized events
 	Other Category = "other"
 	// Unknown is the category for events that couldn't match any of the previous categories
diff --git a/pkg/kevent/ktypes/ktypes_windows.go b/pkg/kevent/ktypes/ktypes_windows.go
@@ -160,6 +160,9 @@ var (
 	// CloseHandle represents handle closure kernel event
 	CloseHandle = Pack(syscall.GUID{Data1: 0x89497f50, Data2: 0xeffe, Data3: 0x4440, Data4: [8]byte{0x8c, 0xf2, 0xce, 0x6b, 0x1c, 0xdc, 0xac, 0xa7}}, 33)
 
+	// LoadDriver represents kernel driver loading event.
+	LoadDriver = Pack(syscall.GUID{Data1: 0xa002690, Data2: 0x3839, Data3: 0x4e3a, Data4: [8]byte{0xb3, 0xb6, 0x96, 0xd8, 0xdf, 0x86, 0x8d, 0x99}}, 10)
+
 	// UnknownKtype designates unknown kernel event type
 	UnknownKtype = Pack(syscall.GUID{}, 0)
 )
@@ -241,6 +244,8 @@ func (k Ktype) String() string {
 		return "Disconnect"
 	case Retransmit, RetransmitTCPv4, RetransmitTCPv6:
 		return "Retransmit"
+	case LoadDriver:
+		return "LoadDriver"
 	default:
 		return string(k[:])
 	}
@@ -269,6 +274,8 @@ func (k Ktype) Category() Category {
 		return Net
 	case CreateHandle, CloseHandle:
 		return Handle
+	case LoadDriver:
+		return Driver
 	default:
 		return Unknown
 	}
@@ -341,6 +348,8 @@ func (k Ktype) Description() string {
 		return "Creates a new handle"
 	case CloseHandle:
 		return "Closes the handle"
+	case LoadDriver:
+		return "Loads the kernel driver"
 	default:
 		return ""
 	}
@@ -403,7 +412,8 @@ func (k Ktype) Exists() bool {
 		RetransmitTCPv4, RetransmitTCPv6,
 		DisconnectTCPv4, DisconnectTCPv6,
 		SendTCPv4, SendTCPv6, SendUDPv4, SendUDPv6,
-		RecvTCPv4, RecvTCPv6, RecvUDPv4, RecvUDPv6:
+		RecvTCPv4, RecvTCPv6, RecvUDPv4, RecvUDPv6,
+		LoadDriver:
 		return true
 	default:
 		return false
diff --git a/pkg/kevent/ktypes/metainfo_windows.go b/pkg/kevent/ktypes/metainfo_windows.go
@@ -64,6 +64,7 @@ var kevents = map[Ktype]KeventInfo{
 	UnloadImage:        {"UnloadImage", Image, "Unloads the module from the address space of the calling process"},
 	CreateHandle:       {"CreateHandle", Handle, "Creates a new handle"},
 	CloseHandle:        {"CloseHandle", Handle, "Closes the handle"},
+	LoadDriver:         {"LoadDriver", Driver, "Loads the kernel driver"},
 }
 
 var ktypes = map[string]Ktype{
@@ -99,6 +100,7 @@ var ktypes = map[string]Ktype{
 	"Retransmit":         Retransmit,
 	"CreateHandle":       CreateHandle,
 	"CloseHandle":        CloseHandle,
+	"LoadDriver":         LoadDriver,
 }
 
 // KtypeToKeventInfo maps the kernel event type to a structure that stores detailed information about the event.
diff --git a/pkg/kstream/controller_windows.go b/pkg/kstream/controller_windows.go
@@ -76,30 +76,6 @@ func (p TraceProvider) IsKernelLogger() bool {
 	return p.GUID == etw.KernelTraceControlGUID
 }
 
-var providers = []TraceProvider{
-	{
-		// core system events
-		etw.KernelLoggerSession,
-		etw.KernelTraceControlGUID,
-		0x0, // no keywords
-		true,
-	},
-	{
-		// provides a source of events for constructing the state of opened file objects
-		etw.KernelLoggerRundownSession,
-		etw.KernelRundownGUID,
-		0x10, // file rundown events
-		true,
-	},
-	{
-		// supplies the `OpenProcess` and `OpenThread` events
-		etw.KernelAuditAPICallsSession,
-		etw.KernelAuditAPICallsGUID,
-		0x0, // no keywords, so we accept all events
-		true,
-	},
-}
-
 // KtraceController is responsible for managing the life cycle of the tracing sessions.
 type KtraceController interface {
 	// StartKtrace starts configured tracing sessions.
@@ -115,13 +91,45 @@ type ktraceController struct {
 	kstreamConfig config.KstreamConfig
 	// traces contains initiated tracing sessions
 	traces map[string]TraceSession
+	// providers contains a list of enabled ETW providers
+	providers []TraceProvider
 }
 
 // NewKtraceController spins up a new instance of kernel trace controller.
 func NewKtraceController(kstreamConfig config.KstreamConfig) KtraceController {
+	providers := []TraceProvider{
+		{
+			// core system events
+			etw.KernelLoggerSession,
+			etw.KernelTraceControlGUID,
+			0x0, // no keywords
+			true,
+		},
+		{
+			// provides a source of events for constructing the state of opened file objects
+			etw.KernelLoggerRundownSession,
+			etw.KernelRundownGUID,
+			0x10, // file rundown events
+			true,
+		},
+		{
+			// supplies the `OpenProcess` and `OpenThread` events
+			etw.KernelAuditAPICallsSession,
+			etw.KernelAuditAPICallsGUID,
+			0x0, // no keywords, so we accept all events
+			kstreamConfig.EnableAuditAPIEvents,
+		},
+		{
+			etw.AntimalwareEngineSession,
+			etw.AntimalwareEngineGUID,
+			0x0,
+			kstreamConfig.EnableAntimalwareEngineEvents,
+		},
+	}
 	controller := &ktraceController{
 		kstreamConfig: kstreamConfig,
 		traces:        make(map[string]TraceSession),
+		providers:     providers,
 	}
 	return controller
 }
@@ -175,7 +183,7 @@ func (k *ktraceController) StartKtrace() error {
 		flushTimer = time.Second
 	}
 
-	for _, prov := range providers {
+	for _, prov := range k.providers {
 		if !prov.Enabled {
 			log.Warnf("provider for trace [%s] is disabled", prov.TraceName)
 			continue
diff --git a/pkg/kstream/controller_windows_test.go b/pkg/kstream/controller_windows_test.go
@@ -29,7 +29,7 @@ import (
 	"time"
 )
 
-func TestStartKtraceSuccess(t *testing.T) {
+func TestStartKtrace(t *testing.T) {
 	startTrace = func(name string, flags *etw.EventTraceProperties) (etw.TraceHandle, error) {
 		return etw.TraceHandle(1), nil
 	}
@@ -38,16 +38,18 @@ func TestStartKtraceSuccess(t *testing.T) {
 	}
 
 	ktracec := NewKtraceController(config.KstreamConfig{
-		EnableThreadKevents: true,
-		EnableNetKevents:    true,
-		BufferSize:          1024,
-		FlushTimer:          time.Millisecond * 2300,
+		EnableThreadKevents:           true,
+		EnableNetKevents:              true,
+		BufferSize:                    1024,
+		FlushTimer:                    time.Millisecond * 2300,
+		EnableAntimalwareEngineEvents: true,
+		EnableAuditAPIEvents:          true,
 	})
 
 	err := ktracec.StartKtrace()
 
 	require.NoError(t, err)
-	assert.Len(t, ktracec.(*ktraceController).traces, 3)
+	assert.Len(t, ktracec.(*ktraceController).traces, 4)
 }
 
 func TestStartKtraceNoSysResources(t *testing.T) {
diff --git a/pkg/kstream/interceptors/chain_windows.go b/pkg/kstream/interceptors/chain_windows.go
@@ -88,6 +88,9 @@ func NewChain(
 		chain.addInterceptor(newHandleInterceptor(hsnap, handle.NewObjectTypeStore(), devMapper, chain.deferredKevts))
 		go chain.consumeDeferred()
 	}
+	if config.Kstream.EnableAntimalwareEngineEvents {
+		chain.addInterceptor(newDriverInterceptor(devMapper))
+	}
 
 	return chain
 }
diff --git a/pkg/kstream/interceptors/driver.go b/pkg/kstream/interceptors/driver.go
@@ -0,0 +1,47 @@
+/*
+ * 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 interceptors
+
+import (
+	"github.com/rabbitstack/fibratus/pkg/fs"
+	"github.com/rabbitstack/fibratus/pkg/kevent"
+	"github.com/rabbitstack/fibratus/pkg/kevent/kparams"
+	"github.com/rabbitstack/fibratus/pkg/kevent/ktypes"
+)
+
+type driverInterceptor struct {
+	devMapper fs.DevMapper
+}
+
+func newDriverInterceptor(devMapper fs.DevMapper) KstreamInterceptor {
+	return &driverInterceptor{devMapper: devMapper}
+}
+
+func (driverInterceptor) Name() InterceptorType { return Driver }
+func (driverInterceptor) Close()                {}
+
+func (d *driverInterceptor) Intercept(kevt *kevent.Kevent) (*kevent.Kevent, bool, error) {
+	if kevt.Type == ktypes.LoadDriver {
+		filename, _ := kevt.Kparams.GetString(kparams.ImageFilename)
+		if err := kevt.Kparams.SetValue(kparams.ImageFilename, d.devMapper.Convert(filename)); err != nil {
+			return kevt, true, err
+		}
+	}
+	return kevt, true, nil
+}
diff --git a/pkg/kstream/interceptors/handle_windows.go b/pkg/kstream/interceptors/handle_windows.go
diff --git a/pkg/kstream/interceptors/handle_windows_test.go b/pkg/kstream/interceptors/handle_windows_test.go
diff --git a/pkg/kstream/interceptors/interceptor.go b/pkg/kstream/interceptors/interceptor.go
diff --git a/pkg/kstream/kstreamc_windows.go b/pkg/kstream/kstreamc_windows.go
diff --git a/pkg/syscall/driver/driver.go b/pkg/syscall/driver/driver.go
diff --git a/pkg/syscall/driver/driver_test.go b/pkg/syscall/driver/driver_test.go
diff --git a/pkg/syscall/etw/types.go b/pkg/syscall/etw/types.go

Original file line number	Diff line number	Diff line change
`@@ -66,6 +66,8 @@ const (`
`66`	`66`	`Process = "Process"`
`67`	`67`	`// SymbolicLink represents the symbolic link object`
`68`	`68`	`SymbolicLink = "SymbolicLink"`
	`69`	`+ // Driver represents the device driver object`
	`70`	`+ Driver = "Driver"`
`69`	`71`	`// Unknown is the unknown handle object`
`70`	`72`	`Unknown = "Unknown"`
`71`	`73`	`)`
Original file line number	Diff line number	Diff line change
`@@ -64,6 +64,7 @@ var kevents = map[Ktype]KeventInfo{`
`64`	`64`	`UnloadImage: {"UnloadImage", Image, "Unloads the module from the address space of the calling process"},`
`65`	`65`	`CreateHandle: {"CreateHandle", Handle, "Creates a new handle"},`
`66`	`66`	`CloseHandle: {"CloseHandle", Handle, "Closes the handle"},`
	`67`	`+ LoadDriver: {"LoadDriver", Driver, "Loads the kernel driver"},`
`67`	`68`	`}`
`68`	`69`
`69`	`70`	`var ktypes = map[string]Ktype{`
`@@ -99,6 +100,7 @@ var ktypes = map[string]Ktype{`
`99`	`100`	`"Retransmit": Retransmit,`
`100`	`101`	`"CreateHandle": CreateHandle,`
`101`	`102`	`"CloseHandle": CloseHandle,`
	`103`	`+ "LoadDriver": LoadDriver,`
`102`	`104`	`}`
`103`	`105`
`104`	`106`	`// KtypeToKeventInfo maps the kernel event type to a structure that stores detailed information about the event.`