octopus.capture.network

class octopus.capture.network.NetworkCapture(interface, output_dir, output_filename='traffic.pcap', tcpdump_path=None, capture_command=None)

Bases: AbstractCapture

Network traffic capture class.

This class provides functionality to capture network traffic using tcpdump or a custom command. It manages the capture process, handles permissions, and stores the output in a PCAP file.

interface

The network interface to capture traffic from.

tcpdump_path

Optional path to the tcpdump binary. If not provided, will attempt to locate it.

capture_command

Optional custom capture command as a string. If provided, overrides the default command.

output_path

Path to the output directory or file.

output_filename

Name of the output file.

start_capture_time

Timestamp when capture starts.

end_capture_time

Timestamp when capture ends.

Example

>>> from pathlib import Path
>>> from octopus.capture.network import NetworkCapture
>>> capture = NetworkCapture(interface="eth0", output_dir=Path("/tmp/"))
>>> capture.start_capture()
>>> capture.stop_capture()
>>> print(capture.get_output_file())
'/tmp/traffic.pcap'

__init__(interface, output_dir, output_filename='traffic.pcap', tcpdump_path=None, capture_command=None)

Initializes a NetworkCapture instance.

Parameters:

• interface (str) – The network interface to capture traffic from.

• output_dir (Path) – The directory where the output PCAP file will be stored.

• output_filename (str | None) – The name of the output PCAP file. Defaults to traffic.pcap.

• tcpdump_path (Path | None) – Optional path to the tcpdump binary. If not provided, will attempt to locate it.

• capture_command (str | None) – Optional custom capture command as a string. If provided, overrides the default command.

Raises:

Exception – If the output filename is invalid or other initialization errors occur.

check_user_permissions()

Checks if the user has permission to capture network traffic.

This method attempts to run a test tcpdump command to verify that the current user has the necessary permissions to capture network traffic on the specified interface. If the user lacks permission, an exception is raised with instructions for granting the required rights.

Raises:

Exception – If the user does not have permission to capture network traffic.

Notes

To grant your user’s permission to capture network traffic, use:

• Linux: sudo setcap cap_net_raw,cap_net_admin+eip /usr/sbin/tcpdump

• Mac OS: sudo chown <username>:admin /dev/bpf*

get_output_file()

Returns the path to the output PCAP file.

Returns:

The path to the pcap file where captured network traffic is stored.

Return type:

Path

get_result()

Returns a dictionary with the capture result details.

Returns:

A dictionary containing the capture command, interface, output file name, start and end capture times, and capture duration in milliseconds.

Return type:

dict

start_capture()

Starts the network capture process.

Checks user permissions if needed and launches the capture process using the specified command. Records the start time of the capture. If an exception occurs during process startup, attempts to stop the process, logs the error, and re-raises the exception.

Raises:

Exception – If the capture process fails to start.

stop_capture()

Stops the network capture process.

This method sends a SIGINT signal to the capture process to gracefully terminate it, waits briefly, then attempts to kill the process group and the process itself if it is still running.

The end capture time is recorded.

Raises:

Exception – Any exception raised during the process termination is caught and suppressed.

name: str = 'network'

Name identifier for the capture instance.

class octopus.capture.network.OnDeviceNetworkCapture(device, output_dir, output_filename='traffic.pcap')

Bases: AbstractCapture

Network capture performed directly on an Android device using tcpdump.

This class manages the full lifecycle of an on-device network capture: installing tcpdump, running it via ADB, retrieving the resulting PCAP file, and cleaning up temporary files on the device.

device

The Android device on which the capture is performed.

output_dir

Local directory where the PCAP file will be saved.

output_filename

Name of the output PCAP file.

output_path

Full local path to the output PCAP file.

on_device_output_path

Full path to the PCAP file on the device.

start_capture_time

Timestamp (ms) when the capture started.

end_capture_time

Timestamp (ms) when the capture stopped.

__init__(device, output_dir, output_filename='traffic.pcap')

Initializes an OnDeviceNetworkCapture instance.

Parameters:

• device (AndroidDevice) – The Android device on which capture will run.

• output_dir (Path) – Local directory where the PCAP file will be saved.

• output_filename (str | None) – Name of the output PCAP file. Defaults to traffic.pcap.

get_output_file()

Returns the local path to the captured PCAP file.

Returns:

The Path to the output PCAP file.

get_result()

Returns a summary of the capture session.

Returns:

• file: output filename.

• start_capture_time: capture start timestamp in ms.

• end_capture_time: capture end timestamp in ms.

• capture_duration: total capture duration in ms.

Return type:

A dictionary with the following keys

start_capture()

Starts the on-device network capture.

Ensures the Frida server is running and tcpdump is installed on the device, then launches tcpdump via a non-blocking ADB shell command. ADB (port 5555) and Frida (port 27042) traffic is excluded from the capture to avoid noise. Records the start timestamp.

Raises:

Exception – If the ADB shell command fails to launch, the capture is stopped and the error is logged.

stop_capture()

Stops the on-device network capture and retrieves the PCAP file.

Sends a SIGKILL signal to the tcpdump process on the device via pkill, waits briefly for the process to terminate, then pulls the PCAP file to the local output directory and removes the temporary file from the device. Records the end timestamp.

Raises:

Exception – Errors during process termination or file retrieval are caught and logged individually.

device: AndroidDevice

end_capture_time: float

output_dir: Path

output_filename: str

start_capture_time: float