sonx 0.1.0__tar.gz

sonx-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: sonx
+Version: 0.1.0
+Summary: Superior Organised Network - Remote access tool
+Author: son
+License: MIT
+Project-URL: Homepage, https://github.com/randompasswordis7/son
+Project-URL: Source, https://github.com/randompasswordis7/son
+Keywords: remote-access,ssh,tunnel,terminal,network
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110.0; extra == "web"
+Requires-Dist: uvicorn>=0.27.0; extra == "web"
+Requires-Dist: httpx>=0.27.0; extra == "web"
+
+# son — Superior Organised Network
+
+Remote access tool with a daemon-agent architecture. Run `sond` on target machines, connect via `son` CLI or web UI.
+
+## Install
+
+```bash
+pip install son
+# or with web UI support:
+pip install "son[web]"
+```
+
+## Quick start
+
+**On the target machine** (the one you want to access):
+
+```bash
+sond
+```
+
+**On your machine** (the one you connect from):
+
+```bash
+# Discover sond instances on LAN
+son discover
+
+# Connect to a remote shell
+son connect 192.168.1.50
+
+# Tunnel a local port through the target
+son tunnel 192.168.1.50 -L 8080:localhost:80
+
+# Web terminal UI
+son web
+```
+
+## How it works
+
+| Component | Runs on | Purpose |
+|---|---|---|
+| `sond` | Target machine | UDP broadcast (LAN discovery), WebSocket server for shell + tunnels |
+| `son` | Your machine | CLI + web UI, connects to `sond` instances |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `sond` | Start daemon (`-p` port, `--password`, `--no-broadcast`) |
+| `son discover` | Scan LAN for sond instances |
+| `son connect <host>` | Open remote shell (`-s powershell/bash/cmd`) |
+| `son tunnel <host> -L local:remote:port` | Local port forwarding |
+| `son web` | Browser-based terminal at `http://127.0.0.1:8585` |
+
+## License
+
+MIT

sonx-0.1.0/README.md

@@ -0,0 +1,56 @@
+# son — Superior Organised Network
+
+Remote access tool with a daemon-agent architecture. Run `sond` on target machines, connect via `son` CLI or web UI.
+
+## Install
+
+```bash
+pip install son
+# or with web UI support:
+pip install "son[web]"
+```
+
+## Quick start
+
+**On the target machine** (the one you want to access):
+
+```bash
+sond
+```
+
+**On your machine** (the one you connect from):
+
+```bash
+# Discover sond instances on LAN
+son discover
+
+# Connect to a remote shell
+son connect 192.168.1.50
+
+# Tunnel a local port through the target
+son tunnel 192.168.1.50 -L 8080:localhost:80
+
+# Web terminal UI
+son web
+```
+
+## How it works
+
+| Component | Runs on | Purpose |
+|---|---|---|
+| `sond` | Target machine | UDP broadcast (LAN discovery), WebSocket server for shell + tunnels |
+| `son` | Your machine | CLI + web UI, connects to `sond` instances |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `sond` | Start daemon (`-p` port, `--password`, `--no-broadcast`) |
+| `son discover` | Scan LAN for sond instances |
+| `son connect <host>` | Open remote shell (`-s powershell/bash/cmd`) |
+| `son tunnel <host> -L local:remote:port` | Local port forwarding |
+| `son web` | Browser-based terminal at `http://127.0.0.1:8585` |
+
+## License
+
+MIT

sonx-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "sonx"
+version = "0.1.0"
+description = "Superior Organised Network - Remote access tool"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "son"}]
+keywords = ["remote-access", "ssh", "tunnel", "terminal", "network"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+web = ["fastapi>=0.110.0", "uvicorn>=0.27.0", "httpx>=0.27.0"]
+
+[project.urls]
+Homepage = "https://github.com/randompasswordis7/son"
+Source = "https://github.com/randompasswordis7/son"
+
+[project.scripts]
+son = "son.cli.main:app"
+sond = "son.daemon.main:main"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["son*", "sond*"]

sonx-0.1.0/setup.cfg

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

sonx-0.1.0/son/__main__.py

@@ -0,0 +1,3 @@
+from son.cli.main import app
+
+app()

sonx-0.1.0/son/cli/connect.py

@@ -0,0 +1,77 @@
+import asyncio
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+
+from son.client.connector import SonConnector
+from son.core.protocol import CONNECTION_PORT
+from son.core.types import get_default_shell
+
+app = typer.Typer(help="Connect to a remote sond instance")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def connect(
+    host: str = typer.Argument(..., help="sond hostname or IP address"),
+    port: int = typer.Option(CONNECTION_PORT, "--port", "-p", help="sond port"),
+    password: str = typer.Option("", "--password", "-P", help="auth password"),
+    shell: str = typer.Option("", "--shell", "-s", help="shell type (powershell, cmd, bash)"),
+):
+    target_shell = shell or get_default_shell()
+
+    async def run():
+        connector = SonConnector(host, port, password)
+        try:
+            await connector.connect()
+        except Exception as e:
+            console.print(f"[red]connection failed:[/] {e}")
+            raise typer.Exit(1)
+
+        console.print(Panel(
+            f"[bold green]connected[/] to [cyan]{host}:{port}[/] via [yellow]{target_shell}[/]\n"
+            "[dim]type 'exit' to disconnect[/]",
+            border_style="green",
+        ))
+
+        await connector.open_shell(shell=target_shell)
+
+        async def read_stdin():
+            loop = asyncio.get_running_loop()
+            while True:
+                line = await loop.run_in_executor(None, sys.stdin.readline)
+                if not line:
+                    break
+                if line.strip().lower() == "exit":
+                    break
+                await connector.send_input(line)
+
+        async def handle_output(data: str):
+            sys.stdout.write(data)
+            sys.stdout.flush()
+
+        connector.on_output(handle_output)
+        connector.on_disconnect(lambda: console.print("\n[red]disconnected[/]"))
+
+        tasks = [
+            asyncio.create_task(connector.listen()),
+            asyncio.create_task(read_stdin()),
+        ]
+
+        try:
+            await asyncio.gather(*tasks)
+        except (asyncio.CancelledError, KeyboardInterrupt):
+            pass
+        finally:
+            await connector.disconnect()
+            for t in tasks:
+                t.cancel()
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        pass

sonx-0.1.0/son/cli/discover.py

@@ -0,0 +1,66 @@
+import asyncio
+import time
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.live import Live
+
+from son.client.discovery import DiscoveryListener
+from son.core.types import DiscoveryInfo
+
+app = typer.Typer(help="Discover sond instances on the local network")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def discover(
+    timeout: Optional[float] = typer.Option(None, "--timeout", "-t", help="scan duration in seconds"),
+):
+    discovered: list[DiscoveryInfo] = []
+    start = time.monotonic()
+
+    def on_discover(info: DiscoveryInfo):
+        for d in discovered:
+            if d.ip == info.ip and d.port == info.port:
+                return
+        discovered.append(info)
+        console.print(f"  [green]✓[/] found [bold]{info.hostname}[/] at {info.ip}:{info.port}")
+
+    async def run():
+        listener = DiscoveryListener()
+        listener.on_discover(on_discover)
+        console.print("[dim]scanning for sond instances...[/]")
+        task = asyncio.create_task(listener.start())
+
+        if timeout:
+            await asyncio.sleep(timeout)
+        else:
+            await asyncio.sleep(5)
+
+        listener.stop()
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+    asyncio.run(run())
+
+    if not discovered:
+        console.print("\n[yellow]no sond instances found[/]")
+        return
+
+    table = Table(title=f"Found {len(discovered)} sond instance(s)")
+    table.add_column("Hostname", style="cyan")
+    table.add_column("IP", style="green")
+    table.add_column("Port", style="yellow")
+    table.add_column("OS")
+
+    for d in discovered:
+        table.add_row(d.hostname, d.ip, str(d.port), d.os)
+
+    console.print("\n")
+    console.print(table)
+    console.print("\n[dim]connect:[/] [bold]son connect <hostname|ip>[/]")

sonx-0.1.0/son/cli/main.py

@@ -0,0 +1,19 @@
+import typer
+
+from son.cli import discover, connect, tunnel, web
+
+app = typer.Typer(
+    name="son",
+    help="Superior Organised Network - remote access tool",
+    no_args_is_help=True,
+)
+
+app.add_typer(discover.app, name="discover")
+app.add_typer(connect.app, name="connect")
+app.add_typer(tunnel.app, name="tunnel")
+app.add_typer(web.app, name="web")
+
+
+@app.callback()
+def callback():
+    pass

sonx-0.1.0/son/cli/tunnel.py

@@ -0,0 +1,76 @@
+import asyncio
+import re
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from son.client.connector import SonConnector
+from son.client.tunnel import TunnelManager
+from son.core.protocol import CONNECTION_PORT
+
+app = typer.Typer(help="Create tunnels through a sond agent")
+console = Console()
+
+LOCAL_FORWARD_RE = re.compile(r"^(?:-L\s+)?(\d+):([^:]+):(\d+)$")
+
+
+@app.callback(invoke_without_command=True)
+def tunnel(
+    host: str = typer.Argument(..., help="sond hostname or IP"),
+    port: int = typer.Option(CONNECTION_PORT, "--port", "-p", help="sond port"),
+    password: str = typer.Option("", "--password", "-P", help="auth password"),
+    local: Optional[str] = typer.Option(
+        None, "--local", "-L",
+        help="local forward: local_port:remote_host:remote_port",
+    ),
+):
+    if not local:
+        console.print("[red]specify a tunnel with --local (-L), e.g. -L 8080:localhost:80[/]")
+        raise typer.Exit(1)
+
+    m = LOCAL_FORWARD_RE.match(local)
+    if not m:
+        console.print("[red]invalid format, use: local_port:remote_host:remote_port[/]")
+        raise typer.Exit(1)
+
+    local_port = int(m.group(1))
+    remote_host = m.group(2)
+    remote_port = int(m.group(3))
+
+    async def run():
+        connector = SonConnector(host, port, password)
+        try:
+            await connector.connect()
+        except Exception as e:
+            console.print(f"[red]connection failed:[/] {e}")
+            raise typer.Exit(1)
+
+        mgr = TunnelManager(connector)
+
+        await mgr.listen("127.0.0.1", local_port, remote_host, remote_port)
+
+        console.print(Panel(
+            f"[bold green]tunnel active[/]\n"
+            f"  [cyan]127.0.0.1:{local_port}[/] → [yellow]{remote_host}:{remote_port}[/] via [bold]{host}[/]",
+            border_style="green",
+        ))
+        console.print("[dim]press Ctrl+C to stop[/]\n")
+
+        listen_task = asyncio.create_task(connector.listen())
+
+        try:
+            await asyncio.Event().wait()
+        except (asyncio.CancelledError, KeyboardInterrupt):
+            pass
+        finally:
+            await mgr.stop_all()
+            listen_task.cancel()
+            await connector.disconnect()
+            console.print("[red]tunnel closed[/]")
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        pass

sonx-0.1.0/son/cli/web.py

@@ -0,0 +1,15 @@
+import typer
+from rich.console import Console
+
+app = typer.Typer(help="Start the local web UI")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def web(
+    port: int = typer.Option(8585, "--port", "-p", help="web UI port"),
+    host: str = typer.Option("127.0.0.1", "--host", "-H", help="bind address"),
+):
+    from son.web.server import run
+    console.print(f"[green]starting web UI at [bold]http://{host}:{port}[/][/]")
+    run(host=host, port=port)

sonx-0.1.0/son/client/connector.py

@@ -0,0 +1,125 @@
+import asyncio
+import json
+import logging
+from typing import Callable, Optional
+
+import websockets
+
+from son.core.protocol import (
+    WS_OPEN, WS_INPUT, WS_OUTPUT, WS_RESIZE, WS_CLOSE,
+    WS_AUTH, WS_AUTH_OK, WS_AUTH_FAIL,
+    WS_TUNNEL_OPEN, WS_TUNNEL_DATA, WS_TUNNEL_CLOSE,
+)
+
+log = logging.getLogger(__name__)
+
+
+class SonConnector:
+    def __init__(self, host: str, port: int, password: str = ""):
+        self._host = host
+        self._port = port
+        self._password = password
+        self._ws = None
+        self._shell_open = False
+        self._on_output: Optional[Callable] = None
+        self._on_disconnect: Optional[Callable] = None
+        self._on_tunnel_data: Optional[Callable] = None
+        self._on_tunnel_close: Optional[Callable] = None
+
+    @property
+    def connected(self) -> bool:
+        return self._ws is not None and not self._ws.close_code
+
+    def on_output(self, callback: Callable):
+        self._on_output = callback
+
+    def on_disconnect(self, callback: Callable):
+        self._on_disconnect = callback
+
+    def on_tunnel_data(self, callback: Callable):
+        self._on_tunnel_data = callback
+
+    def on_tunnel_close(self, callback: Callable):
+        self._on_tunnel_close = callback
+
+    async def connect(self):
+        uri = f"ws://{self._host}:{self._port}"
+        self._ws = await websockets.connect(uri)
+        if self._password:
+            await self._send({"type": WS_AUTH, "password": self._password})
+            resp = json.loads(await self._ws.recv())
+            if resp.get("type") == WS_AUTH_FAIL:
+                raise PermissionError("authentication failed")
+        log.info("connected to %s:%s", self._host, self._port)
+        return self
+
+    async def open_shell(self, shell: str = "", cols: int = 120, rows: int = 30):
+        await self._send({"type": WS_OPEN, "shell": shell, "cols": cols, "rows": rows})
+        self._shell_open = True
+
+    async def send_input(self, data: str):
+        if self._shell_open:
+            await self._send({"type": WS_INPUT, "data": data})
+
+    async def resize(self, cols: int, rows: int):
+        if self._shell_open:
+            await self._send({"type": WS_RESIZE, "cols": cols, "rows": rows})
+
+    async def close_shell(self):
+        if self._shell_open:
+            await self._send({"type": WS_CLOSE})
+            self._shell_open = False
+
+    async def tunnel_open(self, remote_host: str, remote_port: int, tunnel_id: int):
+        await self._send({
+            "type": WS_TUNNEL_OPEN,
+            "tunnel_id": tunnel_id,
+            "remote_host": remote_host,
+            "remote_port": remote_port,
+        })
+
+    async def tunnel_send(self, tunnel_id: int, data: str):
+        await self._send({
+            "type": WS_TUNNEL_DATA,
+            "tunnel_id": tunnel_id,
+            "data": data,
+        })
+
+    async def tunnel_close(self, tunnel_id: int):
+        await self._send({"type": WS_TUNNEL_CLOSE, "tunnel_id": tunnel_id})
+
+    async def _send(self, msg: dict):
+        if self._ws:
+            try:
+                await self._ws.send(json.dumps(msg))
+            except websockets.exceptions.ConnectionClosed:
+                pass
+
+    async def listen(self):
+        try:
+            async for raw in self._ws:
+                msg = json.loads(raw)
+                msg_type = msg.get("type")
+                if msg_type == WS_OUTPUT:
+                    if self._on_output:
+                        self._on_output(msg.get("data", ""))
+                elif msg_type == WS_TUNNEL_DATA:
+                    if self._on_tunnel_data:
+                        self._on_tunnel_data(msg.get("tunnel_id"), msg.get("data", ""))
+                elif msg_type == WS_TUNNEL_CLOSE:
+                    if self._on_tunnel_close:
+                        self._on_tunnel_close(msg.get("tunnel_id"))
+                elif msg_type == WS_CLOSE:
+                    self._shell_open = False
+                    break
+        except (websockets.exceptions.ConnectionClosed, asyncio.CancelledError):
+            pass
+        finally:
+            if self._on_disconnect:
+                self._on_disconnect()
+
+    async def disconnect(self):
+        await self.close_shell()
+        if self._ws:
+            await self._ws.close()
+        log.info("disconnected")

sonx-0.1.0/son/client/discovery.py

@@ -0,0 +1,72 @@
+import asyncio
+import socket
+import logging
+from typing import Callable
+
+from son.core.protocol import DISCOVERY_PORT, DISCOVERY_MAGIC
+from son.core.types import DiscoveryInfo
+
+log = logging.getLogger(__name__)
+
+
+class DiscoveryListener:
+    def __init__(self):
+        self._running = False
+        self._on_discover: Callable[[DiscoveryInfo], None] | None = None
+        self._seen: set[str] = set()
+
+    def on_discover(self, callback: Callable[[DiscoveryInfo], None]):
+        self._on_discover = callback
+
+    async def start(self):
+        self._running = True
+        loop = asyncio.get_running_loop()
+        transport: asyncio.DatagramTransport | None = None
+
+        class Proto(asyncio.DatagramProtocol):
+            def connection_made(self, t):
+                nonlocal transport
+                transport = t
+                sock = t.get_extra_info("socket")
+                if sock is not None:
+                    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+
+            def datagram_received(self, data: bytes, addr):
+                if not data.startswith(DISCOVERY_MAGIC):
+                    return
+                payload = data[len(DISCOVERY_MAGIC) + 1:]
+                try:
+                    info = DiscoveryInfo.from_bytes(payload)
+                    key = f"{info.ip}:{info.port}"
+                    if key not in self._seen:
+                        self._seen.add(key)
+                        log.debug("discovered: %s", info)
+                        if self._on_discover:
+                            self._on_discover(info)
+                except Exception as e:
+                    log.debug("bad discovery packet from %s: %s", addr, e)
+
+            def error_received(self, exc):
+                log.warning("discovery listener error: %s", exc)
+
+        try:
+            _, _ = await loop.create_datagram_endpoint(
+                Proto,
+                local_addr=("0.0.0.0", DISCOVERY_PORT),
+                allow_broadcast=True,
+            )
+            log.info("discovery listener started on port %s", DISCOVERY_PORT)
+            while self._running:
+                await asyncio.sleep(1)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            if transport:
+                transport.close()
+
+    def stop(self):
+        self._running = False
+
+    def reset_seen(self):
+        self._seen.clear()