Getting Started with IPMonitor

Introduction

The IPMonitor component allows applications to monitor network packets on Windows, Linux, and macOS using libpcap or the NetFilter driver (Windows). It supports capturing individual packets or aggregating packet statistics.

Platform Setup

The IPMonitor component requires a libpcap-compatible library to be installed on the system.

Windows

On Windows, there are two options. First, the component may use the NetFilter driver that is included in the /drivers folder of PCAP Filter's installation directory. This requires first using the NetFilter component's Install method to install the netfilter.cab driver.

After doing so, navigate to the /PcapLibs directory and deploy the included packet.dll and wpcap.dll either next to your EXE, or a system directory (e.g., C:\Windows\System32).

Finally, to ensure the NetFilter driver is properly initialized in the IPMonitor component, please set the NetFilterGUID config to the GUID set when calling the Install method in the previous step.

As an alternative to using the included NetFilter driver, the component may use npcap on Windows 10 and later. On Windows 7 and 8, either npcap or WinPcap may be used. In this case, it should also be ensured that packet.dll and wpcap.dll (included with the npcap or WinPcap installation) are deployed either next to your EXE, or a system directory.

Linux

On Linux, the component will automatically attempt to locate libpcap if it is installed. The following commands may be used to install libpcap:

sudo apt install libpcap0.8

or...

yum install libpcap

After doing so, some additional system configuration is required to capture network traffic. In most cases, the superuser or root can capture network traffic without any extra steps. The instructions below may be applicable to limited users who want to use an application without elevated rights.

The process that attempts to capture the traffic must have cap_net_raw and cap_net_admin capabilities. These capabilities are added by the operator or setup script using a command similar to:

sudo setcap cap_net_raw,cap_net_admin=eip {path-to-process}

Note that the setcap tool replaces the capabilities, so if the process must have other capabilities too, all must be included in the above command.

macOS

On macOS, libpcap must be present in the system. It can be installed from source by downloading the source code from the TCPDump site and building it locally. Alternatively, libpcap can also be installed via the Homebrew package manager on macOS:

brew install libpcap

After doing so, a good bit of additional system configuration is required in order to capture network traffic. There are several devices related to packet capturing, which can be listed by running the command:

ls -l /dev/bpf*

The permissions of those devices need to be adjusted. The common approach is to create a dedicated group that will have read-write access to those devices, and add a user to this group. For example, where 'your_group' is the name of the group to which the user account belongs to:

sudo chgrp your_group /dev/bpf* sudo chmod 660 /dev/bpf*

If necessary, you can create a dedicated group for BPF monitoring, add a user to this group, then use the group as shown above. These changes should be done on every system start, so it may be necessary to configure a small launch daemon which will execute the above lines. For example:

• Write the above or similar lines to a file (e.g., 'set_bpf_perms.sh').
• Make the script executable by using chmod:

chmod +x /path/to/set_bpf_perms.sh

• Create a launch daemon plist file (e.g., com.user.bpf.plist) in /Library/LaunchDaemons:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.user.bpf</string> <key>ProgramArguments</key> <array> <string>/path/to/set_bpf_perms.sh</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> </dict> </plist> </xml>

• Load the daemon:

sudo launchctl load /Library/LaunchDaemons/com.user.bpf.plist

Additional information on BPF devices and libpcap can be found in the libpcap files.

Adapter Discovery

Before the component can begin monitoring traffic, users should obtain a list of network interfaces on their machine that are available for monitoring. To obtain a list of adapters available on your machine, you can call the ListAdapters method to populate the Adapters collection. For example:

// 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}"); }

After listing the network adapters, the adapter name's from above may be used with the Activate method to capture packets across that specific adapter.

Packet Filters

Before monitoring a network adapter, filters can be applied to capture only packets matching certain criteria.

First, the Direction property can be used to specify whether to capture incoming packets, outgoing packets, or both. Possible values for this property are:

• PACKET_DIRECTION_OUTGOING (0) - Default
• PACKET_DIRECTION_INCOMING (1)
• PACKET_DIRECTION_ANY (2)

Additionally, the Filter property may be set to a filter string (using the standard pcap-filter(7) syntax) to filter incoming and/or outgoing packets. For example, to capture all TCP packets to and from port 80, you can do:

ipmonitor.Direction = 0x02; ipmonitor.Filter = "src host 192.168.1.1 and tcp port 80"

Operation Modes

The component can either capture packets or capture aggregated packet statistics. This is determined by the value of the OperationMode property.

Capture Mode

This capture mode reports individual packets via the Packet event. For example:

// Capture individual packet information ipmonitor.OperationMode = IPMonitorOperationModes.omCapture; ipmonitor.OnPacket += (o, e) => { Console.WriteLine($"Packet captured at {e.TimeStamp}"); };

Statistics Mode

This capture mode reports aggregated statistics via the Statistics event.

// Report aggregated packet statistics ipmonitor.OperationMOde = IPMonitorOperationModes.omStat; ipmonitor.OnStatistics += (o, e) => { Console.WriteLine($"Packets captured: {e.CapturedPackets}"); };

Monitoring an Adapter

After listing the adapters, configuring the filters, and setting the operation mode, you can start to monitor a network adapter by using the Activate method. This method takes the name of an adapter as returned by the ListAdapters method. For example:

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

After activating the component for a particular adapter, you must then call DoEvents periodically during monitoring, though the exact behavior depends on the value of the OperationMode property.

In capture mode (i.e., omCapture), calling this method while monitoring is active will prompt the component to process any packets captured since the last call, and fire the Packet event for each one. If there are no new packets to report, the method will wait for a duration specified by the PacketTimeout field of the adapter that is being monitored before returning.

In statistics mode (i.e., omStat), calling this method will instead tell the component to collect packet statistics since the last call, and fire the Statistics event with the aggregated data.

To stop monitoring, call the Deactivate method. For example, to monitor packets in capture mode for 30 minutes, this could look like:

ipmonitor.OperationMode = IPMonitorOperationModes.omCapture; ipmonitor.OnPacket += (o, e) => { Console.WriteLine($"Packet captured at {e.TimeStamp}"); };
ipmonitor.ListAdapters(); string adapter = ipmonitor.Adapters[0].Name; ipmonitor.Activate(adapter);
DateTime end = DateTime.Now.AddMinutes(30); while (DateTime.Now < end) { ipmonitor.DoEvents(); }
ipmonitor.Deactivate();

Capture Statistics

Aside from setting OperationMode to omStat, you can instead use the GetStatistics method to retrieve cumulative statistics since the component has been activated for a specific adapter. For example:

long received = 0; long dropped = 0; long adapterDropped = 0; ipmonitor.GetStatistics(ref received, ref dropped, ref adapterDropped);

Above, the Recieved parameter provides the number of packets 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 BufferSize field of the specific adapter being monitored is too small to keep all of the data, or because DoEvents is called too infrequently.

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

The GetStatistics 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 passed parameters to differ depending on the platform.

• Recieved: On some platforms, this count may include all packets, regardless of whether they match the filter criteria set using the Filter property.
• 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.