feat(filter): Introduce TEB filter field

The filter field that returns the thread environment block base address. TEB is the userspace representation of a thread.

pkg/filter/accessor_windows.go

@@ -563,6 +563,8 @@ func (t *threadAccessor) Get(f fields.Field, kevt *kevent.Kevent) (kparams.Value
 		return kevt.GetParamAsString(kparams.StartAddr), 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

pkg/filter/fields/fields_windows.go

@@ -171,6 +171,8 @@ const (
 	ThreadEntrypoint Field = "thread.entrypoint"
 	// 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
@@ -666,6 +668,7 @@ var fields = map[Field]FieldInfo{
 	ThreadUstackLimit:                       {ThreadUstackLimit, "limit of the thread's user space stack", kparams.Address, []string{"thread.ustack.limit = '8ffe0000'"}, nil},
 	ThreadEntrypoint:                        {ThreadEntrypoint, "starting address of the function to be executed by the thread", kparams.Address, []string{"thread.entrypoint = '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},

pkg/filter/filter_test.go

@@ -273,6 +273,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.StartAddr:   {Name: kparams.StartAddr, 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)},
@@ -326,6 +327,7 @@ func TestThreadFilter(t *testing.T) {
 		{`thread.ustack.limit = '525f000'`, true},
 		{`thread.kstack.base = 'ffffc307810d6000'`, true},
 		{`thread.kstack.limit = 'ffffc307810cf000'`, 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},

pkg/kevent/kparam_windows.go

@@ -273,6 +273,7 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 			kstack, klimit uint64
 			ustack, ulimit uint64
 			startAddr      uint64
+			teb            uint64
 			basePrio       uint8
 			pagePrio       uint8
 			ioPrio         uint8
@@ -290,6 +291,7 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 			ustack = evt.ReadUint64(24)
 			ulimit = evt.ReadUint64(32)
 			startAddr = evt.ReadUint64(48)
+			teb = evt.ReadUint64(56)
 		}
 		if evt.Version() >= 3 {
 			basePrio = evt.ReadByte(69)
@@ -303,6 +305,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.StartAddr, kparams.Address, startAddr)
+		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)

pkg/kevent/kparams/fields_windows.go

@@ -76,6 +76,8 @@ const (
 	UstackLimit = "ustack_limit"
 	// StartAddr field is the address of the thread main function.
 	StartAddr = "entrypoint"
+	// 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"