Introduction

Welcome to CBFS Filter, an all-in-one solution for filesystem, registry, and process manager request filtering. Advanced filter rules ensure that your application is notified only of the operations that you care about, and intelligent access rules enable you to enforce access restrictions with no additional effort. CBFS Filter's robust and performant event-driven API will help you monitor, intercept, handle, block, or otherwise react to various system requests, all without writing a single line of driver code.

Included Classes

CBFilter	The CBFilter component allows applications to intercept and control filesystem requests.
CBMonitor	The CBMonitor component allows applications to monitor filesystem requests.
CBProcess	The CBProcess component enables applications to intercept process manager requests.
CBRegistry	The CBRegistry component allows applications to intercept and control registry requests.

Additional Information

You will always find the latest information about CBFS Filter at our web site: www.callback.com. We offer free, fully-functional 30-day trials for all of our products, and our technical support staff are happy to answer any questions you may have during your evaluation.

Please direct all technical questions to support@callback.com. To help support technicians assist you as quickly as possible, please provide an detailed and accurate description of your problem, the results you expected, and the results that you received while using our product. For questions about licensing and pricing, and all other general inquiries, please contact sales@callback.com.

Thank You!

Thank you for choosing CBFS Filter for your development needs. We realize that you have a choice among development tools, and that by choosing us you are counting on us to be a key component in your business. We work around the clock to provide you with ongoing enhancements, support, and innovative products; and we will always do our best to exceed your expectations!

Deployment

The topics in this section provide information regarding the deployment of applications built with CBFS Filter. The information in these topics should be reviewed carefully when designing a deployment strategy, because CBFS Filter's kernel mode drivers and other supplementary DLLs must be distributed along with the application for it to function correctly.

Topics

• Driver Installation
• User Mode Library

Driver Installation

At a high level, CBFS Filter consists of class-specific kernel mode drivers and user mode library libraries which work together in tandem to provide each class's functionality. Therefore, it is necessary to install a class's kernel mode driver when deploying an application built with its user mode library.

The functionality needed to install the class drivers is included in each one's user mode library, as well as in the standalone installer DLLs provided for each one. The drivers directory, located within the product's Python package (see notes below), contains the following files for each class*:

*Note: The CBMonitor class uses the same driver as the CBFilter class. Note: When the user-mode library is installed or updated on end-user systems, it is required to ensure that the kernel-mode drivers already present in the system are updated to match the version of the installed user-mode library.

Python Package Notes

In the Python edition, the drivers directory described above is included as part of the product's Python package, <install_dir>\cbfsfilter-22.0.xxxx.tar.gz. After installing the package with pip (see the User Mode Library topic), the drivers directory can be found within the product's package directory, which can be located by running pip show cbfsfilter.

Installation and Uninstallation via User Mode Library Methods

The class includes the following methods to install and uninstall the required files; please refer to their documentation for more information:

• install
• uninstall
• get_driver_status
• get_driver_version

All of the links in this topic point to the CBFilter's copy of these methods, but they are available in all components.

Important: uninstall must only be used when completely removing the driver. When updating the driver, this method must not be used as it may cause the OS to incorrectly remove the driver on reboot. Please refer to the "Updating the Driver" section, below, for more information.

Installation and Uninstallation via Installer DLL Functions

The installer DLL is a lightweight, stand-alone library that contains only the functionality required for installing and uninstalling the required files. It is available in both 32-bit and 64-bit versions (each of which is capable of installing both 32-bit and 64-bit drivers and helper DLLs); and may be used as desired in installation scripts, setup applications, or any other executable capable of loading dynamically-linked libraries (DLLs).

The functions exposed by the installer DLL mirror the class methods listed above. Each function is available in two forms: those with an *A suffix, which can be used with ANSI/UTF8 strings; and those with a *W suffix, which can be used with Unicode (UTF16) strings.

Updating the Driver

To update the driver, call the install method. The new version of the driver will replace the older version. Please do not call the uninstall method when updating the driver.

Uninstalling the Driver

To uninstall the driver completely, call the uninstall method. If the driver cannot be immediately uninstalled, it will be marked for removal and uninstalled on the next reboot.

Use caution when calling uninstall ; if it gets called and the driver cannot be uninstalled immediately, and then install is subsequently called to install a new version, then upon reboot, the OS will end up uninstalling the newly-installed driver.

Important: The driver should only be uninstalled when the intent is to completely remove it from the system. Do not uninstall the driver to update it.

Reboot Requirements

Depending on the current state of the system, as well as the options chosen when installing or uninstalling the driver, the OS may need to reboot to complete the operation.

Always check the return value of the install and uninstall methods/functions; it will indicate whether a reboot is required .

Additional Notes

The OS treats major versions of the driver as separate products; they can operate in parallel and do not share any resources. Old major versions may optionally be removed from the system when calling install by passing the appropriate value for its Flags parameter.

For each major version of the product, only one copy of the driver can be installed at any time. When the driver is being installed, its version is checked, and one of the following three things occurs:

• If no driver with the same major version is currently installed, then the install procedure installs the driver as a new product.
• If a driver with the same major version and an older minor version is currently installed, then the install procedure updates the existing driver with the new one.
• If a driver with the same major version and a newer minor version is currently installed, then the install procedure leaves the existing driver unchanged.

When deploying files to a target system, the CAB file must remain present on the system. This file is required for uninstallation of the driver at a later time.

The product's installation code maintains a ProductGUID-based record of driver installations in the Windows Registry, creating a separate registry entry for each different ProductGUID. When the driver is "uninstalled", the corresponding registry entry is removed. The driver is only removed from the system if there are no entries left in the registry that reference the driver.

Windows 7 and Windows 2008 Server R2

Kernel-mode drivers are signed using the SHA2 algorithm. The original releases of Windows 7 and Windows 2008 Server R2 didn't support SHA2. To be able to load the newest versions of the drivers, the system needs to have certain updates installed. The updates are KB976932 (Service Pack 1 of the mentioned systems) and KB4474419 (Security Update).

Required Permissions

By default, Windows only allows installation and uninstallation of the CBFS Filter system files (kernel mode drivers and helper DLLs) to be performed from a user account which is a member of the Administrators group.

On systems where UAC is enabled, the process responsible for installing or uninstalling the system files must run with elevated permissions. Detection of current privileges and elevation of permissions is not within the scope of the class itself.

Some examples of obtaining the required permissions for driver installation and uninstallation are below.

• Starting the application which uses the class with the "Run as administrator" option.
• Modifying the Load and unload device drivers setting in the Local Security Policy under the User Rights Assignment section.
• Including a manifest alongside the application indicating the requirement for elevated permissions. For instance, if a file MyApp.exe.manifest with the content below exists next to the application MyApp.exe, it will prompt for elevated permissions when started (if required).

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> <assemblyIdentity version="1.0.0.0" processorArchitecture="X86" name="ExeName" type="win32"/> <description>elevate execution level</description> <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2"> <security> <requestedPrivileges> <requestedExecutionLevel level="requireAdministrator" uiAccess="false"/> </requestedPrivileges> </security> </trustInfo> </assembly>

User Mode Library

Note: : The user-mode library must be deployed to end-user systems along with the kernel-mode drivers; the version of the kernel-mode drivers on the end-user systems must be equal to or newer than the version of the user-mode library. Thus, when the user-mode library is installed or updated on end-user systems, it is required to ensure that the kernel-mode drivers already present in the system are updated to match the version of the installed user-mode library.

The user-mode library comes in two pieces, both of which must be deployed with the application:

• A Python module named cbfsfilter.py.
• A native dynamic library (unmanaged), named pycbfsfilter22.dll, available for both 32-bit (x86) and 64-bit (x64) processor architectures.

Both the module and native library are included in the product's Python package, <install_dir>\cbfsfilter-22.0.xxxx.tar.gz, which should be installed using pip: cd C:\path\to\install_dir python -m pip install cbfsfilter-22.0.xxxx.tar.gz

Once the product's Python package has been installed, the module can be imported and used: from cbfsfilter import *. Nothing else is required to deploy the application.

As an alternative to installing the module using pip, you can utilize the built-in setuptools module to package the module for deployment or install it to the machine. python setup.py build --build-lib=<app_dir> The above setup command packages the module and native library for deployment. A folder is created in the app_dir directory with the module and the native library packaged inside.

Remember to deploy the drivers too, as they are an integral part of CBFS Filter.

General Information

The topics in this section provide general information about various aspects of the product's functionality.

Topics

• Thread Safety of the API
• CBFilter/CBMonitor Topics section
• CBRegistry Topics section
• Driver Altitudes
• Event Handling section
• File and Registry Filter Rules section
• Network Filter Rules
• Loading Drivers in Safe Mode
• Error Reporting and Handling
• Troubleshooting

Thread Safety of the API

The properties and methods provided by CBFS Filter's APIs fall into one of the following categories when it comes to thread safety:

• Properties and methods that are intended to be accessed from event handlers (i.e., those documented as such) are thread-safe, since event handlers always execute in the context of worker threads.
• Methods related to installation, uninstallation, and status retrieval are not thread-safe, since they are expected to be used during the application installation process. (Methods in this category are those which are documented as being "available in both the class API and the Installer DLL".)
• Any helper methods documented in the class's API (i.e., those used to convert error codes, or provide similar supplementary functionality) don't use any explicit thread synchronization, but also don't access any other class properties or methods, and thus are inherently thread-safe.
• All other properties and methods are not thread-safe, so applications must employ proper thread synchronization techniques when using them on multiple threads (including, but not limited to, during event handlers).

CBFilter/CBMonitor Topics

The topics in this section provide additional information specific to the CBFilter and CBMonitor classs.

Topics

• File Masks
• Contexts
• Avoiding Deadlocks
• Security Checks
• File Create/Open Events
• Cached and Non-Cached Requests
• Monitoring Network Resources

File Masks

File masks are "templates" against which file and directory names are matched. A file mask may optionally begin with a path, either with or without a volume name (see the next section); and both the filename part and the path part may contain single-character wildcards (?) or multicharacter wildcards (*). Following are a few examples of file masks:

• 20??_Budget.xls
• *.doc
• *\Pictures\20??\*.jpg
• \temp\*.tmp
• C:\Reports\*

In general, file masks like C:\Reports\* will not match the C:\Reports\ directory itself, so any filter rule using this mask will therefore not match operations that target C:\Reports\ directly (such as an operation that enumerates its files and subdirectories). This behavior applies for all rules except reparse rules; a reparse rule with a source mask like C:\Reports\* will match any operation that targets the C:\Reports\ directory or any of its descendants.

Volume Names in Paths

If a file mask begins with a path, that path may optionally include a volume name. This allows applications to monitor only the volumes they are interested in. The following kinds of volume names are acceptable:

• A volume GUID, formatted like Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\ (note the trailing backslash). A mask may start with the \\?\ prefix, such as "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}".
• A hidden volume mounting point, formatted like \\.\mounting_point_name\.
• A DOS name, formatted like C:\.
• A network resource, formatted like \\server_name\share_name\ (please refer to the Monitoring Network Resources topic for more information).
• A volume NT-native name, formatted like \Device\HarddiskVolumeX\, where X is the number of the volume.

Note: To successfully add a rule with a file mask that includes a volume name, the specified volume must already be present on the system. Applications that wish to add rules for volumes that are not currently present can do one of the following things:

1. Add rules without volume names and selectively skip volumes as desired by setting the on_before_filter_attach_to_volume event's SkipVolume parameter to True.
2. Add and remove volume-specific rules "on-demand" using the on_after_filter_attach_to_volume and on_after_filter_detach_from_volume events.

(The aforementioned events are available in both CBFilter and CBMonitor.)

Mask Modifiers

Inverted Masks

An inverted mask starts with two pipe characters ("||"), such as ||file_mask. It inverts (negates) the result of matching the name to the mask. This syntax is an alternative to using passthrough rules. It can be used to slightly speed up operations: an inverted mask requires one rule, whereas the use of a passthrough rules introduces a secondary bypass rule to match.

Matching of Alternate Data Streams' Names

An alternate data stream (ADS) is a secondary file stream with its own name that follows the name of the file. An ADS full name looks like \path\to\filename.ext:streamname:$streamtype where the "streamname" part can be empty. Thus, to track events that happen specifically on ADS, you need to write the mask in the way that the ADS name matches it. A simple mask to track operations on all file's ADS is filename.ext:*. More complex use of wildcards in such a mask is possible as well.

Exclusion of Alternate Data Streams

Most "simple" masks match both the main name of the file and all of file's alternate data streams (named streams). To track operations that occur with a file but not its ADS, append ":|" to the filename in the mask (e.g., filename.ext:|).

Note: Such a mask covers operations on the specific ADS names that denote the main file or directory's content, that is, "::$DATA" (main data stream of a file), "::$INDEX_ALLOCATION", and ":$I30:$INDEX_ALLOCATION" (both identify a directory's content stream). If you want to exclude operations on these streams, use passthrough rules.

Per-Process Masks

Masks used by standard filter rules and access rules can be restricted so that they only match operations made by a specific process (or, made by all processes except a specific process). To do this, construct a mask in one of the following forms:

• process_name.exe|file_mask: Only matches operations requested by process_name.exe.
• ~process_name.exe|file_mask: Only matches operations not requested by process_name.exe.
• process_id|file_mask: Only matches operations requested by the process whose Id is process_id.
• ~process_id|file_mask: Only matches operations not requested by the process whose Id is process_id.

In all cases, file_mask can be any valid file mask as described above. The process_name.exe portion must be a valid process executable filename, and may optionally begin with a path. Wildcards are supported in any part of the process_name.exe portion. The process_id portion must be a numeric process Id (PID). When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

Contexts

It is often necessary for an application to associate certain information with a given file/directory, file handle, or enumeration operation. To assist developers in doing so in a convenient and performant manner, the CBFilter class provides context parameters in a number of events.

A context carries an application-defined value that identifies or points to some application-defined data, and each file/directory, file handle, and enumeration operation has a separate context associated with it. The CBFilter class treats context values as opaque; it stores the context values passed to it by the application and ensures that the correct values are exposed again whenever some event fires for a particular file, handle, or enumeration; but otherwise, it does not attempt to use said values in any way.

Note: Contexts are not available in the CBMonitor class.

Context Lifetimes

Contexts in CBFilter can be grouped into a few categories, each of which is subject to a different lifetime:

• File contexts and directory contexts, which are associated with an open file or directory.
• Handle contexts, which are associated with a specific open file or directory handle.
• Enumeration contexts, which are associated with an ongoing enumeration.

File/directory contexts are created the first time a file or directory is opened, and they live until the last handle to that file or directory is closed. Handle contexts, in contrast, are created every time a file or directory is opened, and they live only until the associated file handle is closed. For example, consider the following sequence of operations:

File/directory contexts are available in all Control Events corresponding to operations performed on some open file or directory, and handle contexts have similar availability. Enumeration contexts are created anytime a new enumeration operation begins and live until the enumeration operation ends.

All contexts, when created, are created before their corresponding "first event" fires (e.g., on_after_open_file, on_after_enumerate_directory). When deleted, all contexts are deleted after their corresponding "last event" fires (e.g., on_after_close_file, on_after_close_enumeration). If, however, a context's "first event" fails, whether as expected (e.g., due to Security Checks) or otherwise (see Error Reporting and Handling), then that context's value is immediately discarded because its corresponding "last event" will not ever fire. (Contexts are not available in the on_before_open_file or on_before_create_file events because it is unknown whether such requests will succeed.)

Note: The classes offer a special event, on_cleanup_context, which is the ultimate last event for the open file lifecycle. This event lets you dispose of the data, associated with file and handle contexts. It is recommended that contexts are deleted not in a on_after_close_file event, but in on_cleanup_context. This will guarantee that there is no race condition between file closing and reopening, in which case such race condition could lead to an invalid context value coming into play.

Context Use Cases

Contexts are most helpful when used to store information associated with a file/directory or file handle. Typically, contexts are initialized during their corresponding "first event", and then are used in subsequent events to speed up those operations.

Event contexts are used to pass information between event handlers of Before* events and the related handlers of the corresponding After* event fired during handling of the same OS request.

Applications are free to obtain and store whatever information they wish using contexts, as long as their event handlers comply with the restrictions described by the Avoiding Deadlocks and Recursive Calls topics.

Note: Although contexts usually come into play when the file is opened, the complex architecture of Windows filesystem filter stack makes it possible that some event, related to the opened file, fires ahead of the "first event" (i.e., before AfterCreateFile/AfterOpenFile/AfterEnumerateDirectory).

Using Contexts

Python does not have a completely safe way to store object references in contexts either directly or indirectly, which is why all context parameters are integers. To emulate such capabilities, the following approach is recommended:

1. Create a global dictionary instance for the application (i.e., a singleton), with keys that are integers and values of whatever type is desired.
2. When the application needs to create a context object in an event handler, a "key" can be created using the hash of the full file/directory name (including path), potentially mixed with additional information.
   • For file contexts, a hash of the full file/directory name is sufficiently unique because the context is exposed in all events pertaining to that file/directory.
   • For handle and enumeration contexts, additional information must be mixed in because multiple handle or enumeration contexts may be present at once for any given file/directory.
3. Using the created key, add the object to the dictionary.
4. Set the context parameter to the key used in the previous step.
5. To access the object in a later event, use the key stored by the context to retrieve the object from the dictionary.

Notes:

• Applications must take care to enforce proper thread synchronization when accessing the dictionary because events are always fired using worker threads. Please refer to the Threading and Concurrency topic for more information.
• In 32-bit applications, contexts are stored in 32-bit variables internally, and thus, the higher 32 bits of 64-bit values are lost.

Avoiding Deadlocks

As the Cached and Non-Cached Requests topic describes, it is common for the filesystem requests intercepted by a CBFilter/CBMonitor-based application to have been sent by the system's cache manager rather than by an actual process. Consequently, it is critical to keep the following restrictions in mind when implementing the application's event handlers:

• Event handlers must not perform any operations, explicitly or implicitly, against files opened in buffered mode. Any file accessed from an event handler must be opened using the Windows API's FILE_FLAG_NO_BUFFERING flag.
• Event handlers must not perform any asynchronous procedure calls (APCs).
• User interface operations must be strongly restricted.
• Plus, all CBFilter/CBMonitor-specific restrictions discussed in the Recursive Calls topic.

Events handlers that violate any of the restrictions described here will cause a system-wide deadlock.

Security Checks

The CBFilter class offers flexible security handling. During Control Events, applications can use information obtained from security-related methods to determine whether a request should be allowed as-is, modified before continuing, or denied immediately.

CBFilter provides a number of methods that applications can use to implement security checks. The most notable of these methods are get_originator_process_name and get_originator_process_id, which return the name and process Id (PID) of the process that initiated the request; and get_originator_token, which returns the system-defined security token of the process that initiated the request.

The latter is particularly useful when used with various methods in the Windows API, such as the GetTokenInformation function, which can be used to obtain various pieces of information about the object the token is associated with.

Effective security enforcement does not require that all event handlers perform security checks. Applications are technically free to deny almost any file-related event because of a failed security check. It is not, however, meaningful to perform security checks in all event handlers in the first place, and unnecessary security checks will decrease an application's overall performance.

For example, it makes sense to validate access rights in the on_before_create_file, on_after_create_file, on_before_open_file, and on_after_open_file event handlers, but not in the on_after_read_file or on_before_write_file event handlers. If an application denies a file create/open request made by some process, then that process will not be able to make a subsequent read/write request. Therefore, applications can safely assume that all read/write requests come from processes whose access rights they have already verified. Similar logic can be applied for directories and directory enumerations.

Note: This is not an exhaustive set of use-cases; each application's needs will differ.

As stated earlier, applications are free to allow, modify, or deny any request based on security checks. However, they must not "selectively alter" filesystem information based on these checks; it is "all or nothing". Following are some examples to clarify implementation:

• A filesystem object cannot appear to exist to process A, but appear nonexistent to process B.
• A filesystem object cannot be reported as a file to process A, but as a directory to process B.
• A filesystem object's metadata, absent of actual changes, must be consistent between requests (e.g., if a file's size is reported as 1 KB to process A, then it must also be reported as 1 KB to process B).
• A file's contents, absent of actual changes, also must be consistent between requests (e.g., for a file whose size is reported as 1 KB, exactly 1024 bytes must be returned when the file is read, and those 1024 bytes must be exactly the same, including ordering, regardless of which process is doing the reading).

File Create/Open Events

The CBFilter class provides three pairs of events related to creating and opening files:

• on_before_create_file and on_before_open_file, which are Control Events fired when the request is made.
• on_after_create_file and on_after_open_file, which are Control Events fired after the request has been handled.
• on_notify_create_file and on_notify_open_file, which are Notification Events fired after the request has been handled.

Note: The Notification Events are also available in CBMonitor; please refer to the Event Types topic for more information.)

Files can be created or deleted at any time, so there is no way for the OS to know with complete certainty whether a particular file exists until an interested process actually attempts to access it. This is true even if the process checks whether the file exists beforehand, because that file could then be created/deleted in the time between when the check occurred and when the create/open call occurs.

For this reason, the same Windows API function, CreateFile, is used for both creating and opening files. Processes that call this function use its CreationDisposition parameter to specify what the OS and filesystem should do if the file exists/does not exist. The one and only CreationDisposition option that results in a "create file" request is CREATE_NEW; all other options result in an "open file" request, and the filesystem then uses the CreationDisposition for guidance.

Because the class's only source of information is the requests themselves, they also have no way of knowing whether a particular file exists (or not) at any given time. Thus, they simply act in the following manner:

• If the request's CreationDisposition is CREATE_NEW, then the *CreateFile events are used.
• If the request's CreationDisposition is FILE_SUPERSEDE (an NT-native flag used in the kernel), then the *OpenFile events are used, followed by the corresponding *CreateFile events.
• In all other cases, the *OpenFile events are used.

Cached and Non-Cached Requests

Windows has an extremely robust file caching system that it makes extensive use of to provide optimal file I/O performance at all times. To accomplish this, file read/write requests are routed to the cache manager by default, and the cache manager attempts to service said requests with as few actual filesystem calls as possible. These behaviors result in a file I/O model that has three separate "paths" for file data to flow over:

1. From an application (or system component) to the system file cache.
2. From the system file cache to the filesystem.
3. From an application to the filesystem (bypassing the system file cache).

By default, the CBFilter and CBMonitor classs track file read/write requests only on paths (2) and (3); such operations are referred to as noncached requests (or, noncached operations). To include requests on path (1) (referred to as cached requests/operations), the process_cached_io_requests property must be enabled. This property is disabled by default, because in most cases, it is not necessary to intercept cached requests.

To distinguish between cached and noncached file read/write requests, applications can check the Direction parameter provided in the following events:

• on_before_read_file
• on_before_write_file
• on_after_read_file
• on_after_write_file
• on_notify_read_file
• on_notify_write_file

Note: All API members discussed in this topic are available in both CBFilter and CBMonitor, except for the Control Events, which are available only in CBFilter.)

Monitoring Network Resources

In certain cases, it may be desirable for a CBFilter/CBMonitor-based application to be able to track filesystem operations performed on a remote system, such as a file server. It is important to understand the limitations of Windows' filesystem filtering mechanisms to maintain reasonable expectations when developing for such use-cases.

The CBFS Filter system drivers must be installed on a machine for an application built with CBFilter or CBMonitor to be able to track filesystem requests on it; and, similarly, the CBFilter and CBMonitor classs can only track filesystem requests that are made against a local filesystem.

For example, imagine an environment with a file server S, and two client machines C1 and C2. If C1 and C2 have both mounted the filesystem shared by S as a network drive, then two options are available for tracking all requests directed at that filesystem:

1. Install the application on S and track filesystem operations on the shared drive.
2. Install the application on both C1 and C2 and track filesystem operations on the mounted network drive.

In the latter case, it is necessary to install the application on both client machines because the requests that originate on C1 cannot be seen on C2, and vice versa.

Request Modification

Modification of file read/write requests will only work correctly for local filesystems due to how Windows actually transfers the data internally. Attempting to modify the file data carried by a read/write request made against a locally mounted network drive will always fail.

CBRegistry Topics

The topics in this section provide additional information specific to the CBRegistry class.

Topics

• Registry Key Masks
• Contexts
• Security Checks

Registry Key Masks

Registry key masks are "templates" against which registry key names are matched. A registry key mask may begin with a "registry key path" or may simply be a standalone key name; and both the key name part and the path part may contain single-character wildcards (?) or multicharacter wildcards (*). Following are a few examples of registry key masks:

• \REGISTRY\MACHINE\Software\*
• HKEY_LOCAL_MACHINE\Software\*
• *Microsoft*

Note: Some registry keys are reparse points, and the driver cannot match masks that contain the names of such reparse points. For example, "HKEY_LOCAL_MACHINE\System\CurrentControlSet" is a reparse point; thus, the rule to track operations on its subkeys must refer to targets and not to the reparse point. As a result, the following sample rule will work: "HKEY_LOCAL_MACHINE\System\*ControlSet*\Enum" (here, asterisks are wildcard marks to let the rule cover various "ControlSetNN" keys).

Contexts

It is often necessary for an application to associate certain information with a given registry key. To assist developers in doing so in a convenient and performant manner, the CBRegistry class provides context parameters in a number of events.

A context carries an application-defined value that identifies or points to some application-defined data, and a registry key has a separate context associated with it. The CBRegistry class treats context values as opaque. It stores the context values passed to it by the application and ensures that the correct values are exposed again whenever some event fires for a particular registry key; but otherwise, it does not attempt to use said values in any way.

Context Lifetimes

Key contexts in CBRegistry are available in all events that correspond to registry key operations. They are created before the on_before_create_key or on_before_open_key event fires, and they are deleted after the on_after_close_key event fires (or, more accurately, after the on_cleanup_key_context event fires).

Context Use Cases

Key contexts are most helpful when used to store information associated with a registry key that can be used to speed up later events. For example, the only time the CBRegistry class exposes the name of a registry key is during the on_before_create_key and on_before_open_key events. Applications that wish to use the key name in later events can store it in the key context and then access it in the desired events later. A similar strategy can also be applied for events related to registry key values.

More generally, applications are free to obtain and store whatever information they wish using contexts, as long as their event handlers comply with the restrictions described by the Recursive Calls topic.

Using Contexts

Python does not have a completely safe way to store object references in contexts either directly or indirectly, which is why all context parameters are integers. To emulate such capabilities, the following approach is recommended:

1. Create a global dictionary instance for the application (i.e., a singleton), with keys that are integers and values of whatever type is desired.
2. When the application needs to create a context object in an event handler, a "key" can be created using the hash of the full file/directory name (including path), potentially mixed with additional information.
   • For file contexts, a hash of the full file/directory name is sufficiently unique because the context is exposed in all events pertaining to that file/directory.
   • For handle and enumeration contexts, additional information must be mixed in because multiple handle or enumeration contexts may be present at once for any given file/directory.
3. Using the created key, add the object to the dictionary.
4. Set the context parameter to the key used in the previous step.
5. To access the object in a later event, use the key stored by the context to retrieve the object from the dictionary.

Notes:

• Applications must take care to enforce proper thread synchronization when accessing the dictionary because events are always fired using worker threads. Please refer to the Threading and Concurrency topic for more information.
• In 32-bit applications, contexts are stored in 32-bit variables internally, and thus, the higher 32 bits of 64-bit values are lost.

Security Checks

The CBRegistry class offers flexible security handling. During events, applications can use information obtained from security-related methods to determine whether a request should be allowed as-is, modified before continuing, or denied immediately.

CBRegistry provides three security-related methods that applications can use to help implement security checks. They are get_originator_process_name and get_originator_process_id, which return the name and process Id (PID) of the process that initiated the request; and get_originator_token, which returns the system-defined security token of the process that initiated the request.

The latter is particularly useful when used with various methods in the Windows API, such as the GetTokenInformation function, which can be used to obtain various pieces of information about the object the token is associated with.

Driver Altitudes

A key benefit of filter drivers in general is that any number of them can be active at the same time. To keep things organized, Windows maintains a separate stack of filter drivers for each applicable system component (filesystem, registry, and process manager) and ensures that each stack is sorted consistently based on the drivers' altitudes.

These altitudes, which are expressed in a string notation as numbers with an optional fractional part (e.g., "12345.768"), essentially define each driver's absolute position in the stack. Drivers with higher altitudes are attached toward the top of the stack, closer to user mode, whereas drivers with lower altitudes are attached toward the bottom of the stack, closer to the applicable system component. Please refer to Microsoft's Load Order Groups and Altitudes for Minifilter Drivers article for more information about altitudes (much of the content is specific to filesystem filter drivers, but the general concepts apply to all filter drivers).

When an operation is requested, that request "enters" the top of the filter driver stack and moves downward, toward the applicable system component. Once the request has been handled (either by the system component or by one of the filter drivers in the stack), a response travels back up the stack. So the process of choosing a suitable altitude depends primarily on the intended functionality of the filter application being developed. That said, some factors are specific to each type of filter driver; please refer to the sections below for more information.

Filesystem Minifilter Drivers

Of the three kinds of filter drivers mentioned above, filesystem filter drivers are by far the most complex, which is why much of Microsoft's altitude documentation is presented from a filesystem-centric context. To prevent collisions, Microsoft also manages all filesystem minifilter altitude assignments.

When developing an application that uses CBFilter and/or CBMonitor, an altitude must be requested from Microsoft. Use the instructions described in their Minifilter Altitude Request article; and be sure to specify "FileSystem" (or "Both") for the "Filter type:" field when composing the request.

Once Microsoft has assigned an altitude for the application, it should be specified using the altitude property or the Altitude parameter of the install method, which are available in both CBFilter and CBMonitor.

Registry Filter Drivers

Registry filter drivers are not required to have an altitude (in which case they will be attached near the top of the driver stack), but it is recommended that one be requested anyway. Please refer to Microsoft's Supporting Layered Registry Filtering Drivers article for more information.

Although not explicitly stated in the aforementioned article, registry filter driver altitudes can be requested from Microsoft in the same manner as they are for filesystem minifilter driver altitudes. Use the instructions described in their Minifilter Altitude Request article; and be sure to specify "Registry" (or "Both") for the "Filter type:" field when composing the request.

Once Microsoft has assigned an altitude for the application, it should be specified using CBRegistry's altitude property.

Process Manager Filter Drivers

Microsoft is fairly vague about altitudes for process manager filter drivers; there is essentially no information about them beyond confirmation of their existence, as the documentation for the OB_CALLBACK_REGISTRATION structure shows. Notably, it is unclear whether there is a standard way to request an altitude for a process manager filter driver as there is for the other two kinds of filter drivers.

With that in mind, applications are free to set CBProcess's altitude property as desired. CBProcess also provides an extra property, strict_altitude, which specifies how the class should behave if the chosen altitude is already in use.

Event Handling

The topics in this section provide information about event handling.

Topics

• Event Types
• Buffer Parameters
• Recursive Calls
• Threading and Concurrency
• Timeouts

Event Types

The events provided by the CBFS Filter classs generally fall into two categories: Control Events, which are synchronous; and Notification Events, which are asynchronous.

Control Events allow an application to control the execution of an operation. They are fired before a request reaches the applicable system component. For certain operations, they also are fired after the request is handled (i.e., as its response comes back).

Control Events have names like BeforeOperation and AfterOperation (except for CBProcess, whose events do not have a prefix). In the CBProces class all events are Control Events that occur before the operation is completed.

Notification Events, which have names like NotifyOperation, inform an application that an operation has been performed. They are fired as a response comes back (specifically, after the applicable AfterOperation event fires, if such an event exists).

To get a better idea of the general event flow for an operation, please refer to this diagram:

1. A process sends a request, causing the corresponding BeforeOperation event to fire synchronously. The BeforeOperation events allow an application to do the following things:
   • Allow the request to continue, potentially after modifying its parameters/data.
   • Handle the request itself.
   • Deny the request entirely.
   • Store information about the request in the event's contexts, so that it can be used later during the AfterOperation event.
2. Once the request gets to the applicable system component, the requested operation will occur, and a response will be sent back to the process, causing the corresponding AfterOperation event to fire synchronously. The AfterOperation events allow applications to do the following things:
   • Perform an action based on whether the operation succeeded or failed.
   • Modify the response (if the operation supports doing so).
   • Do something earlier with the information stored in the event's contexts during the BeforeOperation event.
3. The response continues onward toward the process, causing the corresponding NotifyOperation event to fire asynchronously. The NotifyOperation events cannot be used to modify responses, nor do they include event contexts; they are best-suited for doing things like audit logging and change journaling.
   • More specifically, notification events are queued for delivery, and fired on a "best-effort" basis.
   • The notification event queue's size is not artificially limited; it will continue to grow (if necessary) so long as the system has sufficient resources available.

Note: The system can have multiple filter drivers loaded simultaneously, and any filter driver that a request or response "reaches" can do any of the things described above. Please refer to the Driver Altitudes topic for more information.

Each of the CBFS Filter classs provide a different set of events for each operation, so the event flow for a particular operation may be simpler than the one shown here depending on which class is being used. Following is a quick summary of which events each class offers:

• The CBFilter class offers BeforeOperation, AfterOperation, and NotifyOperation events for almost all operations.
• The CBProcess class only offers BeforeOperation events (though for simplicity, their names do not use the "Before" prefix).
• The CBRegistry class offers BeforeOperation and AfterOperation events.
• The CBMonitor class, a "monitoring-only" subset of CBFilter, offers the same NotifyOperation events, plus the on_before_filter_attach_to_volume, on_after_filter_attach_to_volume, and on_after_filter_detach_from_volume control events.

For more information about how to use event contexts in CBFilter, please refer to this topic; and for more information about how to use them in CBRegistry, please refer to this topic.

Buffer Parameters

Some events include one or more parameters intended for use as a binary data buffer. Depending on the event, these parameters may contain data when the event is fired, or it may be expected that the application populates them with the desired amount of data during the event handler. Some events combine both paradigms and then expect the application to modify the data already present when the event is fired.

The documentation for such events will describe which of these cases applies to each buffer parameter. In all cases, buffer parameters point to a preallocated block of unmanaged memory, the size of which is specified by the parameter immediately following the buffer parameter. In cases in which data are to be written, be sure to write it directly to the pointed-to memory, do not change the value of the buffer parameter itself. Buffer parameters are always of the ctypes.c_void_p type; use the ctypes.memmove() method to read and write data from and to the unmanaged memory region. To obtain a pointer to a Python buffer suitable for use with ctypes.memmove(), call ctypes.c_void_p.from_buffer() and pass it a byte array or some other type that implements Python's buffer interface.

Recursive Calls

To ensure stable operation, it is critical that applications avoid recursive access to the system component associated with each class. Essentially, this means that event handlers must comply with the following restrictions, which vary by class:

• CBFilter and CBMonitor: Event handlers must not attempt to perform any operations that involve the file or directory for which the event was fired.
  • Plus, they must comply with all restrictions discussed in the Avoiding Deadlocks topic (which is specific to CBFilter and CBMonitor).
  • There is one exception for CBFilter-based applications: During the on_after_create_file and on_after_open_file events, the create_file_direct method may be used to open the file that the event fired for. If the AllowFileAccessInBeforeOpen configuration setting is enabled, create_file_direct can also be used for the same purpose during the on_before_create_file and on_before_open_file events.
• CBProcess: Event handlers must not perform any operations that cause a process or thread to be created or terminated.
• CBRegistry: Event handlers must not perform any operations that cause registry access (either directly or indirectly).

  Note: Many system operations in Windows will perform registry access as part of their normal execution, and this side-effect is rarely documented (if ever).

Event handlers that violate any of these restrictions are likely to cause a system deadlock.

Additional information about third-party filters: Even when a file or registry operation seems to be generally safe, some third-party filter drivers may be not prepared for such recursive operations and will deadlock. Such filters must be dealt with on a case-by-case basis (usually by disabling them).

Threading and Concurrency

Through the use of multithreading, CBFS Filter provides powerful concurrency features to help applications maximize their performance. Each class provides the following API members to allow applications to specify the extent to which events should be fired concurrently:

• The serialize_events property controls whether events should be serialized on a single worker thread or fired in parallel on several. By default, this property is disabled and events are allowed to fire in parallel.
• The MinWorkerThreadCount and MaxWorkerThreadCount configuration settings control the minimum and maximum number of worker threads the classs can use for firing events. By default, both are set to 0, which indicates that a class's system driver should automatically choose appropriate values based on how many CPU cores the system has.
  • These settings are applicable only when serialize_events is disabled.

Note: Even when configured for minimal concurrency, the classs always fire events in the context of a worker thread, not in the thread the class was originally created on. Therefore, applications must be sure to synchronize operations between event handlers and other threads as necessary (including, but not limited to, calls to the class instance, unless a method is explicitly documented as callable within events).

Timeouts

(This topic references methods of the CBFilter class; the same methods exist in CBProcess and CBRegistry classes as well.)

Because the CBFS Filter classs' Control Events are tied directly to the underlying operations' requests and responses, it is critical that their event handlers complete quickly to prevent the system from being blocked. To help prevent such blocking, the classs' system drivers can enforce event timeouts.

To enable event timeouts, pass a nonzero value for the Timeout parameter when calling the start_filter method. Passing 0 will disable event timeouts, in which case, events may take as long as necessary to execute.

When timeout enforcement is in effect, and an event executes long enough for its timeout to expire, the driver either "releases" the underlying request (passing it onward unchanged), or cancels it by reporting an error; whichever is most appropriate for the event in question. The tardy event still runs to completion, but any results it returns once finished are ignored because the underlying request has already passed through the filter driver.

If an event handler knows it will require additional time to complete an operation, it can call the reset_timeout method before the current timeout expires to restart its timeout timer.

Applications should always strive to ensure that all event handlers complete quickly, even if request timeouts are disabled. Do not perform time-consuming work within event handlers; offload such work to background threads.

Note: This information is less relevant for Notification Events, which, because they fire asynchronously, cannot block the system. The CBMonitor class, therefore, does not expose a Timeout parameter in start_filter, or a method for resetting event timeouts; it operates without event timeout enforcement.

File and Registry Filter Rules

In their default state, the CBFS Filter classs ignore all operations; applications must explicitly specify which operations they are interested in by adding one or more filter rules. This "opt-in" approach prevents applications from being overwhelmed by the constant flood of operations occurring on a system at all times.

At a high level, there are two basic categories of filter rules: standard filter rules, which the classs use to determine which operations they should (or should not) fire events for; and special filter rules, which alter or augment the class's behavior in a variety of ways. The following sections discuss each category of filter rules in more detail, and provide class-specific information, where applicable.

Standard Filter Rules

Standard filter rules are typically an integral part of a CBFS Filter-based application's design. Thousands of operations may be occurring on a system at any given moment, and rarely are applications interested in more than a small subset of them. To start receiving events for those "interesting" operations, applications must add one or more standard filter rules so that the CBFS Filter driver knows which operations it needs to monitor.

For the CBFilter, CBMonitor, and CBRegistry classs, standard filter rules always contain two key pieces of information:

1. A mask that determines which files or registry keys the filter matches (or "covers"). The CBFilter and CBMonitor classes use File Masks, while the CBRegistry class uses Registry Key Masks.
   • For CBFilter and CBMonitor, standard filter rules can also include additional qualifiers like file size and attributes, but the mask always takes precedence.
2. A set of flags that specifies what kinds of filesystem/registry operations the class should fire events for.

Together, this pair of parameters gives applications great flexibility, allowing them to create filter rules that are as broad or as narrow in scope as desired. For example, one application might wish to monitor any and all operations performed on files or registry keys whose name contains a specific word, whereas another application might only care about read operations performed on audio files in a specific directory, or on values of a specific registry key.

The CBFilter, CBMonitor, and CBRegistry classs provide the following methods for managing standard filter rules:

• add_filter_rule
• add_filter_rule_ex (CBFilter and CBMonitor only)
• delete_filter_rule
• delete_all_filter_rules

For the CBProcess class, whose design is far less complex than the other class's design, standard filter rules are much simpler. Applications specify which processes they wish to monitor and ignore by name and/or PID using the following methods:

• add_filtered_process_by_name and remove_filtered_process_by_name
• add_filtered_process_by_id and remove_filtered_process_by_id
• add_ignored_process_by_name and remove_ignored_process_by_name
• add_ignored_process_by_id and remove_ignored_process_by_id

For all classs, standard filter rules are deactivated and deleted when the application exits.

Special Filter Rules

In addition to standard filter rules, the CBFilter, CBMonitor, and CBRegistry classs also support special filter rules. Unlike standard filter rules, special filter rules determine when a class should do something other than fire its events. There are multiple types of special filter rules, each of which alters (or augments) a class's behavior in a different way.

The following table provides links to topics with more information about each type of special filter rule, as well as information about which types are supported by each class.

Note: The CBProcess class does not support any special filter rules.

Rulesets

All rules, regardless of their type, are stored in some sort of ruleset; and within a ruleset, rules are uniquely identified by their masks. Adding multiple rules with the same mask to a particular ruleset will result in a single aggregate rule. Knowledge of this behavior is helpful for understanding how to use the methods that add and delete rules.

The number of rulesets each class has depends on its complexity. The most complex class, CBFilter, has four rulesets:

• One for standard filter rules and access rules (please refer to the Access Rules topic for more information on how this works).
• One for default rules.
• One for passthrough rules.
• One for reparse rules.

Access Rules

Access rules are a type of special filter rule supported by the CBFilter and CBRegistry classes. Access rules instruct the class's system driver to automatically process certain requests automatically in a certain manner, without involving the class itself.

Like standard filter rules, access rules use either a file mask or a registry key mask to determine which operations should be handled automatically. For CBFilter, access rules also can include additional qualifiers, such as file size and attributes; however, as with standard filter rules, the mask always takes precedence.

By adding a matching access rule, applications can effectively make one or more files or registry keys read-only, write-only, inaccessible, or protected from deletion. Because the desired access restrictions are enforced by the class's system driver, the application will not have to handle any events, which increases their overall performance and efficiency (especially if the application's sole purpose is access control).

If file creation and opening is covered by one or several rules in a way that both access flags and callback or notify flags should be in effect, access flags are ignored to let the process receive events for operations, specified using those callback and notify flags.

The methods that the CBFilter and CBRegistry classs provide for managing standard filter rules also are used to manage access rules:

• add_filter_rule
• add_filter_rule_ex (CBFilter only)
• delete_filter_rule
• delete_all_filter_rules

Access rules are stored in the same ruleset as the standard filter rules. As the File and Registry Filter Rules topic describes, each rule in a ruleset must have a unique mask; therefore, access rules and standard filter rules with the same mask are aggregated into a single rule. Knowledge of this behavior is helpful for understanding how these methods work.

Access rules are deactivated and deleted when the application exits. For use cases in which this is undesirable, applications may wish to use default rules instead; they provide the same functionality, but are managed by the class's system driver, and thus are enforced any time it is loaded, regardless of whether the application itself is open.

Default Rules

Default rules are a type of special filter rule supported by the CBFilter and CBRegistry classes. Default rules work the same way that access rules do, with one notable exception: they are managed by a class's system driver rather than by the class itself. As a result, they become active as soon as the class's system driver loads at boot time, and then they continue to be enforced at all times, regardless of whether the application that originally added them is open.

Note: Default rules have lower priority that all other filter rules. This means that if or when the application opens and begins to add other kinds of filter rules, any rules that "overlap" a default rule (i.e., those whose masks match one or more of the files or registry keys covered by a default rule) will take precedence, overriding the applicable default rule. When such a rule is removed (either directly or because of the application closing), the default rule that it was overriding will become active again.

The CBFilter and CBRegistry classs provide the following methods for managing default rules:

• add_default_rule
• delete_default_rule
• suspend_default_rules
• create_default_rules_snapshot
• close_default_rules_snapshot

The class's system driver stores information about default rules in the registry under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services key, which has restricted accessibility. Applications must therefore be running with Administrator or System Service rights (or their equivalent) to successfully add or remove default rules. (Running the application from an account that belongs to the administrator's group is not sufficient.)

Note: Default rules only work when a class's system driver is loaded. This means that default rules will not be available, for example, if the system boots in safe mode. Please refer to the Loading Drivers in Safe Mode topic for more information.

Passthrough Rules

Passthrough rules are a type of special filter rule supported by the CBFilter, CBMonitor, and CBRegistry classs. Passthrough rules instruct the class's system driver to explicitly exclude certain requests from processing, thus counteracting any standard filter rules or access rules that they otherwise would match.

Like standard filter rules, passthrough rules use either a file mask or a registry key mask to determine which files/directories or registry keys match. For CBFilter and CBMonitor, passthrough rules can also include additional qualifiers like file size and attributes; however, as with standard filter rules, the mask always takes precedence.

When adding a passthrough rule, applications can specify one or both of the following things:

• Which specific filesystem/registry operations the class should not fire events for (to counteract standard filter rules).
• Which specific access restrictions the class's system driver should not apply (to counteract access rules).

The CBFilter, CBMonitor, and CBRegistry classs provide the following methods for managing passthrough rules:

• add_passthrough_rule
• add_passthrough_rule_ex (CBFilter and CBMonitor only)
• delete_passthrough_rule
• delete_all_passthrough_rules

Passthrough rules are deactivated and deleted when the application exits.

Reparse Rules

Reparse rules are a type of special filter rule supported by the CBFilter class. Reparse rules are used to redirect file or directory access to another location based on two file masks: a source mask used for matching (in the same way as described for standard filter rules); and a destination mask to specify the location to redirect to.

For each wildcard (* or ?) present in the source mask, there must be a corresponding wildcard (of the same type) in the destination mask; and the wildcards in the destination mask must appear in the same order as they do in the source mask. For example, if the source mask is 20??_Budget.*, then 20??_Budget_Report.* would be a legal destination mask; however, 20??_Budget_Report.xls would not be a legal destination mask, nor would 20*_Budget_Report.*.

To use reparse rules effectively, it is important to understand two things about how they behave:

1. Reparse rules have priority over all other types of rules. So, if a file or directory matches a reparse rule, then it will always be redirected, even if it matches other types of rules as well.
2. The rule-matching procedure "restarts" every time a redirection occurs. So, if the newly redirected file or directory matches another reparse rule, then it is redirected again (and the matching procedure restarts again); otherwise, the matching procedure proceeds to consider other types of rules, as usual.

The second behavior is especially notable because it means that multiple reparse rules can "chain" together and be applied in succession. This is a powerful feature, but it must be used carefully; if a cycle of reparse rules is allowed to form, triggering it will send the system driver into an infinite loop, causing a system-wide deadlock.

The CBFilter class provides the following methods for managing reparse rules:

• add_reparse_rule
• delete_reparse_rule
• delete_all_reparse_rules
• create_reparse_rules_snapshot
• close_reparse_rules_snapshot
• get_reparse_rule_by_mask

Reparse rules are managed by the class's system driver rather than by the class. As a result, they will remain active until they are explicitly removed or the system reboots (whichever occurs first), regardless of whether the application that originally added them remains open.

Applications that require more advanced redirection logic can add a standard filter rule that includes the FS_CE_REPARSE_FILENAME control event flag, and then can use the on_reparse_file_name event to implement it.

Note: Neither this event, nor the on_reparse_with_tag event, are directly related to the reparse rules.

Network Filter Rules

In their default state, the CBFS Filter classs ignore all operations; applications must explicitly specify which operations they are interested in by adding one or more filter rules. This "opt-in" approach prevents applications from being overwhelmed by the constant flood of operations occurring on a system at all times.

The CBNETWORKclass provides the following methods for managing standard filter rules:

• add_filter_rule
• delete_filter_rule
• delete_all_filter_rules

Filter rules are deactivated and deleted when the application exits.

Passthrough Rules

Loading Drivers in Safe Mode

When booting in Safe Mode, Windows loads only a limited set of drivers. If circumstances require that one or more of the CBFS Filter drivers be loaded in Safe Mode, this can be accomplished by adding the filenames of the applicable drivers to the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SafeBoot.

Warning: Attempting to load the CBFS Filter drivers in Safe Mode can render the system unbootable if the driver fails or (for the CBFilter and CBRegistry classs' drivers in particular) if the Default Rules added using the CBFilter or CBRegistry class prevent the system from accessing any of the files or registry keys it needs to boot.

PID Reuse

When using various rules that are based on process IDs (PID), you need to be aware that Windows tends to reuse PID numbers. Once the process with a certain PID is finished in any way, Windows can re-use this PID for another process being started. And it does reuse PIDs quite frequently for the purpose of keeping PID numbers low.

Such reuse can cause unexpected and sometimes unpleasant consequence for your application. To counteract it, you can take one or both actions:

1. Open a handle to the process with the needed PID and not close it as long as your rule exists. Windows documentation states that as long as there exists an open handle to a process, its PID is not reused.
2. Track completion of the process with the given PID (either by monitoring the state of the process by its handle or using CBProcess component of the CBFS Filter product) and once the process is finished, delete the corresponding rule.

Error Reporting and Handling

Error Codes

The CBFS Filter communicates errors using the Win32 error codes defined in WinError.h, which is part of the Windows Platform SDK. The CBFS Filter system drivers, however, use NT native error codes, which do not have one-to-one mappings with Win32 error codes. The class includes logic for converting between the two as necessary, and that logic can be updated if any codes are not covered.

Additionally, CBFS Filter uses use certain error codes in a special manner. For more information about such error codes, please refer to the Error Codes page (available for each class).

Reporting Errors to the Class from Event Handlers

If an event has a ResultCode parameter, an event handler can use it to return the result code of the operation to the class. The ResultCode parameter is set to 0 by default, which indicates the operation was successful.

If an unhandled exception occurs in the event handler, it will be caught by the class, which will fire the OnError event.

In some events, the OS does not expect the error code to be returned and either the class or the OS ignores the returned error code. Please refer to the description of a particular event for more information.

How to Handle Errors Reported by the Class

If an error occurs, the class will throw an exception. The code property of the exception object will contain an error code, and the message property will contain an error message (if available).

Extended Logging in Windows

Some class methods in CBFS Filter are capable of writing extended information about reported errors to the Windows event logs, which can be viewed using the system's eventvwr.exe tool. The user mode part of the class writes to the "Windows Logs \ Application" folder, while the kernel mode part writes to the "Windows Logs \ System" folder.

The information written in the extended logs is meaningful to the Callback Technologies development team, but not to end-users, so extended logging is disabled by default. If issues occur during the installation of the CBFS Filter system drivers, or while using the class, please do the following:

1. Enable extended logging (see below).
2. Replicate the issue.
3. Using Event Viewer (eventvwr.exe), export the event log entries from the locations mentioned above in native format (please restrict the scope of the export to just those entries related to CBFS Filter).
4. Submit an issue report that includes the exported file.

There are two ways to toggle extended logging for a class:

1. By toggling the class's LoggingEnabled configuration setting (available in all classes).
2. By adding a DWORD-typed value named Enabled to the HKEY_LOCAL_MACHINE\SOFTWARE\Callback Technologies\{ClassName}\EventLog registry key and setting it to 0 (disabled) or 1 (enabled).
   • Replace the {ClassName} part of the registry key path with the name of the applicable class (use CBFilter for both CBFilter and CBMonitor).
   • If this registry key, one of its parents, or the actual value does not exist, please create it manually.

   Note: If your code runs in emulated mode (x86 mode on x64 or ARM64 architecture), you need to add the value to the HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Callback Technologies\{ClassName}\EventLog registry key in addition to the "main" registry key.

The system must be rebooted anytime extended logging is enabled or disabled to make the changes take effect.

Troubleshooting

CBFS Filter is a complex product that operates in both user mode and kernel mode simultaneously; so when a serious issue occurs, it's critical that we are able to obtain sufficient information about the circumstances of the failure.

In order to help us assist you in a more expedient manner, please collect the information described in the instructions below when reporting a serious issue (i.e., one that causes the system to crash or hang). Our development team cannot effectively diagnose such issues without this information.

Also, please note that these sorts of issues commonly involve environmental differences and other factors that are either unforeseen or otherwise out of our control. It is also not unheard-of for a crash to appear attributable to one thing while in fact being caused by something completely different. Rest assured that we are committed to assisting you as best we can, and we thank you ahead-of-time for your patience and understanding throughout the support process.

System Crashes (BSODs)

If you encounter a consistently-reproducible system crash (BSOD) that you suspect may be due to CBFS Filter, please obtain a crash dump and include it when reporting the issue to us. Our development team is unable to diagnose system crashes without the information these dumps contain.

Ensure that your system is set up to generate crash dumps, and to not restart automatically after a crash, by following the steps found in Microsoft's Enabling a Kernel-Mode Dump File article. The options available in the memory dump dropdown vary depending on your version of Windows; please choose the first one from the following list that is present in yours:

• Complete
• Full
• Automatic
• Kernel

Once your system is set up to generate crash dumps, perform the same action that caused the BSOD originally to trigger the crash again. When it occurs, be sure to copy the information on the BSOD screen exactly so that it can be included in your submission (a picture of the screen in which all of the information is legible is also acceptable). Here are some examples of the specific information we're looking for:

Recent versions of Windows:

What failed: cbfs***22.sys Stop Code: FILE_SYSTEM

Older versions of Windows:

STOP: 0x00000022 (0x00240076, 0xF7A07AA8, 0xF7A077A8, 0xF7800C82) cbfs***22.sys - Address F7800C82 base at F77CD000, DateStamp 447d6975

After you've copied this information, reboot and check that the memory dump file was created at %SYSTEMROOT%\MEMORY.DMP (typically this is C:\Windows\MEMORY.DMP; if you changed the dump file location in the crash dump settings, check the location you specified instead). It will be a very large file that is too big to attach to an email, so please upload it to a file sharing site of your choice and generate a sharing link that our development team can use to download it.

Finally, submit a support issue to us that includes the link to your dump file, all of the information from the BSOD screen (if you took a picture, attach it or provide another sharing link), a description of how the BSOD was triggered, and any other information that you feel is relevant.

System Hangs

If you encounter a consistently-reproducible system hang that you suspect may be due to CBFS Filter, you'll need to collect the same information as described above. But in order to obtain a crash dump, you'll first need to configure your system so that you can trigger a crash from the keyboard once it hangs. To make this possible, follow these steps (adapted from Microsoft's Forcing a System Crash from the Keyboard article):

1. First, using the instructions provided in the section above, configure your system to generate crash dumps, and to not restart automatically after a crash.
2. Next, you must enable keyboard-initiated crashes in the registry by creating a new value named CrashOnCtrlScroll, and setting it equal to a REG_DWORD value of 0x01, in all of the following registry keys:
   • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\i8042prt\Parameters
   • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\kbdhid\Parameters
   • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\hyperkbd\Parameters
3. Finally, you must restart the system in order for these settings to take effect.

After these steps are complete, you'll be able to trigger a keyboard-initiated crash by using the following hotkey sequence: hold down the Right CTRL key, and press the SCROLL LOCK key twice.

At this point, you can perform the same action that caused the system to hang originally to trigger the hang again. Once the system hangs, use the hotkey sequence to force it to crash, and then follow the rest of the instructions from the section above to collect and submit the necessary information.

Method Never Returns

If your application makes a call to some CBFS Filter method and that method never returns, there's a high chance that the driver deadlock has occurred. This can be caused by various factors; to determine the reason and possible solutions, we need a memory dump, as described above. If your system remains functional, you may also use easier ways to initiate a crash:

1. Use the NotMyFault tool by SysInternals to initiate a system crash. This is the preferred way because it generates Complete memory dumps. This tool has a self-explanatory GUI.
2. Use the LiveKD tool by SysInternals to create a live memory dump without crashing a system. The disadvantage of this method is that it creates Kernel dumps that are missing user-mode information. To use LiveKD on 32-bit systems, use this command: "livekd.exe -ml -o memory.dmp". On 64-bit systems, the command line would be "livekd64.exe -ml -k .\kd64.exe -o memory.dmp".

Application Crashes

Sometimes, an application crashes while the OS continues to operate, and the name of one of the modules of CBFS Filter is present in the crash information. A crashing application can be the one that uses CBFS Filter or some third-party process. If the crash occurs repeatedly, it is possible to make use of a User-Mode Crash Dump to locate or narrow down the source of the crash. Generation of crash dumps is disabled by default. Before you reproduce the crash, you need to Enable Collecting User-Mode Crash Dumps.

After you enable the crash dump, you don't need to reboot, you can proceed to reproduction of the crash immediately. After the crash re-occurs, you can pick the dump file from its location. The default locations of user-mode dump files are:

• For regular applications: %LOCALAPPDATA%\CrashDumps
• For System services: %WINDIR%\System32\Config\SystemProfile
• For Network and Local services: %WINDIR%\ServiceProfiles

If you changed the dump file location in the crash dump settings in the Registry, check the location you specified instead.

A crash dump can be a large file (depending on the settings) that is too big to attach to an email, so please upload it to a file sharing site of your choice and generate a sharing link that our development team can use to download it.

Finally, submit a support issue to us that includes the link to your dump file, a description of how the BSOD or a manual crash was triggered, and any other information that you feel is relevant.

Constants

All constants are defined in the cbfsfilter module.