Tracking Process Creation with CBFS Filter

Summary

CBProcess is a component of CBFS Filter, an SDK and library designed for monitoring and controlling various system activities, including the lifecycle of processes and threads, filesystem operations, and registry operations. This component—available as a class, struct, or trait depending on the programming language—enables developers to monitor operations related to processes and threads within their Windows applications. This article reviews the practical steps required to track process creation with the CBProcess component.

Pre-requisites

The functionality of CBProcess relies on a kernel-mode driver that comes with the CBFS Filter product. This driver is installed once, typically during the application installation process, as installing a driver requires permissions that are only available to processes running with elevated administrator privileges, which are usually granted to installer processes.

You can install the driver by calling the Install method of the CBProcess component or by using a helper Installer DLL included with the product. The drivers are packaged in a CAB file, which contains drivers for all processor architectures.

Configuring the Component

CBProcess provides information about each operation through events or callback functions, depending on the programming language used. Here’s a sample code snippet to handle an event in .NET:

CBProcess process = new CBProcess(); … process.OnProcessCreation += HandleProcessCreation; // an application-provided event handler

If the application needs to capture the command line of each started process, it should set the TrackCommandLine property to true.

To reduce system load, the driver requires the application to add a rule that explicitly specifies which process or processes to monitor. When the application intends to monitor process creation, it should specify the name or process identifier (PID) of the creator process to monitor:

process.AddFilteredProcessById(4, false); // this adds the SYSTEM process to the list process.AddFilteredProcessByName(“explorer.exe”, false); // this adds the File Explorer to the list

When adding specific processes to the list, you can also choose to monitor all child processes spawned by them. This can be useful when the exact child processes are unknown. For instance, when you run MSBuild.exe, it may spawn various compilers, linkers, and other processes. To do this, set the second parameter to true:

process.AddFilteredProcessById(4, true); // monitor all child processes of the SYSTEM process

However, in most cases, the application will need to monitor all processes to avoid missing any important events. You can add a rule to monitor all processes as follows:

process.AddFilteredProcessById(-1, true); // monitor all processes

Starting Monitoring

Before starting monitoring, it’s a good idea to check the driver’s status—specifically, whether it is installed and loaded. This helps diagnose any errors that may occur when you begin monitoring.

You can check the driver’s status using the GetDriverStatus method. If the status is not MODULE_STATUS_RUNNING, there's no point in starting monitoring. Instead, the user should be informed that the driver is either not installed or is installed but not running.

To start monitoring, the application should call the StartFilter method and specify the timeout and the events to fire:

process.StartFilter(5000, Constants.PROC_EVT_PROCESS_CREATION);

The timeout specifies how long to wait for event handlers before they are considered expired and processing resumes. This timeout helps prevent system-wide blocking if an event handler takes too long to complete. The driver tracks this timeout, and for debugging purposes, it can be set to 0; however, in a production environment, it's recommended to use a reasonable value. The minimum timeout is 3000 milliseconds (three seconds), and larger values are acceptable. Just keep in mind that if the event handler gets stuck, long timeouts can block certain system operations for that duration.

The second parameter is a combination of flags that instruct the driver which events to fire. The driver will skip notifying user mode about any events not requested with these flags, thereby speeding up operations.

Hanlding Process Creation

An event handler (or callback function, depending on the programming language) is called when a new process is being created, right in the middle of the procedure.

The event handler can inspect the available information and take any necessary actions, such as logging details about the new process or examining its executable.

The event parameters include basic information: the PID (process ID) of the new process, the PID of the creator and of the parent process (the creator and parent may be different), the name of the new process, and the path to the process’s executable.

The path to the executable is provided by the operating system and may sometimes be incomplete. Additionally, it might come with a “\??\” prefix or even in NT-native format (e.g., \Device\HarddiskVolumeN...). Therefore, if the application intends to open an image file, further testing under different conditions is necessary.

To check the security information of the creator process, the event handler can call the GetOriginatorToken method of CBProcess. This method retrieves a security token that can be used to gather more information about the user to whom the process belongs. It’s crucial to remember to close the security token properly after use by calling the CloseHandle function from the Windows API.

If the application decides to prevent the creation of the process, it should set the ResultCode parameter of the event to a non-zero value. A common error code to use is ERROR_ACCESS_DENIED (numeric value 5).

Application Shutdown

To properly shut down the application that started filtering with CBProcess, simply call the StopFilter method. There's no need to explicitly remove the added filter rules.

Getting Started with CBProcess

You can find an evaluation version of the SDK for your platform and programming language in the Download Center. After downloading and installing the SDK, you will receive a library, sample code, and comprehensive documentation on your system. The documentation includes a "Getting Started" section with programming instructions. Additionally, free technical support is available during the evaluation phase.