1# SPDX-FileCopyrightText: 2026 Defensive Lab Agency
2# SPDX-FileContributor: u039b <git@0x39b.fr>
3#
4# SPDX-License-Identifier: GPL-3.0-or-later
5
6import signal
7import threading
8import time
9
10from octopus.android.device import AndroidDeviceUsb, AndroidDeviceTcp
11from octopus.capture.manager import CaptureManager
12
13
[docs]
14def common(device, output_path, no_screen_record, no_network_capture, no_instrumentation, duration, overwrite):
15 """Run the capture session for a given device.
16
17 Sets up signal handlers for graceful shutdown, initializes the
18 :class:`~octopus.capture.manager.CaptureManager`, and runs the
19 capture session for the specified duration or until interrupted.
20
21 Args:
22 device: The Android device instance to capture from.
23 output_path: Path to the directory where output will be saved.
24 no_screen_record: If True, disables screen recording.
25 no_network_capture: If True, disables network traffic capture.
26 no_instrumentation: If True, disables app instrumentation.
27 duration: Duration in seconds to run the capture. If 0 or less,
28 runs until a stop signal is received.
29 overwrite: If True, allows overwriting existing output files.
30 """
31 stop_event = threading.Event()
32
33 def _handle_stop(signum: int, frame) -> None:
34 """Handle OS stop signals by setting the stop event."""
35 stop_event.set()
36
37 # Register signal handlers for graceful shutdown on SIGINT and SIGTERM
38 signal.signal(signal.SIGINT, _handle_stop)
39 signal.signal(signal.SIGTERM, _handle_stop)
40
41 capture_manager = CaptureManager(
42 device, output_path, no_screen_record, no_network_capture, no_instrumentation, overwrite
43 )
44
45 # Abort early if the capture manager failed to initialize
46 if not capture_manager.ready:
47 return
48
49 capture_manager.start()
50
51 if duration > 0:
52 # Run for the specified duration, then signal stop
53 time.sleep(duration)
54 stop_event.set()
55 else:
56 # Wait indefinitely until a stop signal is received
57 stop_event.wait()
58
59 capture_manager.stop()
60
61
[docs]
62def usb_mode(
63 adb_host,
64 adb_port,
65 device_id,
66 output_path,
67 no_screen_record,
68 no_network_capture,
69 no_instrumentation,
70 duration,
71 overwrite,
72):
73 """Start a capture session using a USB-connected Android device.
74
75 Creates an :class:`~octopus.android.device.AndroidDeviceUsb` instance
76 and delegates to :func:`common` to run the capture session.
77
78 Args:
79 adb_host: Hostname or IP address of the ADB server.
80 adb_port: Port number of the ADB server.
81 device_id: The serial ID of the USB-connected Android device.
82 output_path: Path to the directory where output will be saved.
83 no_screen_record: If True, disables screen recording.
84 no_network_capture: If True, disables network traffic capture.
85 no_instrumentation: If True, disables app instrumentation.
86 duration: Duration in seconds to run the capture. If 0 or less,
87 runs until a stop signal is received.
88 overwrite: If True, allows overwriting existing output files.
89 """
90 device = AndroidDeviceUsb(device_id, adb_host, adb_port)
91 common(device, output_path, no_screen_record, no_network_capture, no_instrumentation, duration, overwrite)
92
93
[docs]
94def tcp_mode(
95 adb_host,
96 adb_port,
97 device_host,
98 device_port,
99 output_path,
100 no_screen_record,
101 no_network_capture,
102 no_instrumentation,
103 duration,
104 overwrite,
105):
106 """Start a capture session using a TCP-connected Android device.
107
108 Creates an :class:`~octopus.android.device.AndroidDeviceTcp` instance
109 and delegates to :func:`common` to run the capture session.
110
111 Args:
112 adb_host: Hostname or IP address of the ADB server.
113 adb_port: Port number of the ADB server.
114 device_host: Hostname or IP address of the Android device.
115 device_port: Port number used to connect to the Android device.
116 output_path: Path to the directory where output will be saved.
117 no_screen_record: If True, disables screen recording.
118 no_network_capture: If True, disables network traffic capture.
119 no_instrumentation: If True, disables app instrumentation.
120 duration: Duration in seconds to run the capture. If 0 or less,
121 runs until a stop signal is received.
122 overwrite: If True, allows overwriting existing output files.
123 """
124 device = AndroidDeviceTcp(device_host, device_port, adb_host, adb_port)
125 common(device, output_path, no_screen_record, no_network_capture, no_instrumentation, duration, overwrite)