feat(kevent): Introduce image signature event parameters and rule macros (#169)

* Introduce image signature event parameters and rule macros

* Surround expressions inside parenthesis

* Small refactoring and additional tests for catalog checking and image processor

* Address lint warnings

Author: rabbitstack

pkg/filter/accessor_windows.go

@@ -640,6 +640,10 @@ func (i *imageAccessor) get(f fields.Field, kevt *kevent.Kevent) (kparams.Value,
 		return kevt.Kparams.GetUint32(kparams.ImageCheckSum)
 	case fields.ImagePID:
 		return kevt.Kparams.GetPid()
+	case fields.ImageSignatureType:
+		return kevt.GetParamAsString(kparams.ImageSignatureType), nil
+	case fields.ImageSignatureLevel:
+		return kevt.GetParamAsString(kparams.ImageSignatureLevel), nil
 	}
 	return nil, nil
 }

pkg/filter/fields/fields_windows.go

@@ -332,6 +332,10 @@ const (
 	ImageName Field = "image.name"
 	// ImagePID is the pid of the process where the image was loaded
 	ImagePID Field = "image.pid"
+	// ImageSignatureType represents the image signature type
+	ImageSignatureType Field = "image.signature.type"
+	// ImageSignatureLevel represents the image signature level
+	ImageSignatureLevel Field = "image.signature.level"
 
 	// None represents the unknown field
 	None Field = ""
@@ -497,6 +501,8 @@ var fields = map[Field]FieldInfo{
 	ImageSize:           {ImageSize, "image size", kparams.Uint32, []string{"image.size > 1024"}, nil},
 	ImageDefaultAddress: {ImageDefaultAddress, "default image address", kparams.HexInt64, []string{"image.default.address = '7efe0000'"}, nil},
 	ImagePID:            {ImagePID, "target process identifier", kparams.Uint32, []string{"image.pid = 80"}, nil},
+	ImageSignatureType:  {ImageSignatureType, "image signature type", kparams.AnsiString, []string{"image.signature.type != 'NONE'"}, nil},
+	ImageSignatureLevel: {ImageSignatureLevel, "image signature level", kparams.AnsiString, []string{"image.signature.level = 'AUTHENTICODE'"}, nil},
 
 	FileObject:     {FileObject, "file object address", kparams.Uint64, []string{"file.object = 18446738026482168384"}, nil},
 	FileName:       {FileName, "full file name", kparams.UnicodeString, []string{"file.name contains 'mimikatz'"}, nil},

pkg/kevent/kparam_windows.go

@@ -29,6 +29,7 @@ import (
 	"github.com/rabbitstack/fibratus/pkg/util/ip"
 	"github.com/rabbitstack/fibratus/pkg/util/key"
 	"github.com/rabbitstack/fibratus/pkg/util/ntstatus"
+	"github.com/rabbitstack/fibratus/pkg/util/signature"
 	"golang.org/x/sys/windows"
 	"net"
 	"strconv"
@@ -328,10 +329,11 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 		ktypes.UnloadImage,
 		ktypes.ImageRundown:
 		var (
-			pid         uint32
-			checksum    uint32
-			defaultBase uint64
-			filename    string
+			pid               uint32
+			checksum          uint32
+			defaultBase       uint64
+			filename          string
+			sigLevel, sigType uint8
 		)
 		var offset uint16
 		imageBase := evt.ReadUint64(0)
@@ -344,6 +346,8 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 			defaultBase = evt.ReadUint64(30)
 		}
 		if evt.Version() >= 3 {
+			sigLevel = evt.ReadByte(28)
+			sigType = evt.ReadByte(29)
 			defaultBase = evt.ReadUint64(32)
 		}
 		switch {
@@ -363,6 +367,8 @@ func (e *Kevent) produceParams(evt *etw.EventRecord) {
 		e.AppendParam(kparams.ImageBase, kparams.Address, imageBase)
 		e.AppendParam(kparams.ImageSize, kparams.Uint64, imageSize)
 		e.AppendParam(kparams.ImageFilename, kparams.FileDosPath, filename)
+		e.AppendParam(kparams.ImageSignatureLevel, kparams.Enum, uint32(sigLevel), WithEnum(signature.Levels))
+		e.AppendParam(kparams.ImageSignatureType, kparams.Enum, uint32(sigType), WithEnum(signature.Types))
 	case ktypes.RegOpenKey, ktypes.RegCloseKey,
 		ktypes.RegCreateKCB, ktypes.RegDeleteKCB,
 		ktypes.RegKCBRundown, ktypes.RegCreateKey,

pkg/kevent/kparams/fields_windows.go

@@ -127,6 +127,10 @@ const (
 	ImageDefaultBase = "default_address"
 	// ImageFilename is the parameter name that denotes file name and extension of the DLL/executable image.
 	ImageFilename = "file_name"
+	// ImageSignatureLevel is the parameter denoting the loaded module signature level
+	ImageSignatureLevel = "signature_level"
+	// ImageSignatureType is the parameter denoting the loaded module signature type
+	ImageSignatureType = "signature_type"
 
 	// NetSize identifies the parameter name that represents the packet size.
 	NetSize = "size"

pkg/kstream/kstreamc_windows_test.go

@@ -175,7 +175,10 @@ func TestConsumerEvents(t *testing.T) {
 			nil,
 			func(e *kevent.Kevent) bool {
 				img := filepath.Join(os.Getenv("windir"), "System32", "notepad.exe")
-				return e.IsLoadImage() && strings.EqualFold(img, e.GetParamAsString(kparams.ImageFilename))
+				// should get a catalog-signed binary
+				signatureType := e.GetParamAsString(kparams.ImageSignatureType)
+				return e.IsLoadImage() && strings.EqualFold(img, e.GetParamAsString(kparams.ImageFilename)) &&
+					signatureType == "CATALOG_CACHED"
 			},
 			false,
 		},

pkg/kstream/processors/image_windows.go

@@ -22,26 +22,64 @@ import (
 	"github.com/rabbitstack/fibratus/pkg/kevent"
 	"github.com/rabbitstack/fibratus/pkg/kevent/kparams"
 	"github.com/rabbitstack/fibratus/pkg/ps"
+	"github.com/rabbitstack/fibratus/pkg/util/signature"
 )
 
 type imageProcessor struct {
-	psnap ps.Snapshotter
+	psnap      ps.Snapshotter
+	signatures map[uint32]*signature.Signature
 }
 
 func newImageProcessor(psnap ps.Snapshotter) Processor {
-	return &imageProcessor{psnap: psnap}
+	return &imageProcessor{psnap: psnap, signatures: make(map[uint32]*signature.Signature)}
 }
 
 func (imageProcessor) Name() ProcessorType { return Image }
 
-func (i *imageProcessor) ProcessEvent(e *kevent.Kevent) (*kevent.Kevent, bool, error) {
+func (m *imageProcessor) ProcessEvent(e *kevent.Kevent) (*kevent.Kevent, bool, error) {
+	if e.IsLoadImage() {
+		// image signature parameters exhibit unreliable behaviour. Allegedly,
+		// signature verification is not performed in certain circumstances
+		// which leads to the core system DLL or binaries to be reported with
+		// signature unchecked level.
+		// To mitigate this situation, we have to manually check/verify the signature
+		// for all unchecked signature levels
+		level := e.Kparams.MustGetUint32(kparams.ImageSignatureLevel)
+		if level == signature.UncheckedLevel {
+			m.checkSignature(e)
+		}
+	}
 	if e.IsUnloadImage() {
-		return e, false, i.psnap.RemoveModule(e.Kparams.MustGetPid(), e.GetParamAsString(kparams.ImageFilename))
+		return e, false, m.psnap.RemoveModule(e.Kparams.MustGetPid(), e.GetParamAsString(kparams.ImageFilename))
 	}
 	if e.IsLoadImage() {
-		return e, false, i.psnap.AddModule(e)
+		return e, false, m.psnap.AddModule(e)
 	}
 	return e, true, nil
 }
 
 func (imageProcessor) Close() {}
+
+// checkSignature consults the signature cache and if the signature
+// already exists for a particular image checksum, signature checking
+// is skipped. On the contrary, the signature verification is performed
+// and the cache is updated accordingly.
+func (m *imageProcessor) checkSignature(e *kevent.Kevent) {
+	checksum := e.Kparams.MustGetUint32(kparams.ImageCheckSum)
+	sign, ok := m.signatures[checksum]
+	if !ok {
+		filename := e.GetParamAsString(kparams.FileName)
+		sign = signature.Check(filename)
+		if sign == nil {
+			return
+		}
+		if sign.IsSigned() {
+			sign.Verify()
+		}
+		m.signatures[checksum] = sign
+	}
+	if sign != nil {
+		_ = e.Kparams.SetValue(kparams.ImageSignatureType, sign.Type)
+		_ = e.Kparams.SetValue(kparams.ImageSignatureLevel, sign.Level)
+	}
+}

pkg/kstream/processors/image_windows_test.go

@@ -23,8 +23,12 @@ import (
 	"github.com/rabbitstack/fibratus/pkg/kevent/kparams"
 	"github.com/rabbitstack/fibratus/pkg/kevent/ktypes"
 	"github.com/rabbitstack/fibratus/pkg/ps"
+	"github.com/rabbitstack/fibratus/pkg/util/signature"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
+	"os"
+	"path/filepath"
 	"testing"
 )
 
@@ -40,8 +44,11 @@ func TestImageProcessor(t *testing.T) {
 			&kevent.Kevent{
 				Type: ktypes.LoadImage,
 				Kparams: kevent.Kparams{
-					kparams.ImageFilename: {Name: kparams.ImageFilename, Type: kparams.UnicodeString, Value: "C:\\Windows\\system32\\kernel32.dll"},
-					kparams.ProcessID:     {Name: kparams.ProcessID, Type: kparams.PID, Value: uint32(1023)},
+					kparams.ImageFilename:       {Name: kparams.ImageFilename, Type: kparams.UnicodeString, Value: filepath.Join(os.Getenv("windir"), "System32", "kernel32.dll")},
+					kparams.ProcessID:           {Name: kparams.ProcessID, Type: kparams.PID, Value: uint32(1023)},
+					kparams.ImageCheckSum:       {Name: kparams.ImageCheckSum, Type: kparams.Uint32, Value: uint32(2323432)},
+					kparams.ImageSignatureType:  {Name: kparams.ImageSignatureType, Type: kparams.Enum, Value: uint32(0), Enum: signature.Types},
+					kparams.ImageSignatureLevel: {Name: kparams.ImageSignatureLevel, Type: kparams.Enum, Value: uint32(0), Enum: signature.Levels},
 				},
 			},
 			func() *ps.SnapshotterMock {
@@ -51,6 +58,9 @@ func TestImageProcessor(t *testing.T) {
 			},
 			func(e *kevent.Kevent, t *testing.T, psnap *ps.SnapshotterMock) {
 				psnap.AssertNumberOfCalls(t, "AddModule", 1)
+				// should get the signature verified
+				assert.Equal(t, "EMBEDDED", e.GetParamAsString(kparams.ImageSignatureType))
+				assert.Equal(t, "AUTHENTICODE", e.GetParamAsString(kparams.ImageSignatureLevel))
 			},
 		},
 		{

pkg/pe/parser.go

@@ -52,6 +52,7 @@ type opts struct {
 	parseSymbols   bool
 	parseSections  bool
 	parseResources bool
+	parseSecurity  bool
 	sectionEntropy bool
 	sectionMD5     bool
 	excludedImages []string
@@ -113,6 +114,14 @@ func WithVersionResources() Option {
 	}
 }
 
+// WithSecurity indicates if the security directory is parsed to extract signature information
+// like certificates or Authenticode hashes.
+func WithSecurity() Option {
+	return func(o *opts) {
+		o.parseSecurity = true
+	}
+}
+
 // ParseFile parses the PE given the file system path and parser options.
 func ParseFile(path string, opts ...Option) (*PE, error) {
 	return parse(path, nil, opts...)
@@ -171,7 +180,7 @@ func newParserOpts(opts opts) *peparser.Options {
 	return &peparser.Options{
 		DisableCertValidation:     true,
 		OmitIATDirectory:          true,
-		OmitSecurityDirectory:     true,
+		OmitSecurityDirectory:     !opts.parseSecurity,
 		OmitExceptionDirectory:    true,
 		OmitTLSDirectory:          true,
 		OmitCLRHeaderDirectory:    true,
@@ -286,6 +295,10 @@ func parse(path string, data []byte, options ...Option) (*PE, error) {
 		}
 	}
 
+	if opts.parseSecurity {
+		p.IsSigned = pe.IsSigned
+	}
+
 	return p, nil
 }
 

pkg/pe/types.go

@@ -76,6 +76,8 @@ type PE struct {
 	Imports []string `json:"imports"`
 	// VersionResources holds the version resources
 	VersionResources map[string]string `json:"resources"`
+	// IsSigned determines if the PE contains the digital signature.
+	IsSigned bool `json:"is_signed"`
 }
 
 // String returns the string representation of the PE metadata.

pkg/sys/syscall.go

@@ -41,3 +41,12 @@ package sys
 
 // Windows Terminal Server Functions
 //sys WTSQuerySessionInformationA(handle windows.Handle, sessionID uint32, klass uint8, buf **uint16, size *uint32) (err error) = wtsapi32.WTSQuerySessionInformationW
+
+// Windows Trust Functions
+//sys WinVerifyTrust(handle windows.Handle, action *windows.GUID, data *WintrustData) (ret uint32, err error) [failretval!=0] = wintrust.WinVerifyTrust
+//sys CryptCatalogAdminAcquireContext(handle *windows.Handle, subsystem *windows.GUID, hashAlgorithm *uint16, hashPolicy uintptr, flags uint32) (err error) = wintrust.CryptCATAdminAcquireContext2
+//sys CryptCatalogAdminReleaseContext(handle windows.Handle, flags int32) (ok bool) = wintrust.CryptCATAdminReleaseContext
+//sys CryptCatalogAdminCalcHashFromFileHandle(handle windows.Handle, fd uintptr, size *uint32, hash uintptr, flags uint32) (err error) = wintrust.CryptCATAdminCalcHashFromFileHandle2
+//sys CryptCatalogAdminEnumCatalogFromHash(handle windows.Handle, hash uintptr, size uint32, flags uint32, prevCatalog *windows.Handle) (catalog windows.Handle) = wintrust.CryptCATAdminEnumCatalogFromHash
+//sys CryptCatalogInfoFromContext(handle windows.Handle, catalog *CatalogInfo, flags uint32) (err error) = wintrust.CryptCATCatalogInfoFromContext
+//sys CryptCatalogAdminReleaseCatalogContext(handle windows.Handle, info windows.Handle, flags uint32) (err error) = wintrust.CryptCATAdminReleaseCatalogContext