Filtering

Modern systems generate an overwhelming volume of events, making it difficult to extract meaningful insights or focus on specific behaviors. Fibratus provides a powerful and expressive filtering engine that allows to narrow down event streams, isolate suspicious activity and drive investigations or postmortem analysis. Filters are the foundation of detection rules logic.

Anatomy of a filter

At its core, a filter expression consists of LHS (Left Hand Side) and RHS (Right Hand Side) components connected by a binary, logical, or string operator as depicited in the image below.

!> A special case are boolean fields that can appear alone in the filter expression. For example, module.is_dll is the boolean shortcut of module.is_dll = true

Suppose we want to filter all events generated by cmd.exe, powershell.exe or winword.exe processes. We would write the following filter expression.

ps.name in ('cmd.exe', 'powershell.exe', 'winword.exe')

LHS

The LHS component is typically a field however it can also be a function result. Examples of field names are ps.name or evt.pid. Fields contain values extracted from event parameters, callstack frames, or process context.

RHS

The RHS component can be of several types including strings, numbers, IP addresses, boolean values, field references and collections. Here are some examples:

String values must be enclosed in single quotes ''. If a string contains characters that would make it an invalid identifier, those characters need to be escaped. For instance, path delimiters (backslashes) and quotation marks require escaping:

file.path = 'C:\\Windows\\System32'

Filter expressions also support standard escape sequences, such as the newline character.

Operators

Operators define how LHS and RHS are evaluated. They fall into several categories:

Operator precedence determines how expressions are evaluated. For example, A or B and C is interpreted as A or (B and C). When necessary, use parentheses to make intent explicit and avoid subtle bugs.

Functions

Functions can be used on either side of the expression, or even nested. This enables on-the-fly transformation of event fields and constants, making filters more robust and adaptable to variations in data. For instance, lower(file.name) = 'cmd.exe' ensures the comparison is case-insensitive, while base(ltrim(file.path, 'C:'), false) in suspicious_files demonstrates function composition, where the file path is first trimmed and then reduced to its base name before being matched against a list of suspicious files.

Errors

If a filter contains a syntax error, a hint indicates the position of the error in the expression. By highlighting the exact offset where parsing fails, the hint enables precise debugging of filters, helping users quickly identify issues such as token mismatches, missing delimiters, invalid string escapes, or invalid operator usage without manually inspecting the entire expression.

Filtering in different contexts

As described in the quick start, filters can be applied at different stages of event collection and processing. Filter expressions are passed as command-line arguments to the run, capture, and replay commands.

!> If you're using PowerShell, wrap the entire filter expression in quotes fibratus run --forward "evt.category = 'net'"

Filtering with run

The run command evaluates the filter expression against each incoming event. Events that don’t match are discarded and never forwarded to the output sink.

For example, the following command captures only events that originate from the cmd.exe or svchost.exe processes.

Filtering with capture

The capture command persists only those events that match the filter. Captures are thoroughly explained in the upcoming section. In this example, only registry events are written to the output file.

Filtering with replay

When replaying events from a capture file, filters can narrow down the replay scope. For instance, the following command replays only events that modify registry values:

Filtering in filaments

Filters can also be applied during filament execution. If a filter is defined both in the run command and via the set_filter function, the filament-level filter takes precedence.

Exclusions

In some cases, you may want to exclude specific events, either by process image name or event type after they are captured from kernel buffers. Additionally, the kernel stream consumer can be configured to ignore entire categories of events at the Event Tracing for Windows session level.

Disabling event categories at this stage can significantly reduce system overhead, especially when dealing with high-volume telemetry that isn’t relevant to your use case.

Event source configuration

These options are defined in the eventsource section of the configuration file and control which events are collected:

• enable-thread collect thread-related events
• enable-registry collect registry events
• enable-net collect network events
• enable-fileio collect file system events
• enable-module collect module load/unload events
• enable-handle collect handle events
• enable-audit-api collect kernel audit API calls
• enable-mem collect memory events
• enable-dns collect DNS telemetry
• enable-threadpool collect thread pool telemetry

Disabling unnecessary categories helps reduce both event volume and processing cost.

Excluding events and processes

To permanently exclude specific events or processes from the event stream, use the eventsource.blacklist section:

• events defines a list of event names to drop, for example, CloseFile
• images defines a list of case-sensitive process image names (including extensions). Any event generated by these processes is discarded

This approach is useful for filtering out noisy or irrelevant sources before they reach downstream processing.