IPMonitor Class

Properties   Methods   Events   Config Settings   Errors  

The IPMonitor class allows applications to monitor network packets on multiple platforms.

Syntax

class pcapfilter.IPMonitor

Remarks

IPMonitor is a lightweight class that allows applications to monitor network activity across multiple platforms, including Windows, Linux, and macOS. It utilizes the "libpcap" library and underlying network drivers to capture and report network packets in real-time. The class provides the ability to capture individual network packets for detailed analysis, or collect aggregated packet statistics for monitoring network performance.

Setup

Linux and macOS Before using the class, a libpcap-compatible network library must be installed on the system. For detailed installation instructions, please refer to the Network Filter Library section. This setup only needs to be done once. Also, permissions may need to be adjusted as described in the System Configuration in Linux and macOS instructions page to allow the application to capture packets.

Windows The class uses the NetFilter driver (can be found in the "drivers" directory of the PCAP Filter installation) and the helper libraries included in the "pcaplibs" directory of the installation. Please refer to the Driver-specific section for details on installing the driver to the system and to the User Mode Library page for information about deploying the helper libraries.

The driver must be installed via the NetFilter class and its install method before the driver can be used by IPMonitor. The helper libraries (packet.dll and wpcap.dll) that match your platform must be placed next to the EXE file of your application or copied to the system directory.

Retrieving Network Adapters

The first step in using the class is to identify the name of the network adapter that will be monitored. To retrieve the list of network adapters available on the system, call the list_adapters method. Once the method is called, the adapters will be accessible via the adapters property.

// Retrieve the list of network adapters available on the system ipmonitor.ListAdapters(); // Display the available adapters foreach (Adapter adapter in ipmonitor.Adapters) { Console.WriteLine($"Adapter Name: {adapter.Name}"); Console.WriteLine($"Description: {adapter.Description}"); }

Packet Filters

Before starting to monitor a network adapter, filters can be applied to capture only the packets that match certain criteria.

The direction property can be used to specify whether to capture incoming packets, outgoing packets, or both. In addition to directionality, the filter property can be set to a pcap filter expression string that allows for filtering based on IP addresses, protocol types, ports, and more. For more information on supported filter expressions, please see the pcap-filter(7) man page. // Only capture incoming packets ipmonitor.Direction = callback.PCAPFilter.Constants.PACKET_DIRECTION_INCOMING; // Only capture TCP packets from IP 192.168.1.1 on port 80 ipmonitor.Filter = "src host 192.168.1.1 and tcp port 80";

Operation Modes

In addition to packet filters, the class supports multiple operation modes that determine what kind of packet information will be reported.

Capture Mode

Setting the operation_mode property to omCapture (0) will cause the class to capture individual network packets and report them through the on_packet event. // Capture individual packet information ipmonitor.OperationMode = 0;

Statistical Mode

Setting the operation_mode property to omStat (1) will instead cause the class to collect aggregated packet statistics and report them through the on_statistics event. // Report aggregated packet statistics ipmonitor.OperationMode = 1;

Monitoring an Adapter

After configuring the filters and operation mode, start monitoring the network adapter by calling the activate method and specifying the adapter name.

// Get the name of the first adapter returned by ListAdapters() ipmonitor.ListAdapters(); string adapterToMonitor = ipmonitor.Adapters[0].Name; // Start monitoring the adapter ipmonitor.Activate(adapterToMonitor);

Retrieving Packet Information

Depending on the current operation_mode, packet information is retrieved differently. In both modes, the do_events method must be called to prompt the class to fire events and report packet information.

Capture Mode:

In capture mode, calling do_events will cause the class to process any packets captured by the class and fire the on_packet for each one. ipmonitor.OnPacket += (s, e) => { // Print out information about each individual packet Console.WriteLine($"Packet captured at {e.TimeStamp}"); Console.WriteLine($"Packet Size: {e.PacketSize} bytes"); };

Statistical Mode:

In statistical mode, calling do_events will prompt the class to collect packet statistics and report them through the on_statistics event. ipmonitor.OnStatistics += (s, e) => { // Print out packet statistics Console.WriteLine($"Statistics collected at {e.TimeStamp}"); Console.WriteLine($"Packets Captured: {e.CapturedPackets}"); Console.WriteLine($"Bytes Captured: {e.CapturedBytes}"); };

Capture Statistics

Regardless of the current operation_mode, cumulative statistics about the packets captured since monitoring began can be retrieved by calling the get_statistics method. long receivedPackets = 0; // The number of packets received since monitoring began long droppedPackets = 0; // The number of packets dropped by the component since monitoring began long adapterDroppedPackets = 0; // The number of packets dropped by the adapter since monitoring began ipmonitor.GetStatistics(ref receivedPackets, ref droppedPackets, ref adapterDroppedPackets); Console.WriteLine($"Packets Received: {receivedPackets}"); Console.WriteLine($"Packets Dropped: {droppedPackets}"); Console.WriteLine($"Packets Dropped by Adapter: {adapterDroppedPackets}");

Deactivating Monitoring

To stop monitoring the adapter and cease reporting packets, call the deactivate method. ipmonitor.Deactivate();

Property List

---

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

Method List

---

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

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.

Config Settings

---

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

active property

Indicates whether the class is active and monitoring network traffic.

Syntax

def get_active() -> bool: ...

active = property(get_active, None)

Default Value

FALSE

Remarks

This property reflects whether the class is actively monitoring network traffic. It is automatically set to True after a successful call to activate, and to False when monitoring is stopped with the deactivate method.

This property is read-only.

adapter_count property

The number of records in the Adapter arrays.

Syntax

def get_adapter_count() -> int: ...

adapter_count = property(get_adapter_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• adapter_buffer_size
• adapter_collect_statistics
• adapter_description
• adapter_friendly_name
• adapter_id
• adapter_interface_type
• adapter_mac_address
• adapter_max_packet_bytes
• adapter_name
• adapter_packet_timeout
• adapter_promiscuous_mode
• adapter_wi_fi_monitor_mode
• adapter_wi_fi_monitor_mode_supported

The array indices start at 0 and end at adapter_count - 1.

This property is read-only.

adapter_buffer_size property

Specifies the size of the kernel-level buffer associated with a capture, expressed in KB (kilobytes).

Syntax

def get_adapter_buffer_size(adapter_index: int) -> int: ...
def set_adapter_buffer_size(adapter_index: int, value: int) -> None: ...

Default Value

1024

Remarks

Specifies the size of the kernel-level buffer associated with a capture, expressed in KB (kilobytes).

This field is used only by the IPMonitor class when it is using a third-party capture driver and is ignored by NetFilter driver, which manages memory dynamically.

The default value of 0 tells libpcap to use the default value hard-coded in it. In Windows, this is 1 000 000 bytes (approx.1 megabyte); in Linux, this is 2MB.

The field corresponds to the pcap_set_buffer_size() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_collect_statistics property

Specifies whether the class should report statistics for this adapter when the class is operating in the omStat OperationMode .

Syntax

def get_adapter_collect_statistics(adapter_index: int) -> bool: ...
def set_adapter_collect_statistics(adapter_index: int, value: bool) -> None: ...

Default Value

TRUE

Remarks

Specifies whether the class should report statistics for this adapter when the class is operating in the omStat operation_mode.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_description property

The description of the network adapter.

Syntax

def get_adapter_description(adapter_index: int) -> str: ...

Default Value

""

Remarks

The description of the network adapter.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_friendly_name property

The human-readable name of the adapter, which may be modified by a user using Windows functionality.

Syntax

def get_adapter_friendly_name(adapter_index: int) -> str: ...

Default Value

""

Remarks

The human-readable name of the adapter, which may be modified by a user using Windows functionality.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_id property

Contains the Id of the adapter.

Syntax

def get_adapter_id(adapter_index: int) -> int: ...

Default Value

0

Remarks

Contains the Id of the adapter.

Each network adapter in the system has an Id that is used in all operations of NetFilter where an adapter is referenced by the class or must be specified by an application.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_interface_type property

Contains the type of the adapter interface.

Syntax

def get_adapter_interface_type(adapter_index: int) -> int: ...

Default Value

0

Remarks

Contains the type of the adapter interface.

This field specifies the type of the network with which the adapter works. The available values are defined by IANA.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_mac_address property

The MAC address of the adapter.

Syntax

def get_adapter_mac_address(adapter_index: int) -> str: ...

Default Value

""

Remarks

The MAC address of the adapter.

This field contains the MAC address of the adapter, if such an address exists (only some adapter types have MAC addresses).

The value may be absent or contains a MAC address in HEX-encoded form where bytes are ordered in the transmission order with each byte's HEX characters separated by a hyphen ("-").

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_max_packet_bytes property

Defines the maximum number of bytes of a packet to pass in events.

Syntax

def get_adapter_max_packet_bytes(adapter_index: int) -> int: ...
def set_adapter_max_packet_bytes(adapter_index: int, value: int) -> None: ...

Default Value

262144

Remarks

Defines the maximum number of bytes of a packet to pass in events.

The default value of 0 tells libpcap to set the maximum length to 262 144 bytes.

The field corresponds to the pcap_set_snaplen() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_name property

The name of the adapter.

Syntax

def get_adapter_name(adapter_index: int) -> str: ...

Default Value

""

Remarks

The name of the adapter. This value can be passed into the activate method to start monitoring the adapter in IPMonitor or as a parameter to the add_filter_rule method when adding filtration rules in NetFilter.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_packet_timeout property

Specifies the packet buffer timeout, expressed in milliseconds, which tell the driver how long it may wait before replying with no packets, when packets are not available.

Syntax

def get_adapter_packet_timeout(adapter_index: int) -> int: ...
def set_adapter_packet_timeout(adapter_index: int, value: int) -> None: ...

Default Value

1000

Remarks

Specifies the packet buffer timeout, expressed in milliseconds, which tell the driver how long it may wait before replying with no packets, when packets are not available.

This field is used only by the IPMonitor class when it is using a third-party capture driver and is ignored by NetFilter driver, which works in the so-called "immediate mode" in libpcap terms.

The value must be specified in milliseconds. The behavior if a zero or a negative value is set is not defined by libpcap, thus, it is recommended to always set the value to a positive number. The default value is 1000 ms (one second).

For the detailed description of a packet buffer timeout, please refer to libpcap documentation.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_promiscuous_mode property

Enables or disables the promiscuous mode on the adapter, telling the adapter to capture or skippackets that pass by, i.

Syntax

def get_adapter_promiscuous_mode(adapter_index: int) -> bool: ...
def set_adapter_promiscuous_mode(adapter_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Enables or disables the promiscuous mode on the adapter, telling the adapter to capture or skippackets that pass by, i.e., which do not originate in the given adapter and do not have it as a destination.

For the detailed description of the promiscuous mode, please refer to libpcap documentation.

In the IPMonitor class, the field corresponds to the pcap_set_promisc() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_wi_fi_monitor_mode property

Enables or disables the WiFi monitoring mode on the adapter.

Syntax

def get_adapter_wi_fi_monitor_mode(adapter_index: int) -> bool: ...
def set_adapter_wi_fi_monitor_mode(adapter_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Enables or disables the WiFi monitoring mode on the adapter.

This functionality is provided by adapters, not by the driver itself, and not all WiFi adapters support this mode. Check the adapter_wi_fi_monitor_mode_supported field before enabling the WiFi monitoring mode.

For the detailed description of the WiFi monitoring mode, please refer to libpcap documentation, where it is described under the "monitor mode" title.

In the IPMonitor class, the field corresponds to the pcap_set_rfmon() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_wi_fi_monitor_mode_supported property

Indicates whether the WiFi monitoring mode is supported by the adapter.

Syntax

def get_adapter_wi_fi_monitor_mode_supported(adapter_index: int) -> bool: ...

Default Value

FALSE

Remarks

Indicates whether the WiFi monitoring mode is supported by the adapter. Check this value before trying to enable the WiFi monitor mode.

This functionality is provided by adapters, not by the driver itself, and not all WiFi adapters support this mode.

For the detailed description of the WiFi monitoring mode, please refer to libpcap documentation, where it is described under the "monitor mode" title.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

direction property

Specifies the direction of packets to capture.

Syntax

def get_direction() -> int: ...
def set_direction(value: int) -> None: ...

direction = property(get_direction, set_direction)

Default Value

0

Remarks

The property makes it possible to capture just outgoing or just incoming packets, working as a simple filter for the network packets. The property value can be one of the following:

filter property

Specifies filter criteria used to determine which network packets are captured.

Syntax

def get_filter() -> str: ...
def set_filter(value: str) -> None: ...

filter = property(get_filter, set_filter)

Default Value

""

Remarks

This property specifies a filter expression string that determines which network packets are captured and reported. For additional filtering, the direction property can be used to limit packet capture to incoming or outgoing traffic.

This property can be set before or after calling activate to start monitoring. In some platforms, changing the value of this property while monitoring is active may result in some packets being dropped or reported even if they do not match the new filter rules. For more details on platform-specific behavior, please see the pcap-filter(7) man page.

Filter Expression Syntax

The filter expression follows the syntax used by libpcap. A filter takes the form of a series of conditions that specify the criteria packets must meet to be captured. Expressions can be combined using conjunctions and, or, and optionally preceded by not.

[not] condition [and|or [not] condition ... ]

For more comprehensive information on filter expressions, please refer to the pcap-filter(7) documentation. Below is a simplified overview of common filter expressions:

Example (Simple): // Only capture packets to and from IP 192.168.1.1 ipmonitor.Filter = "host 192.168.1.1";

Example (Advanced): // Only capture TCP packets from IP 192.168.1.1 on port 80 ipmonitor.Filter = "src host 192.168.1.1 and tcp port 80";

operation_mode property

Specifies the mode of operation.

Syntax

def get_operation_mode() -> int: ...
def set_operation_mode(value: int) -> None: ...

operation_mode = property(get_operation_mode, set_operation_mode)

Possible Values

0   # Capture
1   # Stat

Default Value

0

Remarks

This property determines the type of packet information to report when do_events is called. The property value can be one of the following:

tag property

This property stores application-defined data specific to a particular instance of the class.

Syntax

def get_tag() -> int: ...
def set_tag(value: int) -> None: ...

tag = property(get_tag, set_tag)

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the class.

activate method

Starts monitoring network traffic.

Syntax

def activate(adapter: str) -> None: ...

Remarks

This method enables monitoring network packets on a specified network adapter. To disable monitoring, call deactivate instead.

When this method is called, the class will begin monitoring the specified adapter for network activity. Packets will be captured and reported differently depending on the value of the operation_mode property. Once monitoring is active, the active property will be automatically set to True.

Adapter specifies the name of the network adapter to monitor. The list of available adapters can be obtained via the list_adapters method.

Packet Reporting

When active is set to True, the class will report packet information based on the value of the operation_mode property.

config method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

deactivate method

Stops monitoring network traffic.

Syntax

def deactivate() -> None: ...

Remarks

This method stops monitoring network traffic. Once called, the class will cease capturing packets and the active property will be automatically set to False.

do_events method

Processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

This method processes events from the internal message queue and fires the corresponding events based on the current operation_mode. It should be called periodically to prompt the class to fire events and report packet information.

Capture Modes

This method behaves differently depending on the value of the operation_mode property.

When operation_mode is set to omCapture (0), calling this method while monitoring is active will prompt the class to process any packets captured since the last call and fire the on_packet event for each one. If there are no new packets to report, the method will wait for a duration specified by the field of the Adapter that is being monitored before returning.

If operation_mode is set to omStat (1), calling this method will instead tell the class to collect packet statistics since the last call and fire the on_statistics event with the aggregated data.

get_statistics method

Retrieves the total number of packets received and dropped since monitoring began.

Syntax

def get_statistics(received: List[int], dropped: List[int], adapter_dropped: List[int]) -> None: ...

Remarks

This method provides capture statistics about the packets monitored by the class and the underlying driver since activate was called to start monitoring.

The Received parameter provides the number of packets received since monitoring began.

The Dropped parameter provides the number of packets that were dropped since monitoring began. Packets may be dropped if the value of the field of the Adapter that is being monitored is too small to keep all of the data, or because do_events was called too infrequently.

The AdapterDropped parameter provides the full number of packets that were dropped by the network adapter since monitoring began.

Platform Differences

This method is platform-dependent. It uses the underlying pcap_stats() function from the libpcap library to retrieve packet statistics, which may cause the values provided in the Received, Dropped, and AdapterDropped parameters to differ depending on the platform.

• Received: On some platforms, this count may include all packets, regardless of whether they matched the filter criteria set using filter.
• Dropped: This value may not be available on all platforms.
• AdapterDropped: This count might not be implemented on some platforms. If its value is 0, it could indicate either no drops or that the statistic is unavailable.

For more information regarding platform differences, please see the pcap_stats() documentation.

list_adapters method

Retrieves the network adapters available for monitoring.

Syntax

def list_adapters() -> None: ...

Remarks

This method populates the adapters collection with a list of network adapters available for monitoring. Each adapter in the collection includes a name and description provided by the network driver.

This method can be used to obtain the name of a network adapter before calling activate to start monitoring it.

Example: // Populate the 'Adapters' collection with the list of available network adapters ipmonitor.ListAdapters(); // Start monitoring the first adapter in the collection ipmonitor.Activate(ipmonitor.Adapters[0].Name);

on_error event

This event fires if an unhandled error occurs during an event.

Syntax

class IPMonitorErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class IPMonitor:
@property
def on_error() -> Callable[[IPMonitorErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[IPMonitorErrorEventParams], None]) -> None: ...

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

on_packet event

Fires when a network packet is captured.

Syntax

class IPMonitorPacketEventParams(object):
  @property
  def time_stamp() -> datetime.datetime: ...

  @property
  def packet_size() -> int: ...

  @property
  def data() -> c_void_p: ...

  @property
  def data_size() -> int: ...

# In class IPMonitor:
@property
def on_packet() -> Callable[[IPMonitorPacketEventParams], None]: ...
@on_packet.setter
def on_packet(event_hook: Callable[[IPMonitorPacketEventParams], None]) -> None: ...

Remarks

This event fires for each packet received from the monitored network adapter. The event will only fire if operation_mode is set to omCapture (0) and the captured packet matches the filter criteria specified in filter and direction. Packets are reported in the order they are received from the network adapter.

The Timestamp parameter contains the time when the packet was received by the network adapter.

The PacketSize parameter contains the total size of the packet as received by the network adapter. This represents the full byte size of the packet, which may be larger than the amount of data captured in the Data parameter.

The Data parameter contains the packet data that was captured. The amount of data captured is controlled by the field of the Adapter that is being monitored.

The DataSize parameter provides the size of the data contained in the Data parameter. This value represents how much of the packet data was actually captured and made available.

Packet Reporting

When active is set to True, the class will report packet information based on the value of the operation_mode property.

on_statistics event

Fires to provide aggregated packet statistics.

Syntax

class IPMonitorStatisticsEventParams(object):
  @property
  def time_stamp() -> datetime.datetime: ...

  @property
  def captured_packets() -> int: ...

  @property
  def captured_bytes() -> int: ...

# In class IPMonitor:
@property
def on_statistics() -> Callable[[IPMonitorStatisticsEventParams], None]: ...
@on_statistics.setter
def on_statistics(event_hook: Callable[[IPMonitorStatisticsEventParams], None]) -> None: ...

Remarks

This event fires to provide aggregated packet statistics collected from the network adapter. The event will only fire if operation_mode is set to omStat (1). Calling do_events while monitoring is active will prompt the class to report packet statistics and fire this event.

The TimeStamp parameter contains the time when the packet statistics were collected.

The CapturedPackets parameter contains the number of packets captured since the last time the event was fired.

The CapturedBytes parameter contains the total byte size of the packets captured since the last time the event was fired.

Packet Reporting

When active is set to True, the class will report packet information based on the value of the operation_mode property.

IPMonitor Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

IPMonitor Config Settings

Base Config Settings

IPMonitor Errors