You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/filters/functions.md
+247-4Lines changed: 247 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
1
# Functions
2
2
3
-
Functions expand the scope of the filtering language by bringing a plethora of capabilities. The function can return a primitive value, including integers, strings, and booleans. Additionally, some functions may return a collection of values. Function names are case insensitive.
3
+
Functions expand the scope of the filtering language by bringing a plethora of capabilities. The function can return a primitive value, including integers, strings, and booleans. Function calls can be nested where the result of one function is used as an input in another function. For example, `lower(ltrim(file.name, 'C:'))`, removes the `C` drive letter from the file path and converts it to a lower case string.
4
+
5
+
Additionally, some functions may return a collection of values. Function names are case insensitive.
4
6
5
7
### Network functions
6
8
@@ -18,7 +20,7 @@ Functions expand the scope of the filtering language by bringing a plethora of c
18
20
19
21
- **Examples**
20
22
21
-
Assuming the `net.sip` contains the `192.168.1.20` IP address, the following filter
23
+
Assuming the `net.sip` field contains the `192.168.1.20` IP address, the following filter
22
24
would match on this event.
23
25
24
26
```
@@ -40,8 +42,249 @@ Functions expand the scope of the filtering language by bringing a plethora of c
40
42
41
43
- **Examples**
42
44
43
-
Assuming the `registry.key.name` contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup\Pid`, the following would filter events for the matching md5 hash.
45
+
Assuming the `registry.key.name` field contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup\Pid`, the following would filter events for the matching md5 hash.
44
46
45
47
```
46
48
fibratus run kevt.category = 'net' and md5(registry.key.name) = 'eab870b2a516206575d2ffa2b98d8af5'
- `args`: Strings or integers to be concatenated. This function requires at least 2 input arguments
62
+
- `return` a concatenated string of all input arguments
63
+
64
+
- **Examples**
65
+
66
+
Assuming the `ps.domain` field contains `NT_AUTHORITY` and `ps.username` field contains `admin`, the following would filter events for the matching concatenated string.
67
+
68
+
```
69
+
fibratus run concat(ps.domain, '-', ps.username) = 'NT_AUTHORITY-admin'
- `prefix`: Prefix that is removed from the original input string
82
+
- `return` a string with the specified prefix removed
83
+
84
+
- **Examples**
85
+
86
+
Assuming the `registry.key.name` field contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup\Pid`, the following filter expression would match on all events where the resulting string is equal to `SYSTEM\Setup\Pid`
87
+
88
+
```
89
+
fibratus run ltrim(registry.key.name, 'HKEY_LOCAL_MACHINE\\') = 'SYSTEM\\Setup\\Pid'
- `prefix`: Suffix that is removed from the original string
102
+
- `return` a string with the specified suffix removed
103
+
104
+
- **Examples**
105
+
106
+
Assuming the `registry.key.name` field contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup\Pid`, the following filter expression would match on all events where the resulting string is equal to `HKEY_LOCAL_MACHINE\SYSTEM\Setup`
107
+
108
+
```
109
+
fibratus run rtrim(registry.key.name, '\\Pid') = 'HKEY_LOCAL_MACHINE\\SYSTEM\\Setup'
110
+
```
111
+
112
+
#### lower
113
+
114
+
`lower` converts the string with all Unicode letters mapped to their lower case.
115
+
116
+
- **Specification**
117
+
```
118
+
lower(string: <string>) :: <string>
119
+
```
120
+
- `string`: Input string
121
+
- `return` a string converted to lower case
122
+
123
+
- **Examples**
124
+
125
+
Assuming the `registry.key.name` field contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup`, the following filter expression would match on all events where the resulting string is equal to `hkey_local_machine\system\setup`
126
+
127
+
```
128
+
fibratus run lower(registry.key.name) = 'hkey_local_machine\\system\\setup'
129
+
```
130
+
131
+
#### upper
132
+
133
+
`upper` converts the string with all Unicode letters mapped to their upper case.
134
+
135
+
- **Specification**
136
+
```
137
+
upper(string: <string>) :: <string>
138
+
```
139
+
- `string`: Input string
140
+
- `return` a string converted to upper case
141
+
142
+
- **Examples**
143
+
144
+
Assuming the `registry.key.name` field contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup`, the following filter expression would match on all events where the resulting string is equal to `HKEY_LOCAL_MACHINE\SYSTEM\SETUP`
145
+
146
+
```
147
+
fibratus run upper(registry.key.name) = 'HKEY_LOCAL_MACHINE\\SYSTEM\\SETUP'
148
+
```
149
+
150
+
#### replace
151
+
152
+
`replace` replaces all occurrences in the string as given by arbitrary old/new replacement pairs.
- `old`: substring in the original string that is replaced with the `new` string
160
+
- `new`: the replacement string
161
+
- `return` a string with all occurrences replaced by old/new pairs
162
+
163
+
- **Examples**
164
+
165
+
Assuming the `registry.key.name` field contains `HKEY_LOCAL_MACHINE\SYSTEM\Setup`, the following filter expression would match on all events where the resulting string is equal to `HKLM\SYS\Setup`
166
+
167
+
```
168
+
fibratus run replace(registry.key.name, 'HKEY_LOCAL_MACHINE', 'HKLM', 'SYSTEM', 'SYS') = 'HKLM\\SYS\\Setup'
169
+
```
170
+
171
+
#### split
172
+
173
+
`split` produces a slice of substrings separated by the given delimiter.
- `prefix`: The separator that is used to split the string
181
+
- `return` a slice of substrings
182
+
183
+
- **Examples**
184
+
185
+
Assuming the `file.name` field contains `C:\Windows\System32\kernel32.dll`, the following filter expression would match on all events where the `kernel32.dll` or `System32` strings are present in the resulting slice.
186
+
187
+
```
188
+
fibratus run split(file.name, '\\') in ('kernel32.dll', 'System32')
189
+
```
190
+
191
+
#### length
192
+
193
+
`length` returns the number of characters for string arguments and the size of the slice for slice arguments.
194
+
195
+
- **Specification**
196
+
```
197
+
length(string: <string|slice>) :: <int>
198
+
```
199
+
- `string`: Input string or slice
200
+
- `return` the number of characters or array length
201
+
202
+
- **Examples**
203
+
204
+
Assuming the `ps.domain` field contains `"こんにちは"`, the following would filter events with 5 symbols in the process domain.
205
+
206
+
```
207
+
fibratus run length(ps.domain) = 5
208
+
```
209
+
210
+
#### indexof
211
+
212
+
`indexof` returns the index of the instance of substring in a given string depending on the provided search order.
- `return` a substring contained within start and end indices
243
+
244
+
- **Examples**
245
+
246
+
Assuming the `file.name` field contains `\Device\HarddiskVolume2\Windows\system32\user32.dll`, the following filter expression would match on all events where the substring is equal to `\Device`
247
+
248
+
```
249
+
fibratus run substr(file.name, indexof(file.name, '\\'), indexof(file.name, '\\Hard')) = '\\Device'
- `algo`: The algorithm used to calculate the string entropy. `shannon` is the default entropy type. This argument is optional
262
+
- `return` the string entropy
263
+
264
+
- **Examples**
265
+
266
+
Assuming the `file.name` field contains `\Device\HarddiskVolume2\Windows\system32\user32.dll`, the following filter expression would match on all events where file name entropy is greater than 255.
267
+
268
+
```
269
+
fibratus run entropy(file.name) > 255
270
+
```
271
+
272
+
#### regex
273
+
274
+
`regex` applies single/multiple regular expressions on the provided string argument.
Copy file name to clipboardExpand all lines: docs/kevents/process.md
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Process events
2
2
3
+
#### CreateProcess and TerminateProcess
4
+
3
5
Process events are fired up as a stimulus to the process' life-cycle changes. When the kernel puts into motion a process or terminates it, the `CreateProcess` and `TerminateProcess` events are emitted respectively. The following list summarizes all the distinct event parameters that are associated with process events.
4
6
5
7
-`pid` is the process' identifier. This value is valid from the time a process is created until it is terminated.
@@ -15,6 +17,17 @@ Process events are fired up as a stimulus to the process' life-cycle changes. Wh
15
17
-`status` is the exit status of the stopped process.
16
18
-`start_time` designates the instant when the process was started.
17
19
20
+
#### OpenProcess
21
+
22
+
`OpenProcess` event is triggered when a process tries to acquire an existing local process object. This event contains the following parameters:
23
+
24
+
-`desired_access` is the hexadecimal value that represents the desired access to the process object.
25
+
-`desired_access_names` is the list of human-readable desired access strings (e.g. `TERMINATE,QUERY_INFORMATION`). For a full list and detailed explanation of available access rights, head to the official [docs](https://docs.microsoft.com/en-us/windows/win32/procthread/process-security-and-access-rights).
26
+
-`name` is the name of the local process that was opened.
27
+
-`exe` is the full path of the local process object that was open.
28
+
-`pid` is the identifier of the local process that was opened.
29
+
-`status` contains the result of the process object open operation. (e.g. `success`)
30
+
18
31
### Process state {docsify-ignore}
19
32
20
33
Fibratus keeps a snapshot of all running processes including their state such as basic process attributes, allocated file handles, dynamically-linked libraries, PE (Portable Executable) metadata and other resources. The snapshot is updated dynamically as processes get spawn or die. Each time a kernel event is triggered, its process' state is fetched from the snapshot and attached to the event. This state machine semantically enriches each individual event with the aim on providing a powerful context for [filtering](/filters/introduction.md) and [scripting](/filaments/introduction.md).
Copy file name to clipboardExpand all lines: docs/kevents/thread.md
+15Lines changed: 15 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Thread events
2
2
3
+
#### CreateThread and TerminateThread
4
+
3
5
Thread events notify the creation (`CreateThread`) or termination (`TerminateThread`) of threads within the process' address space. In situations where a process spawns a remote thread that runs in other process' address space, the `CreateThread` event is also triggered.
4
6
Thread events are comprised of the following parameters:
5
7
@@ -13,3 +15,16 @@ Thread events are comprised of the following parameters:
13
15
-`kstack_base` is the base address of the thread's kernel space stack.
14
16
-`kstack_limit` is the limit of the thread's kernel space stack.
15
17
-`entrypoint` is the starting address of the function to be executed by the thread.
18
+
19
+
#### OpenThread
20
+
21
+
`OpenProcess` event is triggered when a process opens an existing local thread object. This event contains the following parameters:
22
+
23
+
-`desired_access` is the hexadecimal value that represents the desired access to the thread object.
24
+
-`desired_access_names` is the list of human-readable desired access strings (e.g. `QUERY_LIMITED_INFORMATION`). For a full list and detailed explanation of available access rights, head to the official [docs](https://docs.microsoft.com/en-us/windows/win32/procthread/thread-security-and-access-rights).
25
+
-`name` is the name of the local process whose thread object was open.
26
+
-`exe` is the full path of the local process image whose thread object was open.
27
+
-`pid` is the identifier of the local process whose thread object was opened.
28
+
-`tid` is the identifier of the local thread that was opened.
29
+
-`status` contains the result of the thread object open operation. (e.g. `success`)
0 commit comments