dff-py 0.1.0__tar.gz

dff_py-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: dff-py
+Version: 0.1.0
+Summary: A simple differential fuzzing framework
+Author-email: Justin Traglia <jtraglia@pm.me>
+License: MIT
+Project-URL: Homepage, https://github.com/jtraglia/dff
+Project-URL: Repository, https://github.com/jtraglia/dff
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# DFF Python Implementation
+
+A Python implementation of the DFF (Differential Fuzzing Framework) that uses Unix domain sockets and System V shared memory for high-performance IPC.
+
+## Installation
+
+### From PyPI (once published)
+
+```bash
+pip install dff-py
+```
+
+### From Source
+
+```bash
+cd python
+pip install -e .
+```
+
+## Requirements
+
+- Python 3.8 or higher
+- Linux or macOS (Windows is not supported due to Unix domain sockets and System V shared memory)
+- System configured for 100 MiB shared memory segments (see main README)
+
+## Usage
+
+### Client
+
+```python
+from dff import Client
+
+def process_func(method: str, inputs: list[bytes]) -> bytes:
+    """Process function that handles fuzzing inputs."""
+    if method != "sha":
+        raise ValueError(f"Unknown method: {method}")
+
+    # Process the first input (matching Go/Java behavior)
+    import hashlib
+    return hashlib.sha256(inputs[0]).digest()
+
+# Create and run client
+client = Client("python", process_func)
+client.connect()
+client.run()
+```
+
+### Server
+
+```python
+from dff import Server
+
+def provider() -> list[bytes]:
+    """Generate fuzzing inputs."""
+    import random
+    size = random.randint(1024, 4096)
+    data = bytes(random.randint(0, 255) for _ in range(size))
+    return [data]
+
+# Create and run server
+server = Server("sha")
+server.run(provider)
+```
+
+## Examples
+
+See the `examples/python/` directory for complete working examples:
+
+- `client.py` - SHA256 hashing client implementation
+- `server.py` - Fuzzing server with random data provider
+
+### Running the Examples
+
+Start the server:
+```bash
+./examples/python/server.py
+```
+
+In another terminal, start one or more clients:
+```bash
+./examples/python/client.py
+./examples/python/client.py python2
+./examples/golang/client/client golang
+```
+
+The server will detect any differences in the outputs from different clients.
+
+## Architecture
+
+The framework uses:
+- **Unix domain sockets** for control messages and coordination
+- **System V shared memory** for efficient data transfer
+- **Multiple client support** for differential testing
+
+### Protocol
+
+1. Client connects to server via Unix socket at `/tmp/dff`
+2. Client sends its name
+3. Server responds with:
+   - Input shared memory ID (4 bytes, big-endian)
+   - Output shared memory ID (4 bytes, big-endian)
+   - Method name (up to 64 bytes)
+4. For each fuzzing iteration:
+   - Server writes input data to shared memory
+   - Server sends message with input count and sizes
+   - Client processes data and writes result to output shared memory
+   - Client sends result size back to server
+   - Server compares results across clients
+
+## Performance
+
+The Python implementation is functional but slower than compiled language implementations (Go, Rust) due to:
+- Python's Global Interpreter Lock (GIL)
+- Interpreter overhead
+- Dynamic typing
+
+For better performance, consider:
+- Using PyPy instead of CPython
+- Implementing compute-heavy processing in C extensions
+- Running multiple client instances
+
+## Development
+
+### Running Tests
+
+```bash
+cd python
+pip install -e .[dev]
+pytest
+```
+
+### Code Quality
+
+```bash
+# Format code
+black dff/
+
+# Lint
+ruff dff/
+
+# Type checking
+mypy dff/
+```
+
+## License
+
+MIT License - see the LICENSE file in the root directory.

dff_py-0.1.0/README.md

@@ -0,0 +1,147 @@
+# DFF Python Implementation
+
+A Python implementation of the DFF (Differential Fuzzing Framework) that uses Unix domain sockets and System V shared memory for high-performance IPC.
+
+## Installation
+
+### From PyPI (once published)
+
+```bash
+pip install dff-py
+```
+
+### From Source
+
+```bash
+cd python
+pip install -e .
+```
+
+## Requirements
+
+- Python 3.8 or higher
+- Linux or macOS (Windows is not supported due to Unix domain sockets and System V shared memory)
+- System configured for 100 MiB shared memory segments (see main README)
+
+## Usage
+
+### Client
+
+```python
+from dff import Client
+
+def process_func(method: str, inputs: list[bytes]) -> bytes:
+    """Process function that handles fuzzing inputs."""
+    if method != "sha":
+        raise ValueError(f"Unknown method: {method}")
+
+    # Process the first input (matching Go/Java behavior)
+    import hashlib
+    return hashlib.sha256(inputs[0]).digest()
+
+# Create and run client
+client = Client("python", process_func)
+client.connect()
+client.run()
+```
+
+### Server
+
+```python
+from dff import Server
+
+def provider() -> list[bytes]:
+    """Generate fuzzing inputs."""
+    import random
+    size = random.randint(1024, 4096)
+    data = bytes(random.randint(0, 255) for _ in range(size))
+    return [data]
+
+# Create and run server
+server = Server("sha")
+server.run(provider)
+```
+
+## Examples
+
+See the `examples/python/` directory for complete working examples:
+
+- `client.py` - SHA256 hashing client implementation
+- `server.py` - Fuzzing server with random data provider
+
+### Running the Examples
+
+Start the server:
+```bash
+./examples/python/server.py
+```
+
+In another terminal, start one or more clients:
+```bash
+./examples/python/client.py
+./examples/python/client.py python2
+./examples/golang/client/client golang
+```
+
+The server will detect any differences in the outputs from different clients.
+
+## Architecture
+
+The framework uses:
+- **Unix domain sockets** for control messages and coordination
+- **System V shared memory** for efficient data transfer
+- **Multiple client support** for differential testing
+
+### Protocol
+
+1. Client connects to server via Unix socket at `/tmp/dff`
+2. Client sends its name
+3. Server responds with:
+   - Input shared memory ID (4 bytes, big-endian)
+   - Output shared memory ID (4 bytes, big-endian)
+   - Method name (up to 64 bytes)
+4. For each fuzzing iteration:
+   - Server writes input data to shared memory
+   - Server sends message with input count and sizes
+   - Client processes data and writes result to output shared memory
+   - Client sends result size back to server
+   - Server compares results across clients
+
+## Performance
+
+The Python implementation is functional but slower than compiled language implementations (Go, Rust) due to:
+- Python's Global Interpreter Lock (GIL)
+- Interpreter overhead
+- Dynamic typing
+
+For better performance, consider:
+- Using PyPy instead of CPython
+- Implementing compute-heavy processing in C extensions
+- Running multiple client instances
+
+## Development
+
+### Running Tests
+
+```bash
+cd python
+pip install -e .[dev]
+pytest
+```
+
+### Code Quality
+
+```bash
+# Format code
+black dff/
+
+# Lint
+ruff dff/
+
+# Type checking
+mypy dff/
+```
+
+## License
+
+MIT License - see the LICENSE file in the root directory.

dff_py-0.1.0/dff/__init__.py

@@ -0,0 +1,7 @@
+"""DFF - Differential Fuzzing Framework."""
+
+from .client import Client
+from .server import Server
+
+__version__ = "0.1.0"
+__all__ = ["Client", "Server"]

dff_py-0.1.0/dff/client.py

@@ -0,0 +1,211 @@
+"""DFF Client implementation."""
+
+import ctypes
+import socket
+import struct
+import signal
+import time
+from typing import Callable, List, Optional
+
+from .shm import SharedMemory
+
+SOCKET_PATH = "/tmp/dff"
+MAX_METHOD_LENGTH = 64
+
+
+ProcessFunc = Callable[[str, List[bytes]], bytes]
+
+
+class Client:
+    """Client encapsulates the client-side behavior for connecting to the fuzzing server."""
+
+    def __init__(self, name: str, process_func: ProcessFunc):
+        """Initialize a new Client.
+
+        Args:
+            name: The client identifier sent to the server
+            process_func: The callback function used to process fuzzing inputs
+        """
+        self.name = name
+        self.process_func = process_func
+        self.conn: Optional[socket.socket] = None
+        self.input_shm: Optional[ctypes.Array] = None
+        self.output_shm: Optional[ctypes.Array] = None
+        self.input_shm_obj: Optional[SharedMemory] = None
+        self.output_shm_obj: Optional[SharedMemory] = None
+        self.method: str = ""
+        self.shutdown = False
+
+    def connect(self) -> None:
+        """Establish a connection to the fuzzing server.
+
+        Connects to the server, sends the client name, attaches to shared memory
+        segments, and reads the fuzzing method from the server.
+
+        Raises:
+            ConnectionError: If connection fails
+            OSError: If shared memory operations fail
+        """
+        max_retries = 10
+        retry_delay = 0.1
+
+        for attempt in range(max_retries):
+            try:
+                self.conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+                self.conn.connect(SOCKET_PATH)
+                break
+            except (ConnectionError, FileNotFoundError) as e:
+                if attempt == max_retries - 1:
+                    raise ConnectionError(
+                        f"Failed to connect to server after {max_retries} attempts: {e}"
+                    )
+                time.sleep(retry_delay)
+
+        if not self.conn:
+            raise ConnectionError("Failed to establish connection")
+
+        self.conn.sendall(self.name.encode())
+
+        input_shm_id_bytes = self.conn.recv(4)
+        if len(input_shm_id_bytes) != 4:
+            raise ConnectionError("Failed to read input shared memory ID")
+        input_shm_id = struct.unpack(">I", input_shm_id_bytes)[0]
+
+        self.input_shm_obj = SharedMemory(input_shm_id)
+        self.input_shm = self.input_shm_obj.attach()
+
+        output_shm_id_bytes = self.conn.recv(4)
+        if len(output_shm_id_bytes) != 4:
+            raise ConnectionError("Failed to read output shared memory ID")
+        output_shm_id = struct.unpack(">I", output_shm_id_bytes)[0]
+
+        self.output_shm_obj = SharedMemory(output_shm_id)
+        self.output_shm = self.output_shm_obj.attach()
+
+        method_bytes = self.conn.recv(MAX_METHOD_LENGTH)
+        if not method_bytes:
+            raise ConnectionError("Failed to read method name")
+        self.method = method_bytes.decode().rstrip('\x00')
+
+        print(f"Connected with fuzzing method: {self.method}")
+
+    def run(self) -> None:
+        """Run the client fuzzing loop.
+
+        Waits for the server to send input sizes, extracts data from shared memory,
+        processes it via the provided process_func, writes results to output shared
+        memory, and sends back the result size.
+
+        Raises:
+            RuntimeError: If not connected
+            Exception: Any exception from the process function
+        """
+        if not self.conn or not self.input_shm or not self.output_shm:
+            raise RuntimeError("Client not connected")
+
+        def signal_handler(_signum: int, _frame: object) -> None:
+            self.shutdown = True
+            print("\nShutting down gracefully...")
+
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)
+
+        print("Client running... Press Ctrl+C to exit.")
+
+        try:
+            while not self.shutdown:
+                # Read the message containing number of inputs and their sizes
+                input_msg = self.conn.recv(1024)
+                if not input_msg:
+                    break
+
+                if len(input_msg) < 4:
+                    raise ValueError(f"Invalid input message length: {len(input_msg)}")
+
+                # First 4 bytes: number of inputs
+                num_inputs = struct.unpack(">I", input_msg[0:4])[0]
+
+                # Following bytes: sizes of each input (4 bytes each)
+                expected_length = 4 + (num_inputs * 4)
+                if len(input_msg) < expected_length:
+                    raise ValueError(f"Input message too short: expected {expected_length}, got {len(input_msg)}")
+
+                # Parse all sizes at once
+                input_sizes = struct.unpack(f">{num_inputs}I", input_msg[4:4 + num_inputs * 4])
+
+                inputs: List[bytes] = []
+                offset = 0
+                for size in input_sizes:
+                    if offset + size > len(self.input_shm):
+                        raise ValueError(f"Input size {size} at offset {offset} exceeds buffer")
+                    # Use string_at to read bytes directly from memory address
+                    data_ptr = ctypes.addressof(self.input_shm) + offset
+                    data = ctypes.string_at(data_ptr, size)
+                    inputs.append(data)
+                    offset += size
+
+                try:
+                    start_time = time.perf_counter()
+                    result = self.process_func(self.method, inputs)
+                    elapsed_time = (time.perf_counter() - start_time) * 1000
+                    print(f"Processing time: {elapsed_time:.2f}ms")
+                except Exception as e:
+                    print(f"Process function error: {e}")
+                    result = b""
+
+                if not isinstance(result, bytes):
+                    raise TypeError(f"Process function must return bytes, got {type(result)}")
+
+                if len(result) > len(self.output_shm):
+                    raise ValueError(f"Result size {len(result)} exceeds output buffer")
+
+                # Write result bytes to output shared memory using memmove for performance
+                if isinstance(result, bytes) and len(result) > 0:
+                    dest_ptr = ctypes.addressof(self.output_shm)
+                    src = ctypes.c_char_p(result)
+                    ctypes.memmove(dest_ptr, src, len(result))
+                else:
+                    # Fallback for empty or non-bytes
+                    self.output_shm[0:len(result)] = result
+
+                self.conn.sendall(struct.pack(">I", len(result)))
+
+        except Exception as e:
+            if not self.shutdown:
+                print(f"Client error: {e}")
+                raise
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        """Close the client connection and clean up resources."""
+        if self.conn:
+            try:
+                self.conn.close()
+            except:
+                pass
+            self.conn = None
+
+        if self.input_shm_obj:
+            try:
+                self.input_shm_obj.detach()
+            except:
+                pass
+            self.input_shm_obj = None
+            self.input_shm = None
+
+        if self.output_shm_obj:
+            try:
+                self.output_shm_obj.detach()
+            except:
+                pass
+            self.output_shm_obj = None
+            self.output_shm = None
+
+    def __enter__(self) -> "Client":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        """Context manager exit."""
+        self.close()

dff_py-0.1.0/dff/server.py

@@ -0,0 +1,343 @@
+"""DFF Server implementation."""
+
+import ctypes
+import hashlib
+import os
+import socket
+import struct
+import signal
+import threading
+import time
+from typing import Callable, Dict, List, Optional
+from collections import defaultdict
+
+from .shm import SharedMemory, IPC_CREAT, IPC_EXCL, IPC_RMID
+
+SOCKET_PATH = "/tmp/dff"
+DEFAULT_INPUT_SHM_KEY = 1000
+DEFAULT_SHM_MAX_SIZE = 100 * 1024 * 1024  # 100 MiB
+DEFAULT_SHM_PERM = 0o666
+
+ProviderFunc = Callable[[], List[bytes]]
+
+
+class ClientEntry:
+    """Represents a connected client."""
+
+    def __init__(self, name: str, conn: socket.socket, shm_id: int, method: str):
+        self.name = name
+        self.conn = conn
+        self.shm_id = shm_id
+        self.shm_buffer = bytearray(DEFAULT_SHM_MAX_SIZE)
+        self.method = method
+
+
+class Server:
+    """Server encapsulates the server-side behavior for the fuzzing framework."""
+
+    def __init__(self, method: str):
+        """Initialize a new Server.
+
+        Args:
+            method: The fuzzing method name to send to clients
+        """
+        self.method = method
+        self.input_shm_key = DEFAULT_INPUT_SHM_KEY
+        self.shm_max_size = DEFAULT_SHM_MAX_SIZE
+        self.shm_perm = DEFAULT_SHM_PERM
+        self.clients: Dict[str, ClientEntry] = {}
+        self.clients_lock = threading.Lock()
+        self.shutdown = False
+        self.iteration_count = 0
+        self.total_duration = 0.0
+        self.input_shm: Optional[SharedMemory] = None
+        self.input_shm_buffer: Optional[ctypes.Array] = None
+        self.listener: Optional[socket.socket] = None
+
+    def _cleanup_existing_shm(self) -> None:
+        """Clean up any existing shared memory with our key."""
+        try:
+            existing_shm = SharedMemory.get(self.input_shm_key)
+            existing_shm.remove()
+            print(f"Removed existing input shared memory segment with key {self.input_shm_key}")
+        except OSError:
+            pass
+
+    def _create_shared_memory(self) -> None:
+        """Create the input shared memory segment."""
+        self._cleanup_existing_shm()
+
+        self.input_shm = SharedMemory.create(
+            self.input_shm_key,
+            self.shm_max_size,
+            self.shm_perm
+        )
+
+        self.input_shm_buffer = self.input_shm.attach()
+
+    def _handle_client(self, conn: socket.socket, addr: str) -> None:
+        """Handle a new client connection."""
+        try:
+            # Receive client name
+            name_bytes = conn.recv(256)
+            if not name_bytes:
+                conn.close()
+                return
+
+            client_name = name_bytes.decode().rstrip('\x00')
+            # Create output shared memory for this client
+            output_shm_key = self.input_shm_key + len(self.clients) + 1
+
+            # Clean up if it exists
+            try:
+                existing = SharedMemory.get(output_shm_key)
+                existing.remove()
+            except OSError:
+                pass
+
+            output_shm = SharedMemory.create(
+                output_shm_key,
+                self.shm_max_size,
+                self.shm_perm
+            )
+
+            # Send input shared memory ID
+            conn.sendall(struct.pack(">I", self.input_shm.shmid))
+
+            # Send output shared memory ID
+            conn.sendall(struct.pack(">I", output_shm.shmid))
+
+            # Send method name
+            conn.sendall(self.method.encode())
+
+            # Store client
+            with self.clients_lock:
+                if client_name not in self.clients:
+                    self.clients[client_name] = ClientEntry(
+                        client_name, conn, output_shm.shmid, self.method
+                    )
+                    print(f"Registered new client: {client_name}")
+
+        except Exception as e:
+            print(f"Error handling client: {e}")
+            conn.close()
+
+    def _status_updates(self) -> None:
+        """Print status updates every 5 seconds."""
+        while not self.shutdown:
+            time.sleep(5)
+
+            if self.iteration_count > 0:
+                with self.clients_lock:
+                    client_names = sorted(self.clients.keys())
+
+                avg_duration = self.total_duration / self.iteration_count
+                total_seconds = int(self.total_duration)
+                avg_ms = int(avg_duration * 1000)
+
+                print(f"Fuzzing Time: {total_seconds}s, Iterations: {self.iteration_count}, "
+                      f"Average Iteration: {avg_ms}ms, Clients: {','.join(client_names)}")
+
+    def _accept_clients(self) -> None:
+        """Accept client connections in a separate thread."""
+        while not self.shutdown:
+            try:
+                self.listener.settimeout(1.0)
+                conn, addr = self.listener.accept()
+                # Handle each client in a separate thread
+                thread = threading.Thread(
+                    target=self._handle_client,
+                    args=(conn, addr)
+                )
+                thread.daemon = True
+                thread.start()
+            except socket.timeout:
+                continue
+            except Exception as e:
+                if not self.shutdown:
+                    print(f"Error accepting client: {e}")
+
+    def run(self, provider: ProviderFunc) -> None:
+        """Run the fuzzing server.
+
+        Args:
+            provider: Function that generates fuzzing inputs
+        """
+        # Setup signal handler
+        def signal_handler(_signum: int, _frame: object) -> None:
+            self.shutdown = True
+            print("\nShutting down server...")
+
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)
+
+        # Clean up any existing socket
+        if os.path.exists(SOCKET_PATH):
+            os.unlink(SOCKET_PATH)
+
+        # Create shared memory
+        self._create_shared_memory()
+
+        # Create and bind socket
+        self.listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.listener.bind(SOCKET_PATH)
+        self.listener.listen(10)
+
+        # Start accepting clients in a separate thread
+        accept_thread = threading.Thread(target=self._accept_clients)
+        accept_thread.daemon = True
+        accept_thread.start()
+
+        # Start status updates thread
+        status_thread = threading.Thread(target=self._status_updates)
+        status_thread.daemon = True
+        status_thread.start()
+
+        # Main fuzzing loop
+        try:
+            while not self.shutdown:
+                # Wait until at least one client is connected
+                if len(self.clients) == 0:
+                    print("Waiting for a client...")
+                    time.sleep(1)
+                    continue
+
+                start_time = time.perf_counter()
+
+                # Generate inputs
+                inputs = provider()
+                if not inputs:
+                    continue
+
+                # Prepare input data
+                input_sizes = []
+                offset = 0
+                for input_data in inputs:
+                    size = len(input_data)
+                    if offset + size > self.shm_max_size:
+                        print(f"Warning: Input data exceeds shared memory size")
+                        break
+
+                    # Write to shared memory using memmove for better performance
+                    dest_ptr = ctypes.addressof(self.input_shm_buffer) + offset
+                    if isinstance(input_data, bytes):
+                        src = ctypes.c_char_p(input_data)
+                        ctypes.memmove(dest_ptr, src, size)
+                    else:
+                        # Fallback for other types
+                        self.input_shm_buffer[offset:offset + size] = input_data
+                    input_sizes.append(size)
+                    offset += size
+
+                # Prepare message with number of inputs and their sizes
+                msg = struct.pack(">I", len(input_sizes))
+                for size in input_sizes:
+                    msg += struct.pack(">I", size)
+
+                # Send to all clients and collect results
+                results = {}
+                dead_clients = []
+
+                with self.clients_lock:
+                    for name, client in self.clients.items():
+                        try:
+                            # Send input sizes
+                            client.conn.sendall(msg)
+
+                            # Read result size
+                            result_size_bytes = client.conn.recv(4)
+                            if len(result_size_bytes) != 4:
+                                dead_clients.append(name)
+                                continue
+
+                            result_size = struct.unpack(">I", result_size_bytes)[0]
+
+                            # Read result from client's output shared memory
+                            output_shm = SharedMemory(client.shm_id)
+                            output_buffer = output_shm.attach()
+                            result = bytes(output_buffer[0:result_size])
+                            output_shm.detach()
+
+                            results[name] = result
+
+                        except Exception as e:
+                            print(f"Error communicating with client {name}: {e}")
+                            dead_clients.append(name)
+
+                # Remove dead clients
+                for name in dead_clients:
+                    print(f"Removing dead client: {name}")
+                    with self.clients_lock:
+                        if name in self.clients:
+                            try:
+                                self.clients[name].conn.close()
+                            except:
+                                pass
+                            del self.clients[name]
+
+                # Check for differences
+                if len(results) > 1:
+                    first_result = None
+                    all_same = True
+                    for result in results.values():
+                        if first_result is None:
+                            first_result = result
+                        elif result != first_result:
+                            all_same = False
+                            break
+
+                    if not all_same:
+                        print("Values are different:")
+                        for name, result in results.items():
+                            result_hash = hashlib.sha256(result).hexdigest()
+                            print(f"Key: {name}, Value: {result_hash}")
+
+                # Update statistics
+                duration = time.perf_counter() - start_time
+                self.iteration_count += 1
+                self.total_duration += duration
+
+
+        except Exception as e:
+            if not self.shutdown:
+                print(f"Server error: {e}")
+                raise
+        finally:
+            self._cleanup()
+
+    def _cleanup(self) -> None:
+        """Clean up resources."""
+        print("Cleaning up server resources...")
+
+        # Close client connections
+        with self.clients_lock:
+            for client in self.clients.values():
+                try:
+                    client.conn.close()
+                except:
+                    pass
+            self.clients.clear()
+
+        # Close listener
+        if self.listener:
+            try:
+                self.listener.close()
+            except:
+                pass
+
+        # Clean up socket file
+        if os.path.exists(SOCKET_PATH):
+            try:
+                os.unlink(SOCKET_PATH)
+            except:
+                pass
+
+        # Clean up shared memory
+        if self.input_shm:
+            try:
+                self.input_shm.detach()
+                self.input_shm.remove()
+            except:
+                pass
+
+        print("Server shutdown complete")

dff_py-0.1.0/dff/shm.py

@@ -0,0 +1,186 @@
+"""System V shared memory wrapper for Python."""
+
+import ctypes
+import ctypes.util
+import sys
+from typing import Optional
+
+IPC_CREAT = 0o1000
+IPC_EXCL = 0o2000
+IPC_RMID = 0
+
+if sys.platform == "darwin":
+    libc_name = ctypes.util.find_library("c")
+elif sys.platform.startswith("linux"):
+    libc_name = ctypes.util.find_library("c")
+else:
+    raise OSError(f"Unsupported platform: {sys.platform}")
+
+if not libc_name:
+    raise OSError("Could not find libc")
+
+libc = ctypes.CDLL(libc_name)
+
+
+class ShmidDs(ctypes.Structure):
+    """Shared memory segment descriptor structure."""
+    if sys.platform == "darwin":
+        _fields_ = [
+            ("shm_perm", ctypes.c_void_p),
+            ("shm_segsz", ctypes.c_size_t),
+            ("shm_lpid", ctypes.c_int),
+            ("shm_cpid", ctypes.c_int),
+            ("shm_nattch", ctypes.c_short),
+            ("shm_atime", ctypes.c_long),
+            ("shm_dtime", ctypes.c_long),
+            ("shm_ctime", ctypes.c_long),
+            ("shm_internal", ctypes.c_void_p),
+        ]
+    else:
+        _fields_ = [
+            ("shm_perm", ctypes.c_void_p),
+            ("shm_segsz", ctypes.c_size_t),
+            ("shm_atime", ctypes.c_long),
+            ("shm_dtime", ctypes.c_long),
+            ("shm_ctime", ctypes.c_long),
+            ("shm_cpid", ctypes.c_int),
+            ("shm_lpid", ctypes.c_int),
+            ("shm_nattch", ctypes.c_short),
+        ]
+
+
+libc.shmget.argtypes = [ctypes.c_int, ctypes.c_size_t, ctypes.c_int]
+libc.shmget.restype = ctypes.c_int
+
+libc.shmat.argtypes = [ctypes.c_int, ctypes.c_void_p, ctypes.c_int]
+libc.shmat.restype = ctypes.c_void_p
+
+libc.shmdt.argtypes = [ctypes.c_void_p]
+libc.shmdt.restype = ctypes.c_int
+
+libc.shmctl.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.POINTER(ShmidDs)]
+libc.shmctl.restype = ctypes.c_int
+
+
+class SharedMemory:
+    """Wrapper for System V shared memory operations."""
+
+    def __init__(self, shmid: int, size: int = 0):
+        """Initialize shared memory wrapper.
+
+        Args:
+            shmid: Shared memory ID
+            size: Size of the shared memory segment (for reference)
+        """
+        self.shmid = shmid
+        self.size = size
+        self.addr: Optional[int] = None
+        self._attached = False
+
+    @classmethod
+    def create(cls, key: int, size: int, perm: int = 0o666) -> "SharedMemory":
+        """Create a new shared memory segment.
+
+        Args:
+            key: IPC key for the shared memory segment
+            size: Size of the segment in bytes
+            perm: Permissions for the segment
+
+        Returns:
+            SharedMemory object
+
+        Raises:
+            OSError: If creation fails
+        """
+        flags = perm | IPC_CREAT | IPC_EXCL
+        shmid = libc.shmget(key, size, flags)
+        if shmid == -1:
+            raise OSError(f"Failed to create shared memory with key {key}")
+        return cls(shmid, size)
+
+    @classmethod
+    def get(cls, key: int, size: int = 0) -> "SharedMemory":
+        """Get existing shared memory segment.
+
+        Args:
+            key: IPC key for the shared memory segment
+            size: Expected size (0 to get existing)
+
+        Returns:
+            SharedMemory object
+
+        Raises:
+            OSError: If segment doesn't exist
+        """
+        shmid = libc.shmget(key, size, 0)
+        if shmid == -1:
+            raise OSError(f"Failed to get shared memory with key {key}")
+        return cls(shmid, size)
+
+    def attach(self, addr: int = 0, flags: int = 0) -> ctypes.Array:
+        """Attach to the shared memory segment.
+
+        Args:
+            addr: Preferred attach address (0 for system choice)
+            flags: Attach flags
+
+        Returns:
+            ctypes array of the attached segment
+
+        Raises:
+            OSError: If attach fails
+        """
+        if self._attached:
+            raise RuntimeError("Already attached to shared memory")
+
+        result = libc.shmat(self.shmid, addr, flags)
+        if result == -1:
+            raise OSError(f"Failed to attach to shared memory ID {self.shmid}")
+
+        self.addr = result
+        self._attached = True
+
+        if self.size > 0:
+            return (ctypes.c_ubyte * self.size).from_address(self.addr)
+        else:
+            return (ctypes.c_ubyte * (100 * 1024 * 1024)).from_address(self.addr)
+
+    def detach(self) -> None:
+        """Detach from the shared memory segment."""
+        if not self._attached or self.addr is None:
+            return
+
+        result = libc.shmdt(self.addr)
+        if result == -1:
+            raise OSError("Failed to detach from shared memory")
+
+        self.addr = None
+        self._attached = False
+
+    def remove(self) -> None:
+        """Remove the shared memory segment."""
+        result = libc.shmctl(self.shmid, IPC_RMID, None)
+        if result == -1:
+            raise OSError(f"Failed to remove shared memory ID {self.shmid}")
+
+    def __del__(self) -> None:
+        """Cleanup - detach if still attached."""
+        if self._attached:
+            try:
+                self.detach()
+            except:
+                pass
+
+
+def attach_by_id(shmid: int, size: int = 0) -> ctypes.Array:
+    """Convenience function to attach to shared memory by ID.
+
+    Args:
+        shmid: Shared memory ID
+        size: Expected size (0 for default max)
+
+    Returns:
+        ctypes array of the attached segment
+    """
+    shm = SharedMemory(shmid, size)
+    return shm.attach()

dff_py-0.1.0/dff_py.egg-info/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: dff-py
+Version: 0.1.0
+Summary: A simple differential fuzzing framework
+Author-email: Justin Traglia <jtraglia@pm.me>
+License: MIT
+Project-URL: Homepage, https://github.com/jtraglia/dff
+Project-URL: Repository, https://github.com/jtraglia/dff
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# DFF Python Implementation
+
+A Python implementation of the DFF (Differential Fuzzing Framework) that uses Unix domain sockets and System V shared memory for high-performance IPC.
+
+## Installation
+
+### From PyPI (once published)
+
+```bash
+pip install dff-py
+```
+
+### From Source
+
+```bash
+cd python
+pip install -e .
+```
+
+## Requirements
+
+- Python 3.8 or higher
+- Linux or macOS (Windows is not supported due to Unix domain sockets and System V shared memory)
+- System configured for 100 MiB shared memory segments (see main README)
+
+## Usage
+
+### Client
+
+```python
+from dff import Client
+
+def process_func(method: str, inputs: list[bytes]) -> bytes:
+    """Process function that handles fuzzing inputs."""
+    if method != "sha":
+        raise ValueError(f"Unknown method: {method}")
+
+    # Process the first input (matching Go/Java behavior)
+    import hashlib
+    return hashlib.sha256(inputs[0]).digest()
+
+# Create and run client
+client = Client("python", process_func)
+client.connect()
+client.run()
+```
+
+### Server
+
+```python
+from dff import Server
+
+def provider() -> list[bytes]:
+    """Generate fuzzing inputs."""
+    import random
+    size = random.randint(1024, 4096)
+    data = bytes(random.randint(0, 255) for _ in range(size))
+    return [data]
+
+# Create and run server
+server = Server("sha")
+server.run(provider)
+```
+
+## Examples
+
+See the `examples/python/` directory for complete working examples:
+
+- `client.py` - SHA256 hashing client implementation
+- `server.py` - Fuzzing server with random data provider
+
+### Running the Examples
+
+Start the server:
+```bash
+./examples/python/server.py
+```
+
+In another terminal, start one or more clients:
+```bash
+./examples/python/client.py
+./examples/python/client.py python2
+./examples/golang/client/client golang
+```
+
+The server will detect any differences in the outputs from different clients.
+
+## Architecture
+
+The framework uses:
+- **Unix domain sockets** for control messages and coordination
+- **System V shared memory** for efficient data transfer
+- **Multiple client support** for differential testing
+
+### Protocol
+
+1. Client connects to server via Unix socket at `/tmp/dff`
+2. Client sends its name
+3. Server responds with:
+   - Input shared memory ID (4 bytes, big-endian)
+   - Output shared memory ID (4 bytes, big-endian)
+   - Method name (up to 64 bytes)
+4. For each fuzzing iteration:
+   - Server writes input data to shared memory
+   - Server sends message with input count and sizes
+   - Client processes data and writes result to output shared memory
+   - Client sends result size back to server
+   - Server compares results across clients
+
+## Performance
+
+The Python implementation is functional but slower than compiled language implementations (Go, Rust) due to:
+- Python's Global Interpreter Lock (GIL)
+- Interpreter overhead
+- Dynamic typing
+
+For better performance, consider:
+- Using PyPy instead of CPython
+- Implementing compute-heavy processing in C extensions
+- Running multiple client instances
+
+## Development
+
+### Running Tests
+
+```bash
+cd python
+pip install -e .[dev]
+pytest
+```
+
+### Code Quality
+
+```bash
+# Format code
+black dff/
+
+# Lint
+ruff dff/
+
+# Type checking
+mypy dff/
+```
+
+## License
+
+MIT License - see the LICENSE file in the root directory.

dff_py-0.1.0/dff_py.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+dff/__init__.py
+dff/client.py
+dff/server.py
+dff/shm.py
+dff_py.egg-info/PKG-INFO
+dff_py.egg-info/SOURCES.txt
+dff_py.egg-info/dependency_links.txt
+dff_py.egg-info/top_level.txt

dff_py-0.1.0/dff_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dff_py-0.1.0/dff_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+dff

dff_py-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dff-py"
+version = "0.1.0"
+description = "A simple differential fuzzing framework"
+readme = "README.md"
+authors = [{name = "Justin Traglia", email = "jtraglia@pm.me"}]
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jtraglia/dff"
+Repository = "https://github.com/jtraglia/dff"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["dff*"]

dff_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+