revpty 0.5.7__tar.gz

revpty-0.5.7/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: revpty
+Version: 0.5.7
+Summary: Reverse PTY shell over WebSocket
+Author: ddmonster
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp
+
+# revpty
+
+Reverse PTY shell over WebSocket.
+
+## Installation
+
+```bash
+pip install revpty
+```
+
+## Usage
+
+**1. Start server:**
+```bash
+revpty-server --host 0.0.0.0 --port 8765
+```
+
+**2. Start client (on target machine):**
+```bash
+revpty-client --server ws://your-server:8765 --session my-session
+```
+
+**3. Attach to PTY (from your machine):**
+```bash
+revpty-attach --server ws://your-server:8765 --session my-session
+```
+
+## Cloudflare Access Authentication
+
+If your server is protected by Cloudflare Zero Trust with Service Token authentication:
+
+```bash
+revpty-client --server wss://your-server:8765 --session my-session \
+    --cf-client-id YOUR_CLIENT_ID.access \
+    --cf-client-secret YOUR_CLIENT_SECRET
+```
+
+Same for attach:
+```bash
+revpty-attach --server wss://your-server:8765 --session my-session \
+    --cf-client-id YOUR_CLIENT_ID.access \
+    --cf-client-secret YOUR_CLIENT_SECRET
+```
+
+The client will send `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers during WebSocket connection.
+
+## Features
+
+- WebSocket-based PTY relay
+- Session-based routing
+- Reconnect support
+- HTTP proxy support for client
+- Cloudflare Access Service Token authentication
+- Minimal architecture

revpty-0.5.7/README.md

@@ -0,0 +1,54 @@
+# revpty
+
+Reverse PTY shell over WebSocket.
+
+## Installation
+
+```bash
+pip install revpty
+```
+
+## Usage
+
+**1. Start server:**
+```bash
+revpty-server --host 0.0.0.0 --port 8765
+```
+
+**2. Start client (on target machine):**
+```bash
+revpty-client --server ws://your-server:8765 --session my-session
+```
+
+**3. Attach to PTY (from your machine):**
+```bash
+revpty-attach --server ws://your-server:8765 --session my-session
+```
+
+## Cloudflare Access Authentication
+
+If your server is protected by Cloudflare Zero Trust with Service Token authentication:
+
+```bash
+revpty-client --server wss://your-server:8765 --session my-session \
+    --cf-client-id YOUR_CLIENT_ID.access \
+    --cf-client-secret YOUR_CLIENT_SECRET
+```
+
+Same for attach:
+```bash
+revpty-attach --server wss://your-server:8765 --session my-session \
+    --cf-client-id YOUR_CLIENT_ID.access \
+    --cf-client-secret YOUR_CLIENT_SECRET
+```
+
+The client will send `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers during WebSocket connection.
+
+## Features
+
+- WebSocket-based PTY relay
+- Session-based routing
+- Reconnect support
+- HTTP proxy support for client
+- Cloudflare Access Service Token authentication
+- Minimal architecture

revpty-0.5.7/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "revpty"
+version = "0.5.7"
+description = "Reverse PTY shell over WebSocket"
+authors = [{name = "ddmonster"}]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["aiohttp"]
+
+[project.scripts]
+revpty-server = "revpty.cli.main:server"
+revpty-client = "revpty.cli.main:client"
+revpty-attach = "revpty.cli.main:attach_cmd"
+
+[tool.setuptools.package-data]
+revpty = ["server/static/*"]

revpty-0.5.7/revpty/__init__.py

@@ -0,0 +1,3 @@
+"""revpty: Programmable Shell Runtime over WebSocket"""
+
+__version__ = "0.5.7"

revpty-0.5.7/revpty/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entry points"""

revpty-0.5.7/revpty/cli/attach.py

@@ -0,0 +1,308 @@
+import asyncio
+import logging
+import aiohttp
+import os
+from aiohttp import WSMsgType
+import sys
+import tty
+import termios
+import os
+import random
+import time
+import json
+import uuid
+from enum import Enum
+import signal
+from select import select
+
+from revpty.protocol.frame import Frame, FrameType
+from revpty.protocol.codec import encode, decode
+
+
+_level_name = os.getenv("LOG_LEVEL", "INFO").upper()
+_level = getattr(logging, _level_name, logging.INFO)
+logging.basicConfig(
+    level=_level,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+class AttachState(Enum):
+    INIT = "init"
+    ATTACH_SENT = "attach_sent"
+    ACTIVE = "active"
+    DETACHED = "detached"
+    CLOSED = "closed"
+
+
+class InteractiveTerminal:
+    def __init__(self, ws, session: str, attach_id: str):
+        self.ws = ws
+        self.session = session
+        self.attach_id = attach_id
+        self._old_tty = None
+        self._running = True
+        self._detached_by_user = False
+        self._status_event = asyncio.Event()
+        self._last_output = None
+        self.state = AttachState.INIT
+        self._sigwinch_enabled = False
+
+    # ---------- TTY handling ----------
+
+    def setup_terminal(self):
+        if not sys.stdin.isatty():
+            return
+        self._old_tty = termios.tcgetattr(sys.stdin)
+        tty.setraw(sys.stdin.fileno())
+
+    def restore_terminal(self):
+        if self._old_tty:
+            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self._old_tty)
+            print()
+
+    # ---------- Protocol helpers ----------
+
+    async def send_frame(self, frame: Frame):
+        await self.ws.send_str(encode(frame))
+
+    # ---------- Main loop ----------
+
+    async def run(self):
+        self.setup_terminal()
+        loop = asyncio.get_running_loop()
+
+        logger.info(f"[+] Attached to session '{self.session}'")
+        logger.info("[*] Press Ctrl+] to detach")
+
+        try:
+            ws_task = asyncio.create_task(self._read_from_ws())
+            await self.send_frame(
+                Frame(
+                    session=self.session,
+                    role="browser",
+                    type="attach",
+                )
+            )
+            self.state = AttachState.ATTACH_SENT
+            await self._send_resize()
+            if sys.stdin.isatty():
+                loop.add_signal_handler(signal.SIGWINCH, lambda: asyncio.create_task(self._send_resize()))
+                self._sigwinch_enabled = True
+
+            try:
+                await asyncio.wait_for(self._status_event.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                logger.warning("[!] Attach status timeout")
+            self.state = AttachState.ACTIVE
+            if self._last_output is None:
+                await self.send_frame(Frame(
+                    session=self.session,
+                    role="browser",
+                    type=FrameType.INPUT.value,
+                    data=b"\n",
+                ))
+
+            stdin_task = asyncio.create_task(self._read_from_stdin())
+            heartbeat_task = asyncio.create_task(self._heartbeat())
+
+            done, pending = await asyncio.wait(
+                {ws_task, stdin_task, heartbeat_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for task in pending:
+                task.cancel()
+
+        except KeyboardInterrupt:
+            logger.info("\n[*] Interrupted by user")
+
+        except Exception as e:
+            logger.error(f"[x] Terminal error: {e}")
+
+        finally:
+            try:
+                await self.send_frame(
+                    Frame(
+                        session=self.session,
+                        role="browser",
+                        type="detach",
+                    )
+                )
+            except Exception:
+                pass
+            self.state = AttachState.DETACHED
+            self.restore_terminal()
+            logger.info(f"[-] Detached from session '{self.session}'")
+            if self._sigwinch_enabled:
+                loop.remove_signal_handler(signal.SIGWINCH)
+        
+        self.state = AttachState.CLOSED
+        return "user_detach" if self._detached_by_user else "ws_closed"
+
+    # ---------- WS → stdout ----------
+
+    async def _read_from_ws(self):
+        try:
+            async for msg in self.ws:
+                if msg.type == WSMsgType.TEXT:
+                    frame = decode(msg.data)
+
+                    if frame.type == FrameType.OUTPUT.value:
+                        sys.stdout.buffer.write(frame.data)
+                        sys.stdout.buffer.flush()
+                        self._last_output = time.time()
+                    elif frame.type == FrameType.PING.value:
+                        await self.send_frame(Frame(
+                            session=self.session,
+                            role="browser",
+                            type=FrameType.PONG.value,
+                        ))
+                    elif frame.type == FrameType.STATUS.value:
+                        self._status_event.set()
+                        try:
+                            payload = json.loads(frame.data.decode("utf-8")) if frame.data else {}
+                            logger.info(f"[*] Attach status: {payload}")
+                        except Exception:
+                            logger.info("[*] Attach status received")
+
+                elif msg.type == WSMsgType.CLOSED:
+                    logger.warning("\r[!] Connection closed by server")
+                    break
+
+                elif msg.type == WSMsgType.ERROR:
+                    logger.error(f"\r[x] WebSocket error: {self.ws.exception()}")
+                    break
+
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"\r[x] WS read error: {e}")
+
+    # ---------- stdin → WS ----------
+
+    async def _read_from_stdin(self):
+        fd = sys.stdin.fileno()
+        loop = asyncio.get_running_loop()
+
+        try:
+            while True:
+                # wait for stdin readable
+                await loop.run_in_executor(None, select, [fd], [], [])
+
+                data = os.read(fd, 1024)
+                if not data:
+                    break
+
+                # Ctrl+] detach
+                if b"\x1d" in data:
+                    logger.info("\n[*] Detaching from session...")
+                    self._detached_by_user = True
+                    break
+
+                await self.send_frame(
+                    Frame(
+                        session=self.session,
+                        role="browser",
+                        type=FrameType.INPUT.value,
+                        data=data,
+                    )
+                )
+
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"\r[x] stdin read error: {e}")
+
+    async def _send_resize(self):
+        if not sys.stdin.isatty():
+            return
+        size = os.get_terminal_size(sys.stdin.fileno())
+        await self.send_frame(Frame(
+            session=self.session,
+            role="browser",
+            type=FrameType.RESIZE.value,
+            rows=size.lines,
+            cols=size.columns,
+        ))
+
+    async def _heartbeat(self, interval: int = 20):
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                await self.send_frame(Frame(
+                    session=self.session,
+                    role="browser",
+                    type=FrameType.PING.value,
+                ))
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"\r[x] heartbeat error: {e}")
+
+
+# ---------- Public API ----------
+
+async def attach(server: str, session: str, proxy: str | None = None, secret: str | None = None,
+                 cf_client_id: str | None = None, cf_client_secret: str | None = None):
+    proxy_info = f" via {proxy}" if proxy else ""
+    logger.info(f"[*] Connecting to {server}{proxy_info}")
+    attach_id = uuid.uuid4().hex[:10]
+    attempt = 0
+    retry_delay = 0  # immediate first retry
+    last_connected_at = 0
+    metrics = {
+        "attach_id": attach_id,
+        "attempts": 0,
+        "failures": 0,
+        "start_ms": round(time.time() * 1000),
+    }
+
+    while True:
+        attempt += 1
+        metrics["attempts"] = attempt
+        try:
+            timeout = aiohttp.ClientTimeout(
+                total=30,
+                connect=10,
+                sock_connect=10,
+                sock_read=30
+            )
+            async with aiohttp.ClientSession(timeout=timeout) as http_session:
+                headers = {}
+                if secret:
+                    headers["X-Revpty-Secret"] = secret
+                if cf_client_id and cf_client_secret:
+                    headers["CF-Access-Client-Id"] = cf_client_id
+                    headers["CF-Access-Client-Secret"] = cf_client_secret
+                if not headers:
+                    headers = None
+                async with http_session.ws_connect(server, proxy=proxy, headers=headers, heartbeat=30) as ws:
+                    last_connected_at = time.time()
+                    term = InteractiveTerminal(ws, session, attach_id)
+                    result = await term.run()
+                    if result == "user_detach":
+                        break
+        except aiohttp.ClientError as e:
+            metrics["failures"] += 1
+            logger.error(f"[x] Connection failed: {e}")
+        except Exception as e:
+            metrics["failures"] += 1
+            logger.error(f"[x] Unexpected error: {e}")
+        if last_connected_at > 0 and (time.time() - last_connected_at) > 60:
+            retry_delay = 0
+            last_connected_at = 0
+        if retry_delay > 0:
+            logger.info(f"[*] Reconnecting in {retry_delay:.1f}s...")
+            await asyncio.sleep(retry_delay)
+        else:
+            logger.info("[*] Reconnecting immediately...")
+        if retry_delay == 0:
+            retry_delay = 1
+        else:
+            retry_delay = min(retry_delay * 2, 10) + random.uniform(0, retry_delay * 0.3)
+
+    logger.info("[*] Attach session ended")
+    logger.info(f"[*] attach metrics: {metrics}")

revpty-0.5.7/revpty/cli/main.py

@@ -0,0 +1,155 @@
+import argparse
+import asyncio
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from revpty.server.app import run as run_server
+from revpty.client.agent import Agent
+from revpty.cli.attach import attach
+
+
+def convert_to_ws_url(url):
+    """Convert http/https URL to ws/wss"""
+    url = url.strip()
+    
+    # If already ws:// or wss://, return as-is
+    if url.startswith('ws://') or url.startswith('wss://'):
+        return url
+    
+    # Convert http:// to ws://
+    if url.startswith('http://'):
+        return url.replace('http://', 'ws://', 1)
+    
+    # Convert https:// to wss://
+    if url.startswith('https://'):
+        return url.replace('https://', 'wss://', 1)
+    
+    # Default to ws:// if no scheme specified
+    if not url.startswith(('http://', 'https://', 'ws://', 'wss://')):
+        return f'ws://{url}'
+    
+    return url
+
+
+def _resolve_executable(name: str) -> str:
+    path = shutil.which(name)
+    if path:
+        return path
+    if sys.argv[0].endswith(name):
+        return sys.argv[0]
+    return name
+
+
+def _install_systemd(service_name: str, exec_args: list[str], user_mode: bool = False):
+    if not shutil.which("systemctl"):
+        raise SystemExit("systemctl not found; this command is for systemd-based Linux systems only")
+
+    if user_mode:
+        unit_dir = os.path.expanduser("~/.config/systemd/user")
+        os.makedirs(unit_dir, exist_ok=True)
+        unit_path = os.path.join(unit_dir, f"{service_name}.service")
+        wanted_by = "default.target"
+    else:
+        if os.geteuid() != 0:
+            raise SystemExit("run as root to install systemd service (or use --user for user-level)")
+        unit_path = f"/etc/systemd/system/{service_name}.service"
+        wanted_by = "multi-user.target"
+
+    env_lines = []
+    log_level = os.getenv("LOG_LEVEL")
+    if log_level:
+        env_lines.append(f"Environment=LOG_LEVEL={log_level}")
+    unit = "\n".join([
+        "[Unit]",
+        f"Description={service_name}",
+        "After=network.target",
+        "",
+        "[Service]",
+        "Type=simple",
+        *env_lines,
+        f"ExecStart={' '.join(shlex.quote(arg) for arg in exec_args)}",
+        "Restart=always",
+        "RestartSec=1",
+        "",
+        "[Install]",
+        f"WantedBy={wanted_by}",
+        "",
+    ])
+    with open(unit_path, "w") as f:
+        f.write(unit)
+    systemctl = ["systemctl", "--user"] if user_mode else ["systemctl"]
+    subprocess.run([*systemctl, "daemon-reload"], check=True)
+    subprocess.run([*systemctl, "enable", "--now", service_name], check=True)
+
+
+def server():
+    p = argparse.ArgumentParser()
+    p.add_argument("--host", default="0.0.0.0")
+    p.add_argument("--port", type=int, default=8765)
+    p.add_argument("--secret", "--seceret", dest="secret", default=None)
+    p.add_argument("--install", action="store_true")
+    p.add_argument("--user", action="store_true", help="Install as user-level systemd service")
+    p.add_argument("--cache-size", type=int, default=131072, help="Output cache size in bytes (default: 131072 = 128KB)")
+    args = p.parse_args()
+    if args.install:
+        exe = _resolve_executable("revpty-server")
+        cmd = [exe, "--host", args.host, "--port", str(args.port)]
+        if args.secret:
+            cmd += ["--secret", args.secret]
+        if args.cache_size != 131072:
+            cmd += ["--cache-size", str(args.cache_size)]
+        _install_systemd("revpty-server", cmd, user_mode=args.user)
+        return
+    run_server(args.host, args.port, secret=args.secret, cache_size=args.cache_size)
+
+
+def client():
+    p = argparse.ArgumentParser()
+    p.add_argument("--server", required=True, help="Server URL (auto-converts http/https to ws/wss)")
+    p.add_argument("--session", required=True, help="Session name")
+    p.add_argument("--proxy", default=None, help="HTTP proxy URL")
+    p.add_argument("--secret", "--seceret", dest="secret", default=None)
+    p.add_argument("--cf-client-id", dest="cf_client_id", default=None, help="Cloudflare Access Client ID")
+    p.add_argument("--cf-client-secret", dest="cf_client_secret", default=None, help="Cloudflare Access Client Secret")
+    p.add_argument("--exec", default=None, help="Command to execute (e.g. /bin/bash)")
+    p.add_argument("--install", action="store_true")
+    p.add_argument("--user", action="store_true", help="Install as user-level systemd service")
+    args = p.parse_args()
+
+    ws_url = convert_to_ws_url(args.server)
+    if args.install:
+        exe = _resolve_executable("revpty-client")
+        cmd = [exe, "--server", args.server, "--session", args.session]
+        if args.proxy:
+            cmd += ["--proxy", args.proxy]
+        if args.secret:
+            cmd += ["--secret", args.secret]
+        if args.cf_client_id:
+            cmd += ["--cf-client-id", args.cf_client_id]
+        if args.cf_client_secret:
+            cmd += ["--cf-client-secret", args.cf_client_secret]
+        if args.exec:
+            cmd += ["--exec", args.exec]
+        _install_systemd("revpty-client", cmd, user_mode=args.user)
+        return
+
+    shell = args.exec or "/bin/bash"
+    asyncio.run(Agent(ws_url, args.session, shell=shell, proxy=args.proxy, secret=args.secret,
+                      cf_client_id=args.cf_client_id, cf_client_secret=args.cf_client_secret).run())
+
+
+def attach_cmd():
+    p = argparse.ArgumentParser()
+    p.add_argument("--server", required=True, help="Server URL (auto-converts http/https to ws/wss)")
+    p.add_argument("--session", required=True, help="Session name")
+    p.add_argument("--proxy", default=None, help="HTTP proxy URL")
+    p.add_argument("--secret", "--seceret", dest="secret", default=None)
+    p.add_argument("--cf-client-id", dest="cf_client_id", default=None, help="Cloudflare Access Client ID")
+    p.add_argument("--cf-client-secret", dest="cf_client_secret", default=None, help="Cloudflare Access Client Secret")
+    args = p.parse_args()
+
+    ws_url = convert_to_ws_url(args.server)
+    asyncio.run(attach(ws_url, args.session, proxy=args.proxy, secret=args.secret,
+                       cf_client_id=args.cf_client_id, cf_client_secret=args.cf_client_secret))

revpty-0.5.7/revpty/client/__init__.py

@@ -0,0 +1 @@
+"""Client agent for PTY management"""