diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04de9ba4a..0cce23494 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,7 +118,7 @@ $ ./make ### Running For The First Time -By default, Fibratus operates in rule engine mode. It loads the rule set from the `%PROGRAM FILES%\Fibratus\Rules` directory and sends security alerts to the [systray](/alerts/senders/systray) notification area. Optionally, it takes response actions when the rule is fired, such as killing the process. +By default, Fibratus operates in rule engine mode. It loads the rule set from the `%PROGRAM FILES%\Fibratus\Rules` directory and sends security alerts to [Eventlog](/alerts/senders/eventlog). Optionally, it takes response actions when the rule is fired, such as killing the process. Alternatively, Fibratus can forward events to [output](/outputs/introduction) sinks, if it started in event forwarding mode. To start Fibratus in event forwarding mode run the next command from the root directory of this repo: @@ -129,7 +129,6 @@ $ .\cmd\fibratus\fibratus.exe run --forward If you want to run Fibratus in rule engine mode, follow the next steps: -- run the systray server or disable the systray alert sender in the configuration file. You can start the systray server by running the `.\cmd\fibratus\fibratus-systray.exe` binary. - modify the configuration file to set the location to the rule files. Go to the `filters` section, and specify the absolute path to the `Rules` and `Macros` directories of this repository. ``` filters: @@ -169,5 +168,3 @@ $ ./make.bat pkg ``` The resulting MSI is placed in the `build\msi` directory. - - diff --git a/README.md b/README.md index f7974f524..e6880fe8d 100644 --- a/README.md +++ b/README.md @@ -34,17 +34,28 @@ Events can also be shipped to a wide array of [output sinks](https://www.fibratu In a nutshell, the Fibratus mantra is defined by the pillars of **realtime behavior detection**, **memory scanning**, and **forensics** capabilities. + +### Installation + +- Download the latest [MSI package](https://github.com/rabbitstack/fibratus/releases) and follow the [UI](https://www.fibratus.io/#/setup/installation) wizard or +alternatively install via `msiexec` in silent mode + +``` +$ msiexec /i fibratus-2.3.0-amd64.msi /qn +``` + ### Quick start --- -- [Install](https://www.fibratus.io/#/setup/installation) Fibratus from the latest [MSI package](https://github.com/rabbitstack/fibratus/releases) - spin up a command line prompt - list credentials from the vault by using the `VaultCmd` tool + ``` $ VaultCmd.exe /listcreds:"Windows Credentials" /all ``` -- `Credential discovery via VaultCmd.exe` rule should trigger displaying the alert in the systray notification area + +`Credential discovery via VaultCmd.exe` rule should trigger and emit the alert to the [Eventlog](https://www.fibratus.io/#/alerts/senders/eventlog). Check the short demo [here](https://www.fibratus.io/#/alerts/senders/images/eventlog.gif). ### Documentation diff --git a/docs/_coverpage.md b/docs/_coverpage.md index 41868712d..25598349b 100755 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -4,7 +4,7 @@ -# fibratus 2.2.1 +# fibratus 2.3.0 > Adversary tradecraft detection, protection, and hunting diff --git a/docs/_sidebar.md b/docs/_sidebar.md index f56ccf491..0134d95e1 100755 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -54,6 +54,8 @@ * [Alert Senders](alerts/senders.md) * [Mail](alerts/senders/mail.md) * [Slack](alerts/senders/slack.md) + * [Systray](alerts/senders/systray.md) + * [Eventlog](alerts/senders/eventlog.md) * [Filament Alerting](alerts/filaments.md) * PE * [Portable Executable Introspection](/pe/introduction.md) diff --git a/docs/alerts/introduction.md b/docs/alerts/introduction.md index f1424d964..d829abc09 100644 --- a/docs/alerts/introduction.md +++ b/docs/alerts/introduction.md @@ -4,6 +4,7 @@ Fibratus has the ability to generate security alerts when the detection or [YARA The alert has the following key components: +- **id** the alert identifier represented as UUID. - **title** summarizes the purpose of the alert. - **text** is the message that further explains what this alert is about as well as actors involved. - **tags** contains a sequence of tags for categorizing the alerts. diff --git a/docs/alerts/senders.md b/docs/alerts/senders.md index 2a94087e0..81214c967 100644 --- a/docs/alerts/senders.md +++ b/docs/alerts/senders.md @@ -5,4 +5,5 @@ You can send alert notifications to your team through email, Slack, or incident - [Mail](/alerts/senders/mail) - [Slack](/alerts/senders/mail) - [Systray](/alerts/senders/systray) +- [Eventlog](/alerts/senders/eventlog) diff --git a/docs/alerts/senders/eventlog.md b/docs/alerts/senders/eventlog.md new file mode 100644 index 000000000..a78838e64 --- /dev/null +++ b/docs/alerts/senders/eventlog.md @@ -0,0 +1,24 @@ +# Eventlog + +The `eventlog` alert sender sends alerts to the [Windows Eventlog](https://sematext.com/glossary/what-is-windows-event-log/). + +

+ +

+ +### Configuration {docsify-ignore} + +The `eventlog` alert sender configuration is located in the `alertsenders.eventlog` section. + +#### enabled + +Indicates whether the `eventlog` alert sender is enabled. + +**default**: `true` + +#### verbose + +Enables/disables the verbose mode. In verbose mode, the full event context, including all parameters and the process information are included +in the log message. + +**default**: `true` diff --git a/docs/alerts/senders/images/eventlog.gif b/docs/alerts/senders/images/eventlog.gif new file mode 100644 index 000000000..c3af9fe41 Binary files /dev/null and b/docs/alerts/senders/images/eventlog.gif differ diff --git a/docs/alerts/senders/systray.md b/docs/alerts/senders/systray.md index 5985deff9..42dfe8926 100644 --- a/docs/alerts/senders/systray.md +++ b/docs/alerts/senders/systray.md @@ -10,7 +10,7 @@ The `systray` alert sender configuration is located in the `alertsenders.systray Indicates whether the `systray` alert sender is enabled. -**default**: `true` +**default**: `false` #### sound @@ -23,4 +23,3 @@ Indicates if the associated sound is played when the balloon notification is sho Instructs not to display the balloon notification if the current user is in quiet time. During this time, most notifications should not be sent or shown. This lets a user become accustomed to a new computer system without those distractions. Quiet time also occurs for each user after an operating system upgrade or clean installation. **default**: `false` - diff --git a/docs/filters/fields.md b/docs/filters/fields.md index 1893f9a83..ce4c86f78 100755 --- a/docs/filters/fields.md +++ b/docs/filters/fields.md @@ -88,6 +88,16 @@ The following tables summarize available field names that can be used in filter | ps.uuid | Unique process identifier resistant to repetition | `ps.uuid > 10000400` | | ps.parent.uuid | Unique parent process identifier resistant to repetition | `ps.parent.uuid = 1843450000440` | | ps.child.uuid | Unique child process identifier resistant to repetition | `ps.child.uuid > 20030000000` | +| ps.child.pe.file.name | Original file name of the child process executable supplied at compile-time | `ps.child.pe.file.name = 'NOTEPAD.EXE'` | +| ps.child.is_wow64 | Indicates if the 32-bit child process is created in 64-bit Windows system | `ps.child.is_wow64` | +| ps.child.is_packaged | Indicates if the child process is packaged with the MSIX technology | `ps.child.is_packaged` | +| ps.child.is_protected | Indicates if the child process is a protected process | `ps.child.is_protected` | +| ps.is_wow64 | Indicates if the process generating the event is a 32-bit child process is created in 64-bit Windows system | `ps.is_wow64` | +| ps.is_packaged | Indicates if the process process generating the event is packaged with the MSIX technology | `ps.is_packaged` | +| ps.is_protected | Indicates if the process generating the event is a protected process | `ps.is_protected` | +| ps.parent.is_wow64 | Indicates if the parent process generating the event is a 32-bit process created in 64-bit Windows system | `ps.parent.is_wow64` | +| ps.parent.is_packaged | Indicates if the parent process generating the event is packaged with the MSIX technology | `ps.parent.is_packaged` | +| ps.parent.is_protected | Indicates if the parent process generating the event is a protected process | `ps.parent.is_protected` | ### Thread @@ -100,11 +110,11 @@ The following tables summarize available field names that can be used in filter | thread.kstack.limit | Limit of the thread's kernel space stack | `thread.kstack.limit = 'a85d800000'` | | thread.ustack.base | Base address of the thread's user space stack | `thread.ustack.base = '7ffe0000'` | | thread.ustack.limit | Limit of the thread's user space stack | `thread.ustack.limit = '8ffe0000'` | -| thread.entrypoint | Starting address of the function to be executed by the thread | `thread.entrypoint = '7efe0000'` | +| thread.start_address | Start address of the function to be executed by the thread | `thread.start_address = '7efe0000'` | | thread.access.mask | Thread access rights | `thread.access.mask = '0x1800'` | | thread.access.mask.names | Thread access human-readable rights | `thread.access.mask.names in ('QUERY_LIMITED_INFORMATION')` | | thread.access.status | Thread access status | `thread.access.status = 'Success'` | - +| thread.teb_address | The base address of the thread environment block | `thread.teb_address = '8f30893000'` | ### Callstack | Field Name | Description | Example | @@ -140,6 +150,7 @@ The following tables summarize available field names that can be used in filter | image.is_dll | Indicates if the loaded image is a DLL | `image.is_dll` | | image.is_driver | Indicates if the loaded image is a driver | `image.is_driver` | | image.is_exec | Indicates if the loaded image is an executable | `image.is_exec` | +| image.is_dotnet | Indicates if the loaded image is a .NET assembly | `image.is_dotnet` | ### File | Field Name | Description | Example | @@ -162,7 +173,11 @@ The following tables summarize available field names that can be used in filter | file.is_driver_vulnerable | Indicates if the dropped driver is vulnerable | `file.is_driver_vulnerable` | | file.is_dll | Indicates if the created file is a DLL | `file.is_dll` | | file.is_driver | Indicates if the created file is a driver | `file.is_driver` | -| file.is_exec | Indicates if the crated file is an executable | `file.is_exec` | +| file.is_exec | Indicates if the created file is an executable | `file.is_exec` | +| file.info_class | Identifies the file information class | `file.info_class = 'Allocation'` | +| file.info.allocation_size | Represents the file allocation size set via `NtSetInformationFile` syscall | `file.info.allocation_size > 645400` | +| file.info.eof_size | Represents the file EOF size set via `NtSetInformationFile` syscall | `file.info.eof_size > 1000` | +| file.info.is_disposition_file_delete | Indicates if the file is deleted when its handle is closed | `file.info.is_disposition_file_delete = true` | ### Registry @@ -254,4 +269,3 @@ The following tables summarize available field names that can be used in filter | pe.cert.before | PE certificate enrollment date | `pe.cert.before contains '2024-02-01 00:05:42 +0000 UTC'` | | pe.is_modified | Indicates if on-disk and in-memory PE headers differ | `pe.is_modified'` | | pe.is_modified | Indicates if on-disk and in-memory PE headers differ | `pe.is_modified'` | -| pe.ps.child.file.name | Original file name of the child process executable supplied at compile-time | `pe.ps.child.file.name = 'NOTEPAD.EXE'` | diff --git a/docs/kevents/process.md b/docs/kevents/process.md index 6c0037351..ad6f2a72b 100755 --- a/docs/kevents/process.md +++ b/docs/kevents/process.md @@ -19,6 +19,7 @@ Process events are fired up as a stimulus to the process' life-cycle changes. Wh - `start_time` designates the instant when the process was started. - `domain` represents the domain name under which the process is started. - `username` represents the username that started the process. +- `flags` represents process creation flags. Can be `WOW64`, `PROTECTED`, or `PACKAGED` to designate 32-bit process is created in 64-bit Windows system, process is to be run as a protected process, or a process packaged with the **MSIX** technology respectively. #### OpenProcess diff --git a/docs/kevents/thread.md b/docs/kevents/thread.md index f741f0253..066a68b29 100755 --- a/docs/kevents/thread.md +++ b/docs/kevents/thread.md @@ -14,7 +14,8 @@ Thread events are comprised of the following parameters: - `ustack_limit` is the limit of the thread's user space stack. - `kstack_base` is the base address of the thread's kernel space stack. - `kstack_limit` is the limit of the thread's kernel space stack. -- `entrypoint` is the starting address of the function to be executed by the thread. +- `start_address` is the start address of the function to be executed by the thread. +- `teb` is the address of the Thread Environment Block (TEB). #### OpenThread diff --git a/docs/setup/quick-start.md b/docs/setup/quick-start.md index e20fb73ac..e09d13e19 100644 --- a/docs/setup/quick-start.md +++ b/docs/setup/quick-start.md @@ -1,6 +1,6 @@ # Quick start -By default, Fibratus operates in rule engine mode. It loads the rule set from the `%PROGRAM FILES%\Fibratus\Rules` directory and sends security alerts to the [systray](/alerts/senders/systray) notification area. Optionally, it takes response actions when the rule is fired, such as killing the process. To see Fibratus in action, we can trigger a rule by performing the following actions: +By default, Fibratus operates in rule engine mode. It loads the rule set from the `%PROGRAM FILES%\Fibratus\Rules` directory and sends security alerts to [Eventlog](/alerts/senders/eventlog) or other configurable [sinks](/alerts/senders). Optionally, it takes response actions when the rule is fired, such as killing the process. To see Fibratus in action, we can trigger a rule by performing the following actions: - spin up a command line prompt - list credentials from the vault by using the `VaultCmd` tool @@ -8,7 +8,7 @@ By default, Fibratus operates in rule engine mode. It loads the rule set from th $ VaultCmd.exe /listcreds:"Windows Credentials" /all ``` -- `Credential discovery via VaultCmd.exe` rule should trigger displaying the alert in the systray notification area +- `Credential discovery via VaultCmd.exe` rule should trigger displaying the alert in the Eventlog `Application` channel. To learn more about detection rules, head to [rules](/filters/rules). diff --git a/docs/yara/alerts.md b/docs/yara/alerts.md index 29a9a7622..8dd379e38 100644 --- a/docs/yara/alerts.md +++ b/docs/yara/alerts.md @@ -1,109 +1,6 @@ # Alerts -Alert notifications are automatically sent via the sender specified by the `alert-via` option. The alert will contain any tag that was defined in the YARA rule. The following is an example of a YARA alert. - -``` -Possible malicious process, notepad.exe (8424), detected at 12 Oct 2020 18:33:58 CEST. - -Rule matches - Rule: FakeNotepad - Namespace: default - Meta: map[author:Usurper] - Tags: [notepad] - -Process information - -Name: notepad.exe -PID: 8424 -PPID: 8424 -Comm: "C:\WINDOWS\system32\notepad.exe" -Cwd: C:\Users\nedo\ -SID: ARCHRABBIT\nedo -Session ID: 1 - -Env: - ALLUSERSPROFILE: C:\ProgramData - APPDATA: C:\Users\nedo\AppData\Roaming - COMPUTERNAME: ARCHRABBIT - ComSpec: C:\WINDOWS\system32\cmd.exe - CommonProgramFiles: C:\Program Files\Common Files - CommonProgramFiles(x86): C:\Program Files (x86)\Common Files - CommonProgramW6432: C:\Program Files\Common Files - DriverData: C:\Windows\System32\Drivers\DriverData - ERLANG_HOME: C:\Program Files\erl-23.0 - FPS_BROWSER_APP_PROFILE_STRING: Internet Explorer - FPS_BROWSER_USER_PROFILE_STRING: - SESSIONNAME: Console - SystemDrive: C: - -Threads: - ID: 888 IO prio: 2, Base prio: 8, Page prio: 5, Ustack base: f96af50000, Ustack limit: f96af3f000, Kstack base: ffff9982c4f1c000, Kstack limit: f96af3f000, Entrypoint: 7ff96cad3d60 - ID: 7084 IO prio: 2, Base prio: 8, Page prio: 5, Ustack base: f96aed0000, Ustack limit: f96aebf000, Kstack base: ffff9982c45cd000, Kstack limit: f96aebf000, Entrypoint: 7ff7a0240110 - ID: 7492 IO prio: 2, Base prio: 8, Page prio: 5, Ustack base: f96b280000, Ustack limit: f96b26f000, Kstack base: ffff9982c4fc1000, Kstack limit: f96b26f000, Entrypoint: 7ff96cad3d60 - ID: 13496 IO prio: 2, Base prio: 8, Page prio: 5, Ustack base: f96afd0000, Ustack limit: f96afbf000, Kstack base: ffff9982c4518000, Kstack limit: f96afbf000, Entrypoint: 7ff96acdb0c0 - -Modules: - Name: C:\Windows\System32\notepad.exe, Size: 204800, Checksum: 0, Base address: 7ff7a0220000, Default base address: 7ff7a0220000 - Name: C:\Windows\System32\ntdll.dll, Size: 2031616, Checksum: 0, Base address: 7ff96caa0000, Default base address: 7ff96caa0000 - Name: C:\Windows\System32\kernel32.dll, Size: 729088, Checksum: 0, Base address: 7ff96ab50000, Default base address: 7ff96ab50000 - Name: C:\Program Files\AVG\Antivirus\aswhook.dll, Size: 73728, Checksum: 0, Base address: 7ff94baa0000, Default base address: 7ff94baa0000 Name: C:\Windows\System32\KernelBase.dll, Size: 2764800, Checksum: 0, Base address: 7ff969d00000, Default base address: 7ff969d00000 - Name: C:\Windows\System32\gdi32.dll, Size: 155648, Checksum: 0, Base address: 7ff96c080000, Default base address: 7ff96c080000 - Name: C:\Windows\System32\win32u.dll, Size: 135168, Checksum: 0, Base address: 7ff96ab20000, Default base address: 7ff96ab20000 - Name: C:\Windows\System32\gdi32full.dll, Size: 1654784, Checksum: 0, Base address: 7ff96a880000, Default base address: 7ff96a880000 - Name: C:\Windows\System32\msvcp_win.dll, Size: 647168, Checksum: 0, Base address: 7ff96a060000, Default base address: 7ff96a060000 - Name: C:\Windows\System32\ucrtbase.dll, Size: 1024000, Checksum: 0, Base address: 7ff96aa20000, Default base address: 7ff96aa20000 - Name: C:\Windows\System32\user32.dll, Size: 1654784, Checksum: 0, Base address: 7ff96b8b0000, Default base address: 7ff96b8b0000 - Name: C:\Windows\System32\msvcrt.dll, Size: 647168, Checksum: 0, Base address: 7ff96c880000, Default base address: 7ff96c880000 - Name: C:\Windows\System32\combase.dll, Size: 3366912, Checksum: 0, Base address: 7ff96ac40000, Default base address: 7ff96ac40000 - Name: C:\Windows\System32\rpcrt4.dll, Size: 1179648, Checksum: 0, Base address: 7ff96bc60000, Default base address: 7ff96bc60000 - Name: C:\Windows\System32\bcryptprimitives.dll, Size: 524288, Checksum: 0, Base address: 7ff969a30000, Default base address: 7ff969a30000 Name: C:\Windows\System32\SHCore.dll, Size: 692224, Checksum: 0, Base address: 7ff96b6b0000, Default base address: 7ff96b6b0000 - Name: C:\Windows\System32\advapi32.dll, Size: 667648, Checksum: 0, Base address: 7ff96bbb0000, Default base address: 7ff96bbb0000 - Name: C:\Windows\System32\sechost.dll, Size: 618496, Checksum: 0, Base address: 7ff96b610000, Default base address: 7ff96b610000 - -Handles: - Num: 4 Type: Event, Name: , Object: 0x0, PID: 8424 Num: 12 Type: Event, Name: , Object: 0x0, PID: 8424 - Num: 16 Type: WaitCompletionPacket, Name: , Object: 0x0, PID: 8424 - Num: 20 Type: IoCompletion, Name: , Object: 0x0, PID: 8424 - Num: 24 Type: TpWorkerFactory, Name: , Object: 0x0, PID: 8424 - Num: 28 Type: IRTimer, Name: , Object: 0x0, PID: 8424 - Num: 32 Type: WaitCompletionPacket, Name: , Object: 0x0, PID: 8424 - Num: 36 Type: IRTimer, Name: , Object: 0x0, PID: 8424 - Num: 40 Type: WaitCompletionPacket, Name: , Object: 0x0, PID: 8424 - Num: 56 Type: Directory, Name: \KnownDlls, Object: 0x0, PID: 8424 - Num: 60 Type: Event, Name: , Object: 0x0, PID: 8424 Num: 64 Type: Event, Name: , Object: 0x0, PID: 8424 - Num: 80 Type: ALPC Port, Name: , Object: 0x0, PID: 8424 Num: 96 Type: Key, Name: HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Nls\Sorting\Versions, Object: 0x0, PID: 8424 - Num: 108 Type: Key, Name: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options, Object: 0x0, PID: 8424 - Num: 112 Type: Mutant, Name: , Object: 0x0, PID: 8424 - Num: 116 Type: Event, Name: , Object: 0x0, PID: 8424 - Num: 120 Type: IoCompletion, Name: , Object: 0x0, PID: 8424 - Num: 124 Type: WindowStation, Name: \Sessions\1\Windows\WindowStations\WinSta0, Object: 0x0, PID: 8424 - Num: 128 Type: Desktop, Name: \Default, Object: 0x0, PID: 8424 - Num: 132 Type: WindowStation, Name: \Sessions\1\Windows\WindowStations\WinSta0, Object: 0x0, PID: 8424 - Num: 144 Type: Key, Name: HKEY_LOCAL_MACHINE, Object: 0x0, PID: 8424 Num: 152 Type: Event, Name: , Object: 0x0, PID: 8424 Num: 160 Type: - -Entrypoint: 20110 -Image base: 140000000 -Build date: 2028-08-09 02:09:05 +0000 UTC -Number of symbols: 0 -Number of sections: 7 -Sections: - Name: .text, Size: 132608, Entropy: 0.000000, Md5: - Name: .rdata, Size: 35840, Entropy: 0.000000, Md5: - Name: .data, Size: 3072, Entropy: 0.000000, Md5: - Name: .pdata, Size: 4096, Entropy: 0.000000, Md5: - Name: .didat, Size: 512, Entropy: 0.000000, Md5: - Name: .rsrc, Size: 3072, Entropy: 0.000000, Md5: - Name: .reloc, Size: 1024, Entropy: 0.000000, Md5: -Resources: - CompanyName: Microsoft Corporation - FileDescription: Notepad - FileVersion: 10.0.18362.693 (WinBuild.160101.0800) - InternalName: Notepad - LegalCopyright: © Microsoft Corporation. All rights reserved. - OriginalFilename: NOTEPAD.EXE - ProductName: Microsoft® Windows® Operating System - ProductVersion: 10.0.18362.693 -``` +Alerts on rule matches are automatically sent via all active alert senders. ## Event metadata {docsify-ignore} @@ -140,4 +37,3 @@ The `yara.matches` tag contains the JSON array payload where each object represe } ] ``` - diff --git a/docs/yara/introduction.md b/docs/yara/introduction.md index afc3d8c42..e8c0fe145 100644 --- a/docs/yara/introduction.md +++ b/docs/yara/introduction.md @@ -2,6 +2,14 @@ [YARA](https://virustotal.github.io/yara/) is a prominent tool for binary pattern matching that aims to streamline and accelerate the classification of malware specimens. Fibratus interacts with the `libyara` through C bindings. The `libyara` dependency is statically linked, so no further software needs to be installed. -**Fibratus/YARA** tandem seeks to automate the classification of malicious processes and loadable modules by proactively scanning and alerting whenever a process is started. +**Fibratus/YARA** tandem aims to detect in-memory threats and malicious **PE** files by reacting on various signals including: + +- new process creation +- loading of an unsigned/untrusted executable/DLL or when the executable/DLL is loaded from the unbacked memory region +- creation of executable, DLL, or driver PE files +- creation of [ADS](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/e2b19412-a925-4360-b009-86e3b8a020c8) (Alternate Data Streams) +- RWX memory allocations +- mapping of a suspicious view of section +- writing a binary registry value The YARA scanner is not enabled by default, but you can do that by modifying the `yara.enabled` key in the configuration file. diff --git a/docs/yara/scanning.md b/docs/yara/scanning.md index be3d4eed8..dcbe3d556 100644 --- a/docs/yara/scanning.md +++ b/docs/yara/scanning.md @@ -2,8 +2,6 @@ For the YARA scanner to operate correctly, the rules have to be compiled and loaded into the engine. This is accomplished by providing file system paths with YARA rule definitions in the `rule.paths` configuration keys. The directories are scanned recursively for any `.yar` file. Alternatively, it is possible to provide the rules as inline strings directly in the Fibratus configuration file. -In addition to process scanning, Fibratus also performs file scanning for modules mapped into the process address space. You can control whether file scanning is enabled by changing the `skip-files` option. - ### Configuration {docsify-ignore} YARA scanner related options are located in the `yara` section of the configuration file. @@ -31,132 +29,10 @@ rule: namespace: notepad ``` -#### alert-via - -Indicates which sender is used to transport the alert generated by YARA scanner. - -**default**: `mail` - #### alert-template: -Specifies templates for the alert title and text in Go [templating](https://golang.org/pkg/text/template) language. You can specify a distinct template for both the `title` and the `text`. - -Default `title` template: - -``` -{{if .PS }}YARA alert on process {{ .PS.Name }}{{ else }}YARA alert on file {{ .Filename }}{{ end }} -``` - -Default `text` template: +Specifies templates for the alert text in Go [templating](https://golang.org/pkg/text/template) language. -``` -{{ if .PS }} - Possible malicious process, {{ .PS.Name }} ({{ .PS.PID }}), detected at {{ .Timestamp }}. - - Rule matches - {{- with .Matches }} - {{ range . }} - Rule: {{ .Rule }} - Namespace: {{ .Namespace }} - Meta: {{ .Meta }} - Tags: {{ .Tags }} - {{ end }} - {{- end }} - - Process information - - Name: {{ .PS.Name }} - PID: {{ .PS.PID }} - PPID: {{ .PS.Ppid }} - Comm: {{ .PS.Comm }} - Cwd: {{ .PS.Cwd }} - SID: {{ .PS.SID }} - Session ID: {{ .PS.SessionID }} - {{ if .PS.Envs }} - Env: - {{- with .PS.Envs }} - {{- range $k, $v := . }} - {{ $k }}: {{ $v }} - {{- end }} - {{- end }} - {{ end }} - Threads: - {{- with .PS.Threads }} - {{- range . }} - {{ . }} - {{- end }} - {{- end }} - Modules: - {{- with .PS.Modules }} - {{- range . }} - {{ . }} - {{- end }} - {{- end }} - {{ if .PS.Handles }} - Handles: - {{- with .PS.Handles }} - {{- range . }} - {{ . }} - {{- end }} - {{- end }} - {{ end }} - - {{ if .PS.PE }} - Entrypoint: {{ .PS.PE.EntryPoint }} - Image base: {{ .PS.PE.ImageBase }} - Build date: {{ .PS.PE.LinkTime }} - - Number of symbols: {{ .PS.PE.NumberOfSymbols }} - Number of sections: {{ .PS.PE.NumberOfSections }} - - Sections: - {{- with .PS.PE.Sections }} - {{- range . }} - {{ . }} - {{- end }} - {{- end }} - {{ if .PS.PE.Symbols }} - Symbols: - {{- with .PS.PE.Symbols }} - {{- range . }} - {{ . }} - {{- end }} - {{- end }} - {{ end }} - {{ if .PS.PE.Imports }} - Imports: - {{- with .PS.PE.Imports }} - {{- range . }} - {{ . }} - {{- end }} - {{- end }} - {{ end }} - {{ if .PS.PE.VersionResources }} - Resources: - {{- with .PS.PE.VersionResources }} - {{- range $k, $v := . }} - {{ $k }}: {{ $v }} - {{- end }} - {{- end }} - {{ end }} - {{ end }} - - {{ else }} - - Possible malicious file, {{ .Filename }}, detected at {{ .Timestamp }}. - - Rule matches - {{ with .Matches }} - {{ range . }} - Rule: {{ .Rule }} - Namespace: {{ .Namespace }} - Meta: {{ .Meta }} - Tags: {{ .Tags }} - {{ end }} - {{ end }} - - {{ end }} -``` #### fastscan @@ -172,14 +48,39 @@ Specifies the timeout for the scanner. If the timeout is reached, the scan opera #### skip-files -Indicates whether file scanning is enabled. This affects scans triggered by the image loading events. +Indicates whether file scanning is enabled. This affects the scan triggered by the image loading, create file, and file mapping operations. + +**default**: `false` + +#### skip-allocs + +Indicates whether scanning on suspicious memory allocations is disabled. + +**default**: `false` + +#### skip-mmaps + +Indicates whether scanning on suspicious mappings of sections is disabled. + +**default**: `false` + + +#### skip-registry + +Indicates whether registry value scanning is disabled. **default**: `false` + #### excluded-files -Contains the list of file names that shouldn't be scanned. +Contains the list of the comma-separated file paths that shouldn't be scanned. Wildcard matching is possible. For example: + +``` +excluded-files: + - ?:\\Windows\\System32\\kernel32.dll +``` #### excluded-procs -Contains the list of process image names that shouldn't be scanned. +Contains the list of the comma-separated process image paths that shouldn't be scanned. Wildcard matching is possible.