feat(filter): Introduce TEB filter field

rabbitstack · rabbitstack · commit b600df7630ff · 2024-10-25T00:01:15.000+02:00
The filter field that returns the thread environment block base address. TEB is the userspace representation of a thread.
diff --git a/pkg/filter/accessor_windows.go b/pkg/filter/accessor_windows.go
@@ -614,6 +614,8 @@ func (t *threadAccessor) Get(f fields.Field, kevt *kevent.Kevent) (kparams.Value
 		return kevt.GetParamAsString(kparams.StartAddress), nil
 	case fields.ThreadPID:
 		return kevt.Kparams.GetUint32(kparams.ProcessID)
+	case fields.ThreadTEB:
+		return kevt.GetParamAsString(kparams.TEB), nil
 	case fields.ThreadAccessMask:
 		if kevt.Type != ktypes.OpenThread {
 			return nil, nil
diff --git a/pkg/filter/fields/fields_windows.go b/pkg/filter/fields/fields_windows.go
@@ -193,6 +193,8 @@ const (
 	ThreadStartAddress Field = "thread.start_address"
 	// ThreadPID is the process identifier where the thread is created
 	ThreadPID Field = "thread.pid"
+	// ThreadTEB is the thread environment block base address
+	ThreadTEB Field = "thread.teb_address"
 	// ThreadAccessMask represents the thread access rights field
 	ThreadAccessMask Field = "thread.access.mask"
 	// ThreadAccessMaskNames represents the thread access rights list field
@@ -701,6 +703,7 @@ var fields = map[Field]FieldInfo{
 	ThreadEntrypoint:                        {ThreadEntrypoint, "starting address of the function to be executed by the thread", kparams.Address, []string{"thread.entrypoint = '7efe0000'"}, &Deprecation{Since: "2.3.0", Fields: []Field{ThreadStartAddress}}},
 	ThreadStartAddress:                      {ThreadStartAddress, "thread start address", kparams.Address, []string{"thread.start_address = '7efe0000'"}, nil},
 	ThreadPID:                               {ThreadPID, "the process identifier where the thread is created", kparams.Uint32, []string{"kevt.pid != thread.pid"}, nil},
+	ThreadTEB:                               {ThreadTEB, "the base address of the thread environment block", kparams.Address, []string{"thread.teb_address = '8f30893000'"}, nil},
 	ThreadAccessMask:                        {ThreadAccessMask, "thread desired access rights", kparams.AnsiString, []string{"thread.access.mask = '0x1fffff'"}, nil},
 	ThreadAccessMaskNames:                   {ThreadAccessMaskNames, "thread desired access rights as a string list", kparams.Slice, []string{"thread.access.mask.names in ('IMPERSONATE')"}, nil},
 	ThreadAccessStatus:                      {ThreadAccessStatus, "thread access status", kparams.UnicodeString, []string{"thread.access.status = 'success'"}, nil},
diff --git a/pkg/filter/filter_test.go b/pkg/filter/filter_test.go
@@ -289,6 +289,7 @@ func TestThreadFilter(t *testing.T) {
 		kparams.ThreadID:     {Name: kparams.ThreadID, Type: kparams.TID, Value: uint32(3453)},
 		kparams.BasePrio:     {Name: kparams.BasePrio, Type: kparams.Uint8, Value: uint8(13)},
 		kparams.StartAddress: {Name: kparams.StartAddress, Type: kparams.Address, Value: uint64(140729524944768)},
+		kparams.TEB:          {Name: kparams.TEB, Type: kparams.Address, Value: uint64(614994620416)},
 		kparams.IOPrio:       {Name: kparams.IOPrio, Type: kparams.Uint8, Value: uint8(2)},
 		kparams.KstackBase:   {Name: kparams.KstackBase, Type: kparams.Address, Value: uint64(18446677035730165760)},
 		kparams.KstackLimit:  {Name: kparams.KstackLimit, Type: kparams.Address, Value: uint64(18446677035730137088)},
@@ -343,6 +344,7 @@ func TestThreadFilter(t *testing.T) {
 		{`thread.kstack.base = 'ffffc307810d6000'`, true},
 		{`thread.kstack.limit = 'ffffc307810cf000'`, true},
 		{`thread.start_address = '7ffe2557ff80'`, true},
+		{`thread.teb_address = '8f30893000'`, true},
 		{`thread.callstack.summary = 'KERNELBASE.dll|KERNEL32.DLL|java.dll|unbacked'`, true},
 		{`thread.callstack.detail icontains 'C:\\WINDOWS\\System32\\KERNELBASE.dll!CreateProcessW+0x66'`, true},
 		{`thread.callstack.modules in ('C:\\WINDOWS\\System32\\KERNELBASE.dll', 'C:\\Program Files\\JetBrains\\GoLand 2021.2.3\\jbr\\bin\\java.dll')`, true},
diff --git a/pkg/kevent/kparam_windows.go b/pkg/kevent/kparam_windows.go
@@ -278,6 +278,7 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 			kstack, klimit uint64
 			ustack, ulimit uint64
 			startAddress   uint64
+			teb            uint64
 			basePrio       uint8
 			pagePrio       uint8
 			ioPrio         uint8
@@ -295,6 +296,7 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 			ustack = evt.ReadUint64(24)
 			ulimit = evt.ReadUint64(32)
 			startAddress = evt.ReadUint64(48)
+			teb = evt.ReadUint64(56)
 		}
 		if evt.Version() >= 3 {
 			basePrio = evt.ReadByte(69)
@@ -308,6 +310,7 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 		e.AppendParam(kparams.UstackBase, kparams.Address, ustack)
 		e.AppendParam(kparams.UstackLimit, kparams.Address, ulimit)
 		e.AppendParam(kparams.StartAddress, kparams.Address, startAddress)
+		e.AppendParam(kparams.TEB, kparams.Address, teb)
 		e.AppendParam(kparams.BasePrio, kparams.Uint8, basePrio)
 		e.AppendParam(kparams.PagePrio, kparams.Uint8, pagePrio)
 		e.AppendParam(kparams.IOPrio, kparams.Uint8, ioPrio)
diff --git a/pkg/kevent/kparams/fields_windows.go b/pkg/kevent/kparams/fields_windows.go
@@ -78,6 +78,8 @@ const (
 	UstackLimit = "ustack_limit"
 	// StartAddress field is the thread start address.
 	StartAddress = "start_address"
+	// TEB field is the address of the Thread Environment Block (TEB)
+	TEB = "teb"
 
 	// FileObject determines the field name for the file object pointer.
 	FileObject = "file_object"
