CBFS Filter 2020 Python Edition

Questions / Feedback?

CBFilter Class

Properties   Methods   Events   Configuration Settings   Errors  

The CBFilter class allows applications to intercept and control filesystem requests.

Syntax

class cbfsfilter.CBFilter

Remarks

The CBFilter class gives applications the ability to intercept filesystem requests, allowing them to be altered, handled, blocked, etc. Applications use standard filter rules to specify which requests they're interested in intercepting; and special filter rules to enforce access restrictions and redirect requests to different files.

To learn more about the class's capabilities, please refer to the product's General Information topics.

Getting Started

  1. If the class's system driver hasn't been installed yet, call the install method to do so. This only needs to be done once.
    • In production, the driver can be installed (or updated) ahead-of-time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
  2. Call the initialize method to initialize the CBFilter class. This must be done each time the application starts.
  3. Add one or more filter rules using methods like add_filter_rule. (Rules can also be added/removed after the filter is started.)
  4. Call the start_filter method to start filtering filesystem requests.
  5. When finished, call the stop_filter method to stop filtering filesystem requests.
  6. To uninstall the class's system driver, call the uninstall method. This should not be done as part of the driver upgrade process.
    • In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

activeWhether the class is active and processing requests.
altitudeThe altitude the class's system driver should use when operating in minifilter mode.
default_rule_countThe number of records in the DefaultRule arrays.
default_rule_access_flagsThe access restrictions enforced by the rule.
default_rule_maskA file mask that determines which files and directories match the rule.
file_flushing_behaviorThe file flushing and closing behavior that the class's system driver should enforce.
filter_modeThe filter mode the class's system driver should use.
filter_rule_countThe number of records in the FilterRule arrays.
filter_rule_access_flagsThe access restrictions enforced by the rule (CBFilter only).
filter_rule_control_flagsWhich control events the rule causes the class to fire (CBFilter only).
filter_rule_ea_nameThe name of an extended attribute that a file or directory must have to match the rule.
filter_rule_excluded_attributesThe file attributes that a file or directory must not have to match the rule.
filter_rule_included_attributesThe file attributes that a file or directory must have to match the rule.
filter_rule_maskA file mask that determines which files and directories match the rule.
filter_rule_max_sizeThe maximum size a file can be to match the rule.
filter_rule_min_sizeThe minimum size a file can be to match the rule.
filter_rule_notify_flagsWhich notification events the rule causes the class to fire.
fire_volume_eventsThe events that should be fired when a filesystem volume is mounted to or unmounted from the system.
passthrough_rule_countThe number of records in the PassthroughRule arrays.
passthrough_rule_access_flagsThe access restrictions lifted by the rule (CBFilter only).
passthrough_rule_control_flagsWhich control events the rule prevents the class from firing (CBFilter only).
passthrough_rule_ea_nameThe name of an extended attribute that a file or directory must have to match the rule.
passthrough_rule_excluded_attributesThe file attributes that a file or directory must not have to match the rule.
passthrough_rule_included_attributesThe file attributes that a file or directory must have to match the rule.
passthrough_rule_maskA file mask that determines which files and directories match the rule.
passthrough_rule_max_sizeThe maximum size a file can be to match the rule.
passthrough_rule_min_sizeThe minimum size a file can be to match the rule.
passthrough_rule_notify_flagsWhich notification events the rule prevents the class from firing.
process_cached_io_requestsWhether cached file read/write requests should be processed.
process_failed_requestsWhether failed requests should be processed.
reparse_rule_countThe number of records in the ReparseRule arrays.
reparse_rule_maskA file mask that determines which files and directories match the rule.
reparse_rule_reparse_maskA file mask that specifies where matching files and directories are redirected to.
serialize_eventsWhether events should be fired on a single worker thread, or many.
tagStores application-defined data specific to this instance of the class.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

add_bytes_to_write_bufferReserves extra space in the file data buffers used in file read/write events.
add_default_ruleAdds a default rule.
add_filter_ruleAdds a standard filter rule or access rule.
add_filter_rule_exAdds a standard filter rule or access rule with additional match qualifiers.
add_passthrough_ruleAdds a passthrough rule.
add_passthrough_rule_exAdds a passthrough rule with additional match qualifiers.
add_reparse_ruleAdds a reparse rule.
close_default_rules_snapshotCloses the previously-created default rules snapshot.
close_reparse_rules_snapshotCloses the previously-created reparse rules snapshot.
configSets or retrieves a configuration setting.
create_default_rules_snapshotCreates a snapshot of information about the default rules that have been added.
create_file_directCreates or opens a file or directory by passing the request directly to the filesystem.
create_file_direct_as_streamCreates or opens a file by passing the request directly to the filesystem.
create_reparse_rules_snapshotCreates a snapshot of information about the reparse rules that have been added.
create_virtual_fileThis method is under construction.
delete_all_filter_rulesDeletes all standard filter rules and access rules.
delete_all_passthrough_rulesDeletes all passthrough rules.
delete_all_reparse_rulesDeletes all reparse rules.
delete_default_ruleDeletes a particular default rule.
delete_filter_ruleDeletes a particular standard filter rule or access rule.
delete_passthrough_ruleDeletes a particular passthrough rule.
delete_reparse_ruleDeletes a particular reparse rule.
file_matches_maskChecks whether a particular file or directory name matches the specified mask.
flush_notification_queueFlushes the notification event queue.
get_driver_statusRetrieves the status of the class's system driver.
get_driver_versionRetrieves the version of the class's system driver.
get_handle_creator_process_idRetrieves the Id of the process (PID) that opened the file handle.
get_handle_creator_process_nameRetrieves the name of the process that opened the file handle.
get_handle_creator_thread_idRetrieves the Id of the thread that opened the file handle.
get_handle_creator_tokenRetrieves the security token associated with the process that opened the file handle.
get_originator_process_idRetrieves the Id of the process (PID) that initiated the operation.
get_originator_process_nameRetrieves the name of the process that initiated the operation.
get_originator_thread_idRetrieves the Id of the thread that initiated the operation.
get_originator_tokenRetrieves the security token associated with the process that initiated the operation.
get_reparse_rule_by_maskRetrieves the reparse rule associated with the specified file mask.
get_volume_guidRetrieves the volume GUID of the device targeted by a filesystem operation.
initializeInitializes the class.
installInstalls (or upgrades) the class's system driver.
is_file_filteredChecks whether a particular file or directory is covered by any filter rules.
nt_status_to_win_32_errorConverts a native status code to a Win32 error code.
reset_timeoutResets the timeout duration for the current event handler.
set_file_size_directResizes a file by passing the request directly to the filesystem.
shutdown_systemShuts down or reboots the operating system.
start_filterStart filtering filesystem operations.
stop_filterStop filtering filesystem operations.
suspend_default_rulesSuspends all default rules until the application exits.
suspend_file_eventsSuspends all events for a particular file or directory until all of its handles have been closed.
toggle_process_protectionEnables or disables termination protection for the application.
uninstallUninstalls the class's system driver.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

on_after_can_file_be_deletedFires after the filesystem determines whether a file or directory can be deleted.
on_after_cleanup_fileFires after a file or directory handle is closed.
on_after_close_enumerationFires after a directory enumeration operation finishes.
on_after_close_fileFires after a file or directory is closed.
on_after_create_fileFires after a file or directory is created.
on_after_create_hard_linkFires after a hard link is created.
on_after_delete_fileFires after a file or directory is deleted.
on_after_enumerate_directoryFires after a directory entry is returned during directory enumeration.
on_after_filter_attach_to_volumeFires after the filter attaches to a newly-mounted filesystem volume.
on_after_filter_detach_from_volumeFires after the filter detaches from a filesystem volume.
on_after_fsctlFires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
on_after_get_file_securityFires after a file or directory's security attributes are retrieved.
on_after_get_file_sizesFires after a file's size information is retrieved.
on_after_ioctlFires after an IRP_MJ_DEVICE_CONTROL request is processed.
on_after_lockFires after a range of bytes in a file is locked.
on_after_open_fileFires after a file or directory is opened.
on_after_query_file_infoFires after information about a file or directory is retrieved.
on_after_read_fileFires after data is read from a file.
on_after_rename_or_move_fileFires after a file or directory is renamed or moved.
on_after_set_allocation_sizeFires after a file's allocation size is changed.
on_after_set_file_attributesFires after a file or directory's attributes and/or times are changed.
on_after_set_file_infoFires after information about a file or directory is changed.
on_after_set_file_securityFires after a file or directory's security attributes are changed.
on_after_set_file_sizeFires after a file is resized.
on_after_unlock_allFires after all locked byte ranges in a file are unlocked.
on_after_unlock_all_by_keyFires after all locked byte ranges in a file, associated with a particular key, are unlocked.
on_after_unlock_singleFires after a particular locked byte range in a file is unlocked.
on_after_write_fileFires after data is written to a file.
on_before_can_file_be_deletedFires before the filesystem determines whether a file or directory can be deleted.
on_before_cleanup_fileFires before a file or directory handle is closed.
on_before_close_fileFires before a file or directory is closed.
on_before_create_fileFires before a file or directory is created.
on_before_create_hard_linkFires before a hard link is created.
on_before_delete_fileFires before a file or directory is deleted.
on_before_filter_attach_to_volumeFires before the filter attaches to a newly-mounted filesystem volume.
on_before_fsctlFires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.
on_before_get_file_securityFires before a file or directory's security attributes are retrieved.
on_before_ioctlFires before an IRP_MJ_DEVICE_CONTROL request is processed.
on_before_lockFires before a range of bytes in a file is locked.
on_before_open_fileFires before a file or directory is opened.
on_before_query_file_infoFires before information about a file or directory is retrieved.
on_before_read_fileFires before data is read from a file.
on_before_rename_or_move_fileFires before a file or directory is renamed or moved.
on_before_set_allocation_sizeFires before a file's allocation size is changed.
on_before_set_file_attributesFires before a file or directory's attributes and/or times are changed.
on_before_set_file_infoFires before information about a file or directory is changed.
on_before_set_file_securityFires before a file or directory's security attributes are changed.
on_before_set_file_sizeFires before a file is resized.
on_before_unlock_allFires before all locked byte ranges in a file are unlocked.
on_before_unlock_all_by_keyFires before all locked byte ranges in a file, associated with a particular key, are unlocked.
on_before_unlock_singleFires before a particular locked byte range in a file is unlocked.
on_before_write_fileFires before data is written to a file.
on_cleanup_contextFires when the application-defined data stored in one or more contexts needs to be cleaned up.
on_delete_virtual_fileFires when a virtual file needs to be deleted.
on_errorFires if an unhandled error occurs during an event.
on_filter_startFires once the filter has attached and filtering has started.
on_filter_stopFires once filtering has stopped and the filter has detached.
on_notify_can_file_be_deletedFires when the filesystem has determined whether a file or directory can be deleted.
on_notify_cleanup_fileFires when a file or directory handle has been closed.
on_notify_close_fileFires when a file or directory has been closed.
on_notify_create_fileFires when a file or directory has been created.
on_notify_create_hard_linkFires when a hard link has been created.
on_notify_delete_fileFires when a file or directory has been deleted.
on_notify_enumerate_directoryFires when a directory entry has been returned during directory enumeration.
on_notify_filter_attach_to_volumeFires when the filter has been attached to a newly-mounted filesystem volume.
on_notify_filter_detach_from_volumeFires when the filter has been detached from a filesystem volume.
on_notify_fsctlFires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.
on_notify_get_file_securityFires when a file or directory's security attributes have been retrieved.
on_notify_get_file_sizesFires when a file's size information has been retrieved.
on_notify_ioctlFires when an IRP_MJ_DEVICE_CONTROL operation has occurred.
on_notify_lockFires when a range of bytes in a file has been locked.
on_notify_open_fileFires when a file or directory has been opened.
on_notify_query_file_infoFires when information about a file or directory has been retrieved.
on_notify_read_fileFires when data has been read from a file.
on_notify_rename_or_move_fileFires when a file or directory has been renamed or moved.
on_notify_set_allocation_sizeFires when a file's allocation size has been changed.
on_notify_set_file_attributesFires when a file or directory's attributes and/or times have been changed.
on_notify_set_file_infoFires when information about a file or directory has been changed.
on_notify_set_file_securityFires when a file or directory's security attributes have been changed.
on_notify_set_file_sizeFires when a file has been resized.
on_notify_unlock_allFires when all locked byte ranges in a file have been unlocked.
on_notify_unlock_all_by_keyFires when all locked byte ranges in a file, associated with a particular key, have been unlocked.
on_notify_unlock_singleFires when a particular locked byte range in a file has been unlocked.
on_notify_write_fileFires when data has been written to a file.
on_reparse_file_nameFires to allow file access to be dynamically redirected another location.
on_reparse_with_tagFires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point.
on_worker_thread_creationFires just after a new worker thread is created.
on_worker_thread_terminationFires just before a worker thread is terminated.

Configuration Settings


The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.

AllowFileAccessInBeforeOpenWhether file access, via the CreateFileDirect method, is allowed in during the BeforeCreateFile and BeforeOpenFile events.
AlwaysPrepareFilesWhether the driver should keep track of information for files that are already open when (i.e., were opened before) the class is initialized.
CacheRemoteFilesLocallyWhether remote files involved in filtered operations should be cached locally rather than remotely.
FilterOwnRequestsWhether the class's system driver should filter requests made by the application itself.
ForceAppPermissionCheckWhether the driver should require the controller process to have elevated or system privileges.
ForceSecurityChecksWhether the driver should prevent the controller process from filtering files that it would not normally have access to.
LoggingEnabledWhether extended logging is enabled.
MaxWorkerThreadCountThe maximum number of worker threads to use to fire events.
MinWorkerThreadCountThe minimum number of worker threads to use to fire events.
ModifiableReadWriteBuffersWhether the driver should duplicate read/write buffers sent to the user.
PreprocessedRulesCacheSizeMaximum number of preprocessed rules to keep cached.
ResolveNtDeviceToDriveLetterWhether native device names are translated to drive letters.
SendRequestsViaDriverStackWhether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers.
WorkerInitialStackSizeThe initial stack size to create worker threads with.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Filter 2020 Python Edition - Version 20.0 [Build 7647]