Add files via upload

Author: DefinetlyNotAI

CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 4.0)
+project(example/pyCTools C)
+
+set(CMAKE_C_STANDARD 11)
+
+add_library(PyCTools SHARED
+        src/hRng.c
+        src/processInspect.c)

README.md

@@ -0,0 +1,71 @@
+# Project Overview
+
+This project provides a cross-language toolkit for Windows process inspection and hardware random number generation, with both Python and C components. It includes:
+
+- **Python library (`pyCTools`)**: Easy-to-use wrappers for native DLLs to access process metrics and hardware RNG.
+- **C source files**: Implement the DLLs for process inspection and hardware RNG.
+- **Example Python scripts**: Demonstrate usage of the library.
+- **PowerShell build helper**: Automates DLL compilation for x86/x64.
+
+## Directory Structure
+
+```
+example/
+  pyCTools/
+    hwrng.py           # Python wrapper for hardware RNG DLL
+    processInspect.py  # Python wrapper for process inspection DLL
+  hwrng_example.py     # Example: hardware RNG usage
+  process_inspect_example.py # Example: process metrics usage
+src/
+  hRng.c               # C source for hardware RNG DLL
+  processInspect.c     # C source for process inspection DLL
+tool/
+  compilerHelper.ps1   # PowerShell script to build DLLs for x86/x64
+dist/
+  x64/                 # Compiled DLLs for 64-bit
+  x86/                 # Compiled DLLs for 32-bit
+```
+
+## Building the DLLs
+
+1. Open PowerShell and run `tool/compilerHelper.ps1`.
+2. Select which `.c` files to compile.
+3. The script will build both x86 and x64 DLLs and place them in `dist/x86` and `dist/x64`.
+
+## Using the Python Library
+
+- Place the `dist/` folder as a sibling to your Python scripts or as described in the wrappers.
+- Import and use `pyCTools.hwrng` or `pyCTools.processInspect` as shown in the examples.
+
+## Example Usage
+
+**Hardware RNG:**
+```python
+from pyCTools.hwrng import get_hardware_random_bytes
+rb = get_hardware_random_bytes(16)
+print(rb.hex())
+```
+
+**Process Inspection:**
+```python
+from pyCTools.processInspect import ProcessMetrics
+metrics = ProcessMetrics()
+pid = 1234  # Target PID
+flags = ProcessMetrics.METRIC_WORKING_SET | ProcessMetrics.METRIC_CPU_USAGE
+snapshot = metrics.get_snapshot(pid, flags)
+print(snapshot)
+```
+
+## DLL Discovery
+
+The Python wrappers automatically search for the correct DLL in:
+- `./dist/{arch}/<dll>`
+- `../dist/{arch}/<dll>`
+- `../../dist/{arch}/<dll>`
+
+where `{arch}` is `x64` or `x86` depending on your Python interpreter.
+
+## License
+
+MIT or specify your license here.
+

example/hwrng_example.py

@@ -0,0 +1,9 @@
+# Optional CLI usage
+from pyCTools.hwrng import get_hardware_random_bytes
+
+if __name__ == '__main__':
+    try:
+        rb = get_hardware_random_bytes(256)
+        print("Random bytes:", rb.hex())
+    except Exception as e:
+        print("Error:", e)

example/process_inspect_example.py

@@ -0,0 +1,39 @@
+import os
+
+from pyCTools.processInspect import ProcessMetrics
+
+metrics = ProcessMetrics()
+pid = os.getpid()  # Replace with your actual target PID
+flags = (
+        ProcessMetrics.METRIC_WORKING_SET |
+        ProcessMetrics.METRIC_PRIVATE_BYTES |
+        ProcessMetrics.METRIC_CPU_USAGE |
+        ProcessMetrics.METRIC_IO |
+        ProcessMetrics.METRIC_THREADS |
+        ProcessMetrics.METRIC_HANDLES
+)
+
+# Start session
+if metrics.start_session(pid, flags):
+    # Simulate some work to collect metrics
+    # Time await without work
+    import time
+    time.sleep(5)
+
+    for i in range(3):
+        # Simulate resource intensive work
+        _ = [x ** 2 for x in range(10**6)]
+
+    # End session and get metrics delta
+    result = metrics.end_session(pid, flags)
+    print("Delta Metrics:", result)
+else:
+    print("Failed to start metrics session.")
+
+# Or get a snapshot instead
+try:
+    # Some values will be unreliable if it's a snapshot, example CPU usage
+    snapshot = metrics.get_snapshot(pid, flags)
+    print("Instant Snapshot:", snapshot)
+except RuntimeError as e:
+    print("Error:", str(e))

example/pyCTools/__pycache__/hwrng.cpython-313.pyc

@@ -0,0 +1,80 @@
+"""
+hwrng_example.py
+
+Hardware Random Number Generator (RDRAND) interface for Python using ctypes and a custom DLL.
+"""
+
+import ctypes
+import os
+import platform
+
+__all__ = ["get_hardware_random_bytes", "HardwareRNGError"]
+
+
+class HardwareRNGError(RuntimeError):
+    """Raised when hardware RNG fails or DLL cannot be loaded."""
+    pass
+
+
+def _load_rng_function():
+    arch = 'x64' if platform.architecture()[0] == '64bit' else 'x86'
+    dll_name = f'hRng_{arch}.dll'
+    base_dir = os.path.dirname(__file__)
+    possible_dist_paths = [
+        os.path.join(base_dir, 'dist', arch, dll_name),
+        os.path.join(base_dir, '..', 'dist', arch, dll_name),
+        os.path.join(base_dir, '..', '..', 'dist', arch, dll_name),
+    ]
+
+    dll_path = None
+    for path in possible_dist_paths:
+        abs_path = os.path.abspath(path)
+        if os.path.exists(abs_path):
+            dll_path = abs_path
+            break
+
+    if dll_path is None:
+        dll_path = os.path.abspath(possible_dist_paths[0])  # fallback for error message
+
+    dll = ctypes.CDLL(dll_path)
+
+    # Setup and return the function
+    func = dll.read_hwrng
+    func.argtypes = [ctypes.POINTER(ctypes.c_ubyte), ctypes.c_int]
+    func.restype = ctypes.c_int
+    return func
+
+
+# Load the function only once
+_read_hwrng = _load_rng_function()
+
+
+def get_hardware_random_bytes(size: int) -> bytes:
+    """
+        Retrieve cryptographically secure random bytes from the hardware RNG via a custom DLL.
+
+        Args:
+            size (int): The number of random bytes to generate. Must be a positive integer.
+
+        Returns:
+            bytes: A bytes object containing `size` random bytes from the hardware RNG.
+
+        Raises:
+            ValueError: If `size` is not a positive integer.
+            HardwareRNGError: If the hardware RNG fails or is not supported on this system.
+
+        Example:
+            >>> random_bytes = get_hardware_random_bytes(16)
+            >>> len(random_bytes)
+            16
+    """
+    if size <= 0:
+        raise ValueError("Size must be a positive integer")
+
+    buffer = (ctypes.c_ubyte * size)()
+    success = _read_hwrng(buffer, size)
+
+    if not success:
+        raise HardwareRNGError("Hardware RNG failed or RDRAND not supported.")
+
+    return bytes(buffer)

example/pyCTools/__pycache__/processInspect.cpython-313.pyc

@@ -0,0 +1,153 @@
+import ctypes
+import os
+import json
+import platform
+from ctypes import c_char_p, c_size_t, c_ulong, create_string_buffer
+
+
+class ProcessMetrics:
+    """
+    Wrapper class for interfacing with the native `processInspect` DLL that collects
+    various system and process metrics on Windows. Supports querying working set,
+    private bytes, pagefile usage, handle count, thread count, CPU usage, IO stats,
+    and network stats.
+
+    The correct DLL is selected automatically based on the platform architecture (x64 or x86),
+    searching multiple possible relative paths.
+
+    Methods allow starting a metric collection session, ending it (to retrieve final metrics),
+    and getting an instant snapshot of metrics. All metric results are returned as parsed JSON dicts.
+
+    Attributes:
+        METRIC_WORKING_SET (int): Flag for working set memory usage.
+        METRIC_PRIVATE_BYTES (int): Flag for private bytes memory usage.
+        METRIC_PAGEFILE (int): Flag for pagefile usage.
+        METRIC_HANDLES (int): Flag for handle count.
+        METRIC_THREADS (int): Flag for thread count.
+        METRIC_CPU_USAGE (int): Flag for CPU usage percentage.
+        METRIC_IO (int): Flag for I/O statistics.
+        METRIC_NET (int): Flag for network statistics.
+
+    Raises:
+        RuntimeError: If the DLL is not found or if metric collection fails.
+    """
+
+    METRIC_WORKING_SET = 0x01
+    METRIC_PRIVATE_BYTES = 0x02
+    METRIC_PAGEFILE = 0x04
+    METRIC_HANDLES = 0x08
+    METRIC_THREADS = 0x10
+    METRIC_CPU_USAGE = 0x20
+    METRIC_IO = 0x40
+    METRIC_NET = 0x80
+
+    def __init__(self):
+        """
+        Initialize ProcessMetrics instance by loading the appropriate DLL
+        for the current platform architecture.
+
+        Searches for DLL in relative paths:
+            - ./dist/{arch}/processInspect_{arch}.dll
+            - ../dist/{arch}/processInspect_{arch}.dll
+            - ../../dist/{arch}/processInspect_{arch}.dll
+
+        Raises:
+            FileNotFoundError: If the DLL cannot be found in any of the expected locations.
+        """
+        arch = 'x64' if platform.architecture()[0] == '64bit' else 'x86'
+        dll_name = f'processInspect_{arch}.dll'
+        base_dir = os.path.dirname(__file__)
+        possible_dist_paths = [
+            os.path.join(base_dir, 'dist', arch, dll_name),
+            os.path.join(base_dir, '..', 'dist', arch, dll_name),
+            os.path.join(base_dir, '..', '..', 'dist', arch, dll_name),
+        ]
+
+        dll_path = None
+        for path in possible_dist_paths:
+            abs_path = os.path.abspath(path)
+            if os.path.exists(abs_path):
+                dll_path = abs_path
+                break
+
+        if dll_path is None:
+            # Could not find DLL, raise an informative error
+            raise FileNotFoundError(
+                f"Could not find {dll_name} DLL in any of the expected locations:\n" +
+                "\n".join(os.path.abspath(p) for p in possible_dist_paths)
+            )
+
+        # Load the DLL using ctypes
+        self._dll = ctypes.CDLL(dll_path)
+
+        # Define argument and return types of DLL functions for type safety
+        self._dll.start_metrics_collection.argtypes = [c_ulong, c_ulong]
+        self._dll.start_metrics_collection.restype = ctypes.c_int
+
+        self._dll.end_metrics_collection.argtypes = [c_ulong, c_ulong, c_char_p, c_size_t]
+        self._dll.end_metrics_collection.restype = ctypes.c_int
+
+        self._dll.get_metrics_json.argtypes = [c_ulong, c_ulong, c_char_p, c_size_t]
+        self._dll.get_metrics_json.restype = ctypes.c_int
+
+    @staticmethod
+    def _json_call(func, pid: int, metrics: int) -> dict:
+        """
+        Internal helper method to call a DLL function that returns JSON data
+        in a buffer, parse it, and return as a Python dictionary.
+
+        Args:
+            func (callable): DLL function to call, which fills a buffer with JSON.
+            pid (int): Process ID to query.
+            metrics (int): Bitmask of metrics flags to request.
+
+        Returns:
+            dict: Parsed JSON metrics.
+
+        Raises:
+            RuntimeError: If the DLL function call returns failure.
+        """
+        buf = create_string_buffer(4096)  # buffer size fixed to 4 KB
+        success = func(pid, metrics, buf, ctypes.sizeof(buf))
+        if not success:
+            raise RuntimeError(f"Metric collection failed for PID {pid}")
+        return json.loads(buf.value.decode('utf-8'))
+
+    def start_session(self, pid: int, metrics: int) -> bool:
+        """
+        Start a metrics collection session for a specific process ID.
+
+        Args:
+            pid (int): Process ID to start metrics collection for.
+            metrics (int): Bitmask of metrics to collect (use class flags).
+
+        Returns:
+            bool: True if session started successfully, False otherwise.
+        """
+        return bool(self._dll.start_metrics_collection(pid, metrics))
+
+    def end_session(self, pid: int, metrics: int) -> dict:
+        """
+        End a previously started metrics collection session and retrieve results.
+
+        Args:
+            pid (int): Process ID of the session.
+            metrics (int): Bitmask of metrics to retrieve.
+
+        Returns:
+            dict: Metrics collected during the session.
+        """
+        return self._json_call(self._dll.end_metrics_collection, pid, metrics)
+
+    def get_snapshot(self, pid: int, metrics: int) -> dict:
+        """
+        Retrieve an instant snapshot of metrics for a process without starting a session.
+
+        Args:
+            pid (int): Process ID to query.
+            metrics (int): Bitmask of metrics to retrieve.
+
+        Returns:
+            dict: Current metrics snapshot.
+        """
+        return self._json_call(self._dll.get_metrics_json, pid, metrics)