feat(yara): Rule matches as tags in event metadata (#103)

* YARA rule matches as tags in event metadata

* add space

Author: rabbitstack

docs/_coverpage.md

@@ -4,7 +4,7 @@
   <img src='logo.png'></img>
 </div>
 
-# fibratus <small>1.4.1</small>
+# fibratus <small>1.4.2</small>
 
 > A modern tool for the Windows kernel exploration and observability
 

docs/yara/alerts.md

@@ -104,3 +104,40 @@ Resources:
   ProductName: Microsoft® Windows® Operating System
   ProductVersion: 10.0.18362.693
 ```
+
+##  Event metadata {docsify-ignore}
+
+When the event triggers a specific YARA rule, its metadata is automatically decorated with the rule matches. 
+The `yara.matches` tag contains the JSON array payload where each object represents the YARA rule match. For example:
+
+```json
+[
+  {
+    "Rule": "AnglerEKredirector ",
+    "Namespace": "EK",
+    "Tags": null,
+    "Metas": [
+      {
+        "Identifier": "description",
+        "Value": "Angler Exploit Kit Redirector"
+      }
+    ],
+    "Strings": "..."
+  },
+  {
+    "Rule": "angler_flash_uncompressed ",
+    "Namespace": "EK",
+    "Tags": [
+      "exploitkit"
+    ],
+    "Metas": [
+      {
+        "Identifier": "description",
+        "Value": "Angler Exploit Kit Detection"
+      }
+    ],
+    "Strings": "..."
+  }
+]
+```
+

pkg/filter/rules.go

@@ -32,7 +32,6 @@ import (
 	"text/template"
 )
 
-
 const (
 	// ruleNameMeta identifies the rule that was triggered by the event
 	ruleNameMeta = "rule.name"

pkg/kstream/interceptors/image_windows.go

@@ -20,6 +20,7 @@ package interceptors
 
 import (
 	"expvar"
+
 	"github.com/rabbitstack/fibratus/pkg/fs"
 	"github.com/rabbitstack/fibratus/pkg/kevent"
 	"github.com/rabbitstack/fibratus/pkg/kevent/kparams"
@@ -67,7 +68,7 @@ func (i *imageInterceptor) Intercept(kevt *kevent.Kevent) (*kevent.Kevent, bool,
 			// scan the the target filename
 			go func() {
 				imageYaraScans.Add(1)
-				err := i.yara.ScanFile(filename)
+				err := i.yara.ScanFile(filename, kevt)
 				if err != nil {
 					log.Warnf("unable to run yara scanner on %s image: %v", filename, err)
 				}

pkg/kstream/interceptors/ps_windows.go

@@ -20,18 +20,19 @@ package interceptors
 
 import (
 	"expvar"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
 	"github.com/rabbitstack/fibratus/pkg/kevent"
 	"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/syscall/process"
 	"github.com/rabbitstack/fibratus/pkg/yara"
 	log "github.com/sirupsen/logrus"
-	"os"
-	"path/filepath"
-	"regexp"
-	"strings"
-	"time"
 )
 
 // systemRootRegexp is the regular expression for detecting path with unexpanded SystemRoot environment variable
@@ -122,7 +123,7 @@ func (ps psInterceptor) Intercept(kevt *kevent.Kevent) (*kevent.Kevent, bool, er
 				// run yara scanner on the target process
 				go func() {
 					procYaraScans.Add(1)
-					err := ps.yara.ScanProc(pid)
+					err := ps.yara.ScanProc(pid, kevt)
 					if err != nil {
 						log.Warnf("unable to run yara scanner on pid %d: %v", pid, err)
 					}

pkg/yara/scanner.go

@@ -23,23 +23,29 @@ package yara
 
 import (
 	"bytes"
+	"encoding/json"
 	"expvar"
 	"fmt"
+	"html/template"
+	"os"
+	"path/filepath"
+	"time"
+
 	"github.com/hillu/go-yara/v4"
 	"github.com/rabbitstack/fibratus/pkg/alertsender"
+	"github.com/rabbitstack/fibratus/pkg/kevent"
 	"github.com/rabbitstack/fibratus/pkg/ps"
 	pstypes "github.com/rabbitstack/fibratus/pkg/ps/types"
 	"github.com/rabbitstack/fibratus/pkg/util/multierror"
 	"github.com/rabbitstack/fibratus/pkg/yara/config"
 	log "github.com/sirupsen/logrus"
-	"html/template"
-	"os"
-	"path/filepath"
-	"time"
 )
 
 const alertTitleTmpl = `{{if .PS }}YARA alert on process {{ .PS.Name }}{{ else }}YARA alert on file {{ .Filename }}{{ end }}`
 
+// matchesMeta is the tag name for the yara matches
+const matchesMeta = "yara.matches"
+
 var (
 	// ruleMatches computes all the rule matches
 	ruleMatches = expvar.NewInt("yara.rule.matches")
@@ -159,7 +165,7 @@ func parseCompilerErrors(errors []yara.CompilerMessage) error {
 	return multierror.Wrap(errs...)
 }
 
-func (s scanner) ScanProc(pid uint32) error {
+func (s scanner) ScanProc(pid uint32, kevt *kevent.Kevent) error {
 	proc := s.psnap.Find(pid)
 	if proc == nil {
 		return fmt.Errorf("cannot scan proc. pid %d does not exist in snapshotter", pid)
@@ -183,15 +189,20 @@ func (s scanner) ScanProc(pid uint32) error {
 	}
 	ruleMatches.Add(int64(len(matches)))
 
+	if err := putMatchesMeta(matches, kevt); err != nil {
+		return err
+	}
+
 	ctx := AlertContext{
 		PS:        proc,
 		Matches:   matches,
 		Timestamp: time.Now().Format(tsLayout),
 	}
+
 	return s.send(ctx)
 }
 
-func (s scanner) ScanFile(filename string) error {
+func (s scanner) ScanFile(filename string, kevt *kevent.Kevent) error {
 	if s.config.SkipFiles || s.config.ShouldSkipFile(filename) {
 		return nil
 	}
@@ -210,6 +221,10 @@ func (s scanner) ScanFile(filename string) error {
 	}
 	ruleMatches.Add(int64(len(matches)))
 
+	if err := putMatchesMeta(matches, kevt); err != nil {
+		return err
+	}
+
 	ctx := AlertContext{
 		Filename:  filename,
 		Matches:   matches,
@@ -281,6 +296,16 @@ func tagsFromMatches(matches []yara.MatchRule) []string {
 	return tags
 }
 
+// putMatchesMeta injects rule matches into event metadata as a JSON payload.
+func putMatchesMeta(matches yara.MatchRules, kevt *kevent.Kevent) error {
+	b, err := json.Marshal(matches)
+	if err != nil {
+		return nil
+	}
+	kevt.AddMeta(matchesMeta, string(b))
+	return nil
+}
+
 func (s scanner) Close() {
 	if s.c != nil {
 		s.c.Destroy()

pkg/yara/scanner_test.go

@@ -22,6 +22,16 @@
 package yara
 
 import (
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/hillu/go-yara/v4"
+	"github.com/rabbitstack/fibratus/pkg/kevent"
+	"github.com/rabbitstack/fibratus/pkg/kevent/ktypes"
+
 	"github.com/rabbitstack/fibratus/pkg/alertsender"
 	htypes "github.com/rabbitstack/fibratus/pkg/handle/types"
 	"github.com/rabbitstack/fibratus/pkg/kevent/kparams"
@@ -34,11 +44,6 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
-	"os"
-	"path/filepath"
-	"syscall"
-	"testing"
-	"time"
 )
 
 var yaraAlert *alertsender.Alert
@@ -167,8 +172,19 @@ func TestScan(t *testing.T) {
 		time.Sleep(time.Millisecond * 100)
 	}
 
+	kevt := &kevent.Kevent{
+		Type: ktypes.CreateProcess,
+		Name: "CreateProcess",
+		Tid:  2484,
+		PID:  859,
+		Kparams: kevent.Kparams{
+			kparams.ProcessName: {Name: kparams.ProcessName, Type: kparams.UnicodeString, Value: "svchost.exe"},
+		},
+		Metadata: make(map[string]string),
+	}
+
 	// test attaching on pid
-	require.NoError(t, s.ScanProc(pi.ProcessId))
+	require.NoError(t, s.ScanProc(pi.ProcessId, kevt))
 	require.NotNil(t, yaraAlert)
 
 	assert.Equal(t, "YARA alert on process notepad.exe", yaraAlert.Title)
@@ -177,10 +193,35 @@ func TestScan(t *testing.T) {
 
 	// test file scanning on DLL that merely contains
 	// the fmt.Println("Go Yara DLL Test") statement
-	require.NoError(t, s.ScanFile("_fixtures/yara-test.dll"))
+	require.NoError(t, s.ScanFile("_fixtures/yara-test.dll", kevt))
 	require.NotNil(t, yaraAlert)
 
 	assert.Equal(t, "YARA alert on file _fixtures/yara-test.dll", yaraAlert.Title)
 	assert.Contains(t, yaraAlert.Tags, "dll")
 
 }
+
+func TestMatchesMeta(t *testing.T) {
+	yaraMatches := []yara.MatchRule{
+		{Rule: "test", Namespace: "ns1"},
+		{Rule: "test2", Namespace: "ns2", Tags: []string{"dropper"}, Metas: []yara.Meta{{Identifier: "author", Value: "rabbit"}}},
+	}
+
+	kevt := &kevent.Kevent{
+		Type: ktypes.CreateProcess,
+		Name: "CreateProcess",
+		Tid:  2484,
+		PID:  859,
+		Kparams: kevent.Kparams{
+			kparams.ProcessName: {Name: kparams.ProcessName, Type: kparams.UnicodeString, Value: "svchost.exe"},
+		},
+		Metadata: make(map[string]string),
+	}
+
+	assert.Empty(t, kevt.Metadata)
+
+	putMatchesMeta(yaraMatches, kevt)
+
+	assert.NotEmpty(t, kevt.Metadata)
+	assert.Contains(t, kevt.Metadata, matchesMeta)
+}

pkg/yara/types.go

@@ -18,14 +18,16 @@
 
 package yara
 
+import "github.com/rabbitstack/fibratus/pkg/kevent"
+
 // Scanner watches for certain kernel events such as process creation or image loading and
 // triggers the scanning either of the target process or image file. If matches occur, an
 // alert is emitted via specified alert sender.
 type Scanner interface {
 	// ScanProc scans process memory.
-	ScanProc(pid uint32) error
+	ScanProc(pid uint32, kevt *kevent.Kevent) error
 	// ScanFile scans the specified file in the file system.
-	ScanFile(filename string) error
+	ScanFile(filename string, kevt *kevent.Kevent) error
 	// Close disposes any resources allocated by scanner.
 	Close()
 }