feat(evasion): Evasion scanner

This changeset establishes the architecture for the
evasion scanner. Evasion scanner piggybacks on top
of different evasion detectors such as direct syscall
(being the first evasion behaviour implemented).
When the evasion behaviour is detected, the event is
decorated with such evasion in its metadata.

Author: rabbitstack

.github/PULL_REQUEST_TEMPLATE.md

@@ -68,6 +68,8 @@
 
 > /area deps
 
+> /area evasion
+
 > /area other
 
 

.github/workflows/master.yml

@@ -169,6 +169,10 @@ jobs:
         run: |
           cd yara
           make install
+      - name: Setup test fixtures
+        run: |
+          choco install -y go-task
+          task --taskfile internal/etw/_fixtures/Taskfile.yml all
       - name: Test
         shell: bash
         run: |

.github/workflows/pr.yml

@@ -151,6 +151,10 @@ jobs:
         run: |
           cd yara
           make install
+      - name: Setup test fixtures
+        run: |
+          choco install -y go-task
+          task --taskfile internal/etw/_fixtures/Taskfile.yml all
       - name: Test
         shell: bash
         run: |

configs/fibratus.yml

@@ -156,6 +156,21 @@ handle:
   # Indicates if process handles are collected during startup or when a new process is spawn.
   enumerate-handles: false
 
+# =============================== Evasion ====================================================
+
+# Tweaks for controlling evasion scanner behaviours. Evasion behaviours can represent strong
+# IoC (Indicators of Compromise) such as direct syscall or require a combination of fine-tune
+# exceptions to reduce the alert fatigue.
+evasion:
+  # Indicates if evasion detections are enabled global-wise. If disabled, evasion scanner will
+  # not try to classify ad-hoc evasion techniques.
+  enabled: true
+
+  # Indicates if direct syscall evasion detection is enabled. A direct syscall bypasses Windows
+  # API functions and calls the underlying system call directly using the syscall instruction,
+  # skipping the NTDLL stub that normally performs the transition to kernel mode.
+  #enable-direct-syscall: true
+
 # =============================== Event ===============================================
 
 # The following settings control the state of the event.

internal/bootstrap/bootstrap.go

@@ -21,6 +21,7 @@ package bootstrap
 import (
 	"context"
 	"errors"
+	"github.com/rabbitstack/fibratus/internal/evasion"
 	"github.com/rabbitstack/fibratus/pkg/aggregator"
 	"github.com/rabbitstack/fibratus/pkg/alertsender"
 	"github.com/rabbitstack/fibratus/pkg/api"
@@ -233,6 +234,10 @@ func (f *App) Run(args []string) error {
 			f.symbolizer = symbolize.NewSymbolizer(symbolize.NewDebugHelpResolver(cfg), f.psnap, cfg, false)
 			f.evs.RegisterEventListener(f.symbolizer)
 		}
+		// register evasion scanner
+		if cfg.Evasion.Enabled {
+			f.evs.RegisterEventListener(evasion.NewScanner(cfg.Evasion))
+		}
 		// register rule engine
 		if f.engine != nil {
 			f.evs.RegisterEventListener(f.engine)

internal/etw/_fixtures/Taskfile.yml

@@ -0,0 +1,20 @@
+version: '3'
+
+vars:
+  SYSWHISPERS3_REPO: https://github.com/klezVirus/SysWhispers3.git
+  VISUAL_STUDIO_EDITION: Enterprise
+  VISUAL_STUDIO_VERSION: 2022
+
+tasks:
+  direct-syscall:
+    desc: Builds the binary to perform direct syscalls via Syswhispers generated stubs
+    dir: direct-syscall
+    cmds:
+      - git clone {{ .SYSWHISPERS3_REPO }}
+      - python SysWhispers3/syswhispers.py -a x64 -c msvc -p common -o syscalls
+      - cmd.exe /c 'C:\"Program Files"\"Microsoft Visual Studio"\{{ .VISUAL_STUDIO_VERSION }}\{{ .VISUAL_STUDIO_EDITION }}\VC\Auxiliary\Build\vcvars64.bat && nmake -f Makefile.msvc'
+    silent: true
+
+  all:
+    deps:
+      - direct-syscall

internal/etw/_fixtures/direct-syscall/.gitignore

@@ -0,0 +1,6 @@
+SysWhishpers3
+*.obj
+*.asm
+*.exe
+syscalls.c
+syscalls.h

internal/etw/_fixtures/direct-syscall/Makefile.msvc

@@ -0,0 +1,7 @@
+OPTIONS = -Zp8 -c -nologo -Gy -Os -O1 -GR- -EHa -Oi -GS-
+LIBS = libvcruntime.lib libcmt.lib ucrt.lib kernel32.lib
+
+main:
+  ML64 /c syscalls-asm.x64.asm /link /NODEFAULTLIB /RELEASE /MACHINE:X64
+  cl.exe $(OPTIONS) syscalls.c main.c
+  link.exe /OUT:direct-syscall.exe -nologo $(LIBS) /MACHINE:X64 -subsystem:console -nodefaultlib syscalls-asm.x64.obj syscalls.obj main.obj

internal/etw/_fixtures/direct-syscall/main.c

@@ -0,0 +1,9 @@
+#include "syscalls.h"
+
+#include <Windows.h>
+
+int main(int argc, char* argv[])
+{
+    Sw3NtSetContextThread(-1, NULL);
+    return 0;
+}

internal/etw/source_test.go

@@ -20,6 +20,7 @@ package etw
 import (
 	"context"
 	"fmt"
+	"github.com/rabbitstack/fibratus/internal/evasion"
 	"github.com/rabbitstack/fibratus/pkg/config"
 	"github.com/rabbitstack/fibratus/pkg/event"
 	"github.com/rabbitstack/fibratus/pkg/event/params"
@@ -41,6 +42,7 @@ import (
 	"net"
 	"net/http"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -1294,6 +1296,127 @@ func testCallstackEnrichment(t *testing.T, hsnap handle.Snapshotter, psnap ps.Sn
 	}
 }
 
+func containsEvasion(e *event.Event, evasion string) bool {
+	m := e.GetMeta(event.EvasionsKey)
+	evas, ok := m.([]string)
+	if !ok {
+		return false
+	}
+	for _, eva := range evas {
+		if eva == evasion {
+			return true
+		}
+	}
+	return false
+}
+
+func TestEvasionScanner(t *testing.T) {
+	var tests = []*struct {
+		name      string
+		gen       func() error
+		want      func(e *event.Event) bool
+		completed bool
+	}{
+		{
+			"direct syscall",
+			func() error {
+				cmd := exec.Command("_fixtures/direct-syscall/direct-syscall.exe")
+				return cmd.Run()
+			},
+			func(e *event.Event) bool {
+				if strings.Contains(strings.ToLower(e.Callstack.String()), strings.ToLower("direct-syscall.exe")) && e.Type == event.SetThreadContext {
+					log.Info(e, e.Callstack)
+					return containsEvasion(e, "direct_syscall")
+				}
+				return false
+			},
+			false,
+		},
+	}
+
+	evsConfig := config.EventSourceConfig{
+		EnableThreadEvents:   true,
+		EnableImageEvents:    true,
+		EnableFileIOEvents:   false,
+		EnableVAMapEvents:    true,
+		EnableNetEvents:      true,
+		EnableRegistryEvents: false,
+		EnableMemEvents:      false,
+		EnableHandleEvents:   false,
+		EnableDNSEvents:      false,
+		EnableAuditAPIEvents: true,
+		StackEnrichment:      true,
+	}
+	evsConfig.Init()
+
+	hsnap := new(handle.SnapshotterMock)
+	hsnap.On("FindByObject", mock.Anything).Return(htypes.Handle{}, false)
+	hsnap.On("FindHandles", mock.Anything).Return([]htypes.Handle{}, nil)
+	hsnap.On("Write", mock.Anything).Return(nil)
+	hsnap.On("Remove", mock.Anything).Return(nil)
+
+	cfg := &config.Config{EventSource: evsConfig, Filters: &config.Filters{}}
+
+	psnap := ps.NewSnapshotter(hsnap, cfg)
+
+	evs := NewEventSource(psnap, hsnap, cfg, nil)
+
+	l := &MockListener{}
+	evs.RegisterEventListener(l)
+
+	symbolizer := symbolize.NewSymbolizer(symbolize.NewDebugHelpResolver(cfg), psnap, cfg, true)
+	defer symbolizer.Close()
+	evs.RegisterEventListener(symbolizer)
+
+	scanner := evasion.NewScanner(evasion.Config{Enabled: true, EnableDirectSyscall: true})
+	evs.RegisterEventListener(scanner)
+
+	require.NoError(t, evs.Open(cfg))
+	defer evs.Close()
+
+	time.Sleep(time.Second * 2)
+
+	for _, tt := range tests {
+		gen := tt.gen
+		if gen != nil {
+			log.Infof("executing [%s] evasion test generator", tt.name)
+			require.NoError(t, gen(), tt.name)
+		}
+	}
+
+	ntests := len(tests)
+	timeout := time.After(time.Duration(ntests) * time.Minute)
+
+	for {
+		select {
+		case e := <-evs.Events():
+			for _, tt := range tests {
+				if tt.completed {
+					continue
+				}
+				pred := tt.want
+				if pred(e) {
+					t.Logf("PASS: %s", tt.name)
+					tt.completed = true
+					ntests--
+				}
+				if ntests == 0 {
+					return
+				}
+			}
+		case err := <-evs.Errors():
+			t.Fatalf("FAIL: %v", err)
+		case <-timeout:
+			for _, tt := range tests {
+				if !tt.completed {
+					t.Logf("FAIL: %s", tt.name)
+				}
+			}
+			t.Fatal("FAIL: TestEvasionScanner")
+		}
+	}
+}
+
 var (
 	modadvapi32 = windows.NewLazySystemDLL("advapi32.dll")
 	kernel32    = windows.NewLazySystemDLL("kernel32.dll")