python-rayhunter 2025.3.1__py3-none-any.whl

python_rayhunter-2025.3.1.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: python-rayhunter
+Version: 2025.3.1
+Summary: Unofficial Python bindings for EFF's Rayhunter API
+Author-email: UltraSunshine <python-rayhunter.hedge098@passfwd.com>
+Maintainer-email: UltraSunshine <python-rayhunter.hedge098@passfwd.com>
+Project-URL: Homepage, https://github.com/UltraSunshine/python-rayhunter
+Project-URL: Documentation, https://python-rayhunter.readthedocs.io/en/latest/index.html
+Project-URL: Repository, https://github.com/UltraSunshine/python-rayhunter.git
+Project-URL: Bug Tracker, https://github.com/UltraSunshine/python-rayhunter/issues
+Keywords: rayhunter,lte,orbic,qualcomm,pcap,qmdl
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.2
+Dynamic: license-file
+
+# python-rayhunter
+
+Unofficial Python bindings for EFF's [Rayhunter](https://github.com/EFForg/rayhunter) API.
+
+> **Note:** This project is not affiliated with the EFF or the Rayhunter project.
+
+
+## Documentation
+
+Full documentation can be found on [Read The Docs](https://python-rayhunter.readthedocs.io/en/latest/index.html). Please read them, I worked hard on them.
+
+## Requirements
+
+- Python >= 3.11
+- [requests](https://pypi.org/project/requests/) >= 2.32.2
+
+## Installation
+
+```bash
+pip install python-rayhunter
+```
+
+## Quick Start
+
+```python
+from rayhunter import RayhunterApi
+
+api = RayhunterApi(hostname="192.168.1.1", port=8080)
+```
+
+## Usage
+
+### Check recording status
+
+```python
+if api.active_recording:
+    print("A recording is currently in progress")
+```
+
+### Fetch the QMDL manifest
+
+The manifest lists all capture files available on the device, plus the active capture (if any).
+
+```python
+manifest = api.get_manifest()
+
+for entry in manifest.entries:
+    print(f"{entry.name} — started {entry.start_time}, size {entry.qmdl_size_bytes} bytes")
+
+if manifest.current_entry:
+    print(f"Active capture: {manifest.current_entry.name}")
+```
+
+### Download capture files
+
+Use the filenames from the manifest to download files.
+
+```python
+# Raw QMDL capture data
+qmdl_data = api.get_qmdl_file("capture.qmdl")
+
+# PCAP file (dynamically generated from QMDL by the Rayhunter binary)
+pcap_data = api.get_pcap_file("capture.qmdl")
+
+# Analysis report
+report_data = api.get_analysis_report_file("capture.qmdl")
+```
+
+### Control recordings
+
+```python
+# Start a new recording (stops any active recording first)
+api.start_recording()
+
+# Stop the current recording
+api.stop_recording()
+```
+
+### System statistics
+
+```python
+stats = api.system_stats()
+
+disk = stats.disk_stats
+print(f"Partition:  {disk.partition} ({disk.mounted_on})")
+print(f"Disk usage: {disk.used_size}/{disk.total_size} bytes ({disk.used_percent}% used)")
+
+mem = stats.memory_stats
+print(f"Memory:     {mem.used}/{mem.total} bytes used, {mem.free} bytes free")
+```
+
+## API Reference
+
+### `RayhunterApi(hostname, port)`
+
+The main client for interacting with the Rayhunter API.
+
+| Method | Returns | Description |
+|---|---|---|
+| `active_recording` | `bool` | `True` if a recording is currently in progress |
+| `get_manifest()` | `QmdlManifest` | Fetch the QMDL manifest from the device |
+| `get_qmdl_file(filename)` | `bytes` | Download a raw QMDL capture file |
+| `get_pcap_file(filename)` | `bytes` | Download a PCAP file (generated on demand) |
+| `get_analysis_report_file(filename)` | `bytes` | Download the analysis report for a capture |
+| `start_recording()` | — | Start a new recording |
+| `stop_recording()` | — | Stop the active recording |
+| `system_stats()` | `SystemStats` | Fetch disk and memory utilisation stats |
+
+### `QmdlManifest`
+
+| Attribute | Type | Description |
+|---|---|---|
+| `entries` | `List[QmdlManifestEntry]` | All finalised capture files on the device |
+| `current_entry` | `Optional[QmdlManifestEntry]` | The active capture, or `None` |
+
+### `QmdlManifestEntry`
+
+| Attribute | Type | Description |
+|---|---|---|
+| `name` | `str` | Capture file name |
+| `start_time` | `str` | Timestamp when the capture started |
+| `last_message_time` | `str` | Timestamp of the last captured message |
+| `qmdl_size_bytes` | `int` | Size of the QMDL file in bytes |
+| `analysis_size_bytes` | `int` | Size of the associated analysis file in bytes |
+
+### `SystemStats`
+
+| Attribute | Type | Description |
+|---|---|---|
+| `disk_stats` | `DiskStats` | Disk usage information |
+| `memory_stats` | `MemoryStats` | Memory usage information |
+
+### `DiskStats`
+
+| Attribute | Type | Description |
+|---|---|---|
+| `partition` | `str` | Partition Rayhunter is mounted on (e.g. `ubi0:usrfs`) |
+| `total_size` | `int` | Total disk size in bytes |
+| `used_size` | `int` | Used disk space in bytes |
+| `available_size` | `int` | Available disk space in bytes |
+| `used_percent` | `int` | Percentage of disk space in use |
+| `mounted_on` | `str` | Mount point (e.g. `/data`) |
+
+### `MemoryStats`
+
+| Attribute | Type | Description |
+|---|---|---|
+| `total` | `int` | Total memory in bytes |
+| `used` | `int` | Used memory in bytes |
+| `free` | `int` | Free memory in bytes |
+
+## License
+
+Since "do what you'd like and don't blame me," isn't necessarily legally binding, this repository uses the [MIT LICENSE](LICENSE).

python_rayhunter-2025.3.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+python_rayhunter-2025.3.1.dist-info/licenses/LICENSE,sha256=4LHwVtwZNgbaRLzi-IQFBGpI-BwfCzPE-O7uJQWtALE,1061
+rayhunter/__init__.py,sha256=HF1EAkB8DJO-TarR9n4s5lLyPu8_o-r0d7EEXNRJpuI,64
+rayhunter/api.py,sha256=EJW3HR_2wRns86IIUKEI-h3BlvJMNyTojl3UsxJuliI,4618
+rayhunter/manifest.py,sha256=V_U7-mdcaDRxGvysLQDdkylOl85hwmURbKXYTVST0aU,1575
+rayhunter/system_stats.py,sha256=DXc27bJaBceH74FjqS2-lXLov3yBUs8eSsEfB9bXboQ,3081
+python_rayhunter-2025.3.1.dist-info/METADATA,sha256=fmFj2lYrK-oxPTjRQ1TEYKTTTfMFTABz1SZQQmFIuYQ,5255
+python_rayhunter-2025.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_rayhunter-2025.3.1.dist-info/top_level.txt,sha256=GGniULEc2vexd1qBwVhxi7nUx9ONWigBRt8DJ6vFddY,10
+python_rayhunter-2025.3.1.dist-info/RECORD,,

python_rayhunter-2025.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_rayhunter-2025.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_rayhunter-2025.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+rayhunter

rayhunter/__init__.py

@@ -0,0 +1,6 @@
+from .api import RayhunterApi
+
+
+__all__ = [
+    "RayHunterApi"
+]

rayhunter/api.py

@@ -0,0 +1,108 @@
+import io
+import logging
+import requests
+import urllib.parse
+
+from .manifest import QmdlManifest
+from .system_stats import SystemStats
+
+
+class RayhunterApi:
+
+    @property
+    def active_recording(self) -> bool:
+        """
+        Check the manifest file to determine if there's a recording in progress.
+        :returns: True if there's a "current_entry" in the manifest, else False
+        """
+        manifest = self.get_manifest()
+        return manifest.current_entry is not None
+
+    def __init__(self, hostname: str, port: int):
+        self._url = f"http://{hostname}:{port}/"
+
+    def _get_file_content(self, api_endpoint: str) -> bytes:
+        """
+        Stream a file from the given API endpoint into memory. 
+        :param api_endpoint: The endpoint from which to retrieve a file
+        :returns: The contents of the file (bytes)
+        """
+        file_content = io.BytesIO()
+        file_url = urllib.parse.urljoin(self._url, api_endpoint)
+        logging.info(f"Downloading file from: {file_url}")
+        response = requests.get(file_url, stream=True)
+        response.raise_for_status()
+        for chunk in response.iter_content(chunk_size=4096):
+            file_content.write(chunk)
+        file_content.seek(0)
+        return file_content.read()
+
+    def get_manifest(self) -> QmdlManifest:
+        """
+        Fetch a copy of the QMDL manifest, used to track the names of previous and active recordings.
+        :returns: An instance of `QmdlManifest` populated from the target device
+        """
+        manifest_url = urllib.parse.urljoin(self._url, "/api/qmdl-manifest")
+        logging.info(f"Fetching manifest from: {manifest_url}")
+        response = requests.get(manifest_url)
+        response.raise_for_status()
+        return QmdlManifest.from_dict(response.json())
+    
+    def get_analysis_report_file(self, filename: str) -> bytes:
+        """
+        Fetch a copy of the analysis report for a given capture. Use `get_manifest` to identify capture names.
+        :param filename: The capture file name
+        :returns: The contents of the analysis report file (bytes)
+        """
+        logging.info(f"Fetching analysis report for capture: {filename}")
+        api_endpoint = f"/api/analysis-report/{filename}"
+        return self._get_file_content(api_endpoint)
+    
+    def get_pcap_file(self, filename: str) -> bytes:
+        """
+        Fetch a copy of the pcap file for a given capture. PCAP is dynamically generated from QMDL by the Rayhunter binary when this API is called.
+        :param filename: The capture file name (found in manifest)
+        :returns: The contents of the pcap file (bytes)
+        """
+        logging.info(f"Fetching PCAP file for capture: {filename}")
+        api_endpoint = f"/api/pcap/{filename}"
+        return self._get_file_content(api_endpoint)
+
+    def get_qmdl_file(self, filename: str) -> bytes:
+        """
+        Fetch a copy of the given QMDL file. Use `get_manifest` to identify QMDL capture names.
+        :param filenae: The QMDL file name (found in manifest)
+        :returns: The contents of the QMDL file (bytes)
+        """
+        logging.info(f"Fetching QDML file for capture: {filename}")
+        api_endpoint = f"/api/qmdl/{filename}"
+        return self._get_file_content(api_endpoint)
+    
+    def start_recording(self):
+        """
+        Start a new recording. Stops the active recording and starts a new one if this device is already recording.
+        """
+        start_recording_url = urllib.parse.urljoin(self._url, "/api/start-recording")
+        logging.info(f"Starting recording with POST request to: {start_recording_url}")
+        response = requests.post(start_recording_url)
+        response.raise_for_status()
+    
+    def stop_recording(self):
+        """
+        Stop an active recording. Throws a 500 error if there is no active recording.
+        """
+        stop_recording_url = urllib.parse.urljoin(self._url, "/api/stop-recording")
+        logging.info(f"Stopping recording with POST request to: {stop_recording_url}")
+        response = requests.post(stop_recording_url)
+        response.raise_for_status()
+
+    def system_stats(self):
+        """
+        Fetch disk and memory utilization stats from the API.
+        :returns: An instance of `SystemStats` populated from the target device.
+        """
+        system_stats_url = urllib.parse.urljoin(self._url, "/api/system-stats")
+        logging.info(f"Fetching system stats from: {system_stats_url}")
+        response = requests.get(system_stats_url)
+        response.raise_for_status()
+        return SystemStats.from_dict(response.json())

rayhunter/manifest.py

@@ -0,0 +1,47 @@
+import json
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class QmdlManifestEntry:
+
+    """Metadata for a single QMDL capture file.
+
+    Attributes:
+        name (str): The name of the QMDL file.
+        start_time (str): The start time of this capture file.
+        last_message_time (str): The timestamp of the last message captured in this file.
+        qmdl_size_bytes (int): The total size in bytes of this QMDL file.
+        analysis_size_bytes (int): The total size in bytes of the analysis file associated with this QMDL capture file.
+    
+    """
+
+    name: str
+    start_time: str
+    last_message_time: str
+    qmdl_size_bytes: int
+    analysis_size_bytes: int
+
+
+@dataclass
+class QmdlManifest:
+
+    """A collection of metadata for all QMDL capture files available on this system.
+
+    Attributes:
+        entries (List[QmdlManifestEntry]): A list of metadata for all finalized QMDL capture files available on this system.
+        current_entry (Optional[QmdlManifestEntry]): An optional value containing information on the active capture, or `None` if there is no active capture.
+    
+    """
+
+    entries: List[QmdlManifestEntry]
+    current_entry: Optional[QmdlManifestEntry]
+
+    @staticmethod
+    def from_dict(qmdl_manifest: dict):
+        qmdl_manifest["entries"] = [QmdlManifestEntry(**x) for x in qmdl_manifest["entries"]]
+        if qmdl_manifest["current_entry"] is not None:
+            qmdl_manifest["current_entry"] = QmdlManifestEntry(**qmdl_manifest["current_entry"])
+        return QmdlManifest(**qmdl_manifest)

rayhunter/system_stats.py

@@ -0,0 +1,91 @@
+from dataclasses import dataclass
+
+
+def _size_str_to_int(size: str) -> int:
+    """
+    Convert string notation of megabytes (e.g. 214.7M) to an integer value representing bytes (e.g. 225129267).
+    :param size: String notation, megabytes (e.g. 214.7M)
+    :returns: An integer value representing bytes (e.g. 225129267)
+    """
+    if size[-1] != "M":
+        raise ValueError(f"Unsupported size suffix: {size[-1]} ({size})")
+    return int(float(size.rstrip("M")) * 1048576)
+
+
+@dataclass
+class DiskStats:
+
+    """Disk usage statistics and information about the underlying filesystem, obtained from the Rayhunter API.
+
+    Size and percentage values are converted from string (e.g. 214.7M) to bytes (e.g. 225129267) for programmatic ease of use.
+
+    Attributes:
+        partition (str): The partition Rayhunter is mounted on (e.g. ubi0:usrfs).
+        total_size (int): Total size of the disk in bytes (e.g. 225129267).
+        used_size (int): The amount of disk space currently in use in bytes (e.g. 18350080).
+        available_size (int): The amount of disk space currently available in bytes (e.g. 206884044).
+        used_percent (int): The percentage of disk space currently in use (e.g. 8).
+        mounted_on (str): Rayhunter's mount point (e.g. /data).
+
+    """
+
+    partition: str
+    total_size: int
+    used_size: int
+    available_size: int
+    used_percent: int
+    mounted_on: str
+
+    @staticmethod
+    def from_dict(disk_stats: dict):
+        for size_key in ["total_size", "used_size", "available_size"]:
+            disk_stats[size_key] = _size_str_to_int(disk_stats[size_key])
+        disk_stats["used_percent"] = int(disk_stats["used_percent"].rstrip("%"))
+        return DiskStats(**disk_stats)
+
+
+@dataclass
+class MemoryStats:
+
+    """Memory usage statistics, obtained from the Rayhunter API.
+
+    Size and percentage values are converted from string (e.g. 159.9) to bytes (e.g. 167667302) for programmatic ease of use.
+
+    Attributes:
+        total (int): Total size of memory in bytes (e.g. 167667302).
+        used (int): The amount of memory currently in use in bytes (e.g. 149212364).
+        free (int): The amount of memory currently available in bytes (e.g. 18454937)
+
+    """
+
+    total: int
+    used: int
+    free: int
+
+    @staticmethod
+    def from_dict(memory_stats):
+        for key in ["total", "used", "free"]:
+            memory_stats[key] = _size_str_to_int(memory_stats[key])
+        return MemoryStats(**memory_stats)
+    
+
+@dataclass
+class SystemStats:
+
+    """Disk and memory utilization statistics for the underlying system, pulled from the Rayhunter API.
+    
+    Attributes:
+        disk_stats (DiskStats): Information on the underlying disk
+        memory_stats (MemoryStats): Information on system memory utilization
+
+    """
+
+    disk_stats: DiskStats
+    memory_stats: MemoryStats
+
+    @staticmethod
+    def from_dict(system_stats: dict):
+        return SystemStats(
+            disk_stats=DiskStats.from_dict(system_stats["disk_stats"]),
+            memory_stats=MemoryStats.from_dict(system_stats["memory_stats"])
+        )