CBFS Filter 2020 Python Edition

Questions / Feedback?

CBMonitor Class

Properties   Methods   Events   Configuration Settings   Errors  

The CBMonitor class allows applications to monitor filesystem requests.

Syntax

class cbfsfilter.CBMonitor

Remarks

The CBMonitor class is a "monitoring-only" subset of the CBFilter class; it gives applications the ability to monitor filesystem requests, allowing them to be logged, reported, etc. Applications use standard filter rules to specify which requests they're interested in monitoring.

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 CBMonitor 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 monitoring filesystem requests.
  5. When finished, call the stop_filter method to stop monitoring 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.
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.
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_filter_ruleAdds a standard filter rule.
add_filter_rule_exAdds a standard filter rule with additional match qualifiers.
add_passthrough_ruleAdds a passthrough rule.
add_passthrough_rule_exAdds a passthrough rule with additional match qualifiers.
configSets or retrieves a configuration setting.
delete_all_filter_rulesDeletes all standard filter rules.
delete_all_passthrough_rulesDeletes all passthrough rules.
delete_filter_ruleDeletes a particular standard filter rule.
delete_passthrough_ruleDeletes a particular passthrough 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_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_volume_guidRetrieves the volume GUID of the device targeted by a filesystem operation.
initializeInitializes the class.
installInstalls (or upgrades) the class's system driver.
nt_status_to_win_32_errorConverts a native status code to a Win32 error code.
shutdown_systemShuts down or reboots the operating system.
start_filterStart filtering filesystem operations.
stop_filterStop filtering filesystem operations.
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_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_before_filter_attach_to_volumeFires before the filter attaches to a newly-mounted filesystem volume.
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 OS marks a file or directory for deletion or removes such a mark.
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_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.

AlwaysPrepareFilesWhether the driver should keep track of information for files that are already open when (i.e., were opened before) the class is initialized.
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.
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) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Filter 2020 Python Edition - Version 20.0 [Build 8317]