shellcode_encoder.py

#!/usr/bin/env python3
"""
Exploit-Dev-Toolkit — Shellcode Encoder

A reference tool for shellcode encoding and manipulation techniques.

This module is documentation-first. Run it to see conceptual guides and
usage for XOR encoding, alphanumeric shellcode, and NOP sled techniques.

Usage:
 python shellcode_encoder.py # Print full reference
 python shellcode_encoder.py --xor # XOR encoding reference
 python shellcode_encoder.py --alphanumeric # Alphanumeric reference
 python shellcode_encoder.py --nop # NOP sled reference
 python shellcode_encoder.py --xor-encode <hex> # XOR-encode raw shellcode
 python shellcode_encoder.py --nop-gen <count> # Generate a NOP sled
"""

import argparse
import random
import struct
import sys


HELP_XOR = """
╔══════════════════════════════════════════════════════════════════════╗
║ XOR Encoding ║
╚══════════════════════════════════════════════════════════════════════╝

Concept:
 XOR encoding transforms shellcode by XOR-ing each byte with a single
 key byte (or multi-byte key). A small decoder stub placed before the
 encoded payload re-XORs every byte at runtime to restore the original.

 This evades signature-based detection because the encoded payload
 looks like random bytes rather than known shellcode patterns.

Single-byte XOR:
 Encoded[i] = Shellcode[i] XOR Key
 Shellcode[i] = Encoded[i] XOR Key (XOR is its own inverse)

 Decoder stub (NASM x86):
 xor_decode:
 pop esi ; address of encoded shellcode
 xor ecx, ecx
 mov cl, LENGTH ; shellcode length
 loop:
 xor byte [esi+ecx-1], KEY
 loop loop
 jmp esi

Multi-byte XOR (rolling key):
 Encoded[i] = Shellcode[i] XOR Key[i % key_len]

 Harder to detect; decoder stub loops through key bytes.

Pitfalls:
 - Null bytes (0x00) in the decoder stub may break string-based exploits.
 - Key 0x00 = no encoding (avoid).
 - Key choice matters: a key equal to common bytes (e.g., 0x90 for NOP)
 may produce many nulls in output.

Tools / Libraries:
 - msfvenom: msfvenom -p linux/x64/exec ... -e x86/xor_mixed
 - pwntools: from pwn import *; encoded = xor(shellcode, key)
 - Custom: provided by --xor-encode below
"""


HELP_ALPHANUMERIC = """
╔══════════════════════════════════════════════════════════════════════╗
║ Alphanumeric Shellcode ║
╚══════════════════════════════════════════════════════════════════════╝

Concept:
 Alphanumeric (aka printable) shellcode consists only of bytes in the
 ASCII printable range (0x20–0x7E). This allows the payload to pass
 through filters that reject non-printable characters — common in
 input validation, WAFs, and some protocol parsers.

 The constraint is severe: only ~95 byte values out of 256 are allowed.
 This means the decoder stub itself must be alphanumeric.

Techniques:
 1. SUB / ADD / XOR with alphanumeric immediates
 - On x86, SUB EAX, 0x3D3D3D3D is printable.
 - Chain enough arithmetic to build arbitrary values.

 2. Self-modifying alphanumeric code
 - Write non-printable bytes into memory using only printable
 instructions, then jump to the reconstructed shellcode.

 3. Use of INC/ DEC / PUSH / POP variants that fall in the printable range:
 - 0x50–0x57: PUSH register (printable: PUSH EAX = 0x50 ... PUSH EDI)
 - 0x58–0x5F: POP register (POP EAX = 0x58 ... POP EDI)
 - 0x6A: PUSH imm8
 - 0x68: PUSH imm32

Generating alphanumeric shellcode:
 - msfvenom: msfvenom -p windows/exec CMD=calc -e x86/alpha_mixed
 - ADMmutate (older)
 - Custom encoder walking the XOR/ADD/SUB spiral

Pitfalls:
 - Alphanumeric shellcode is typically 3–10x larger than the original.
 - Only well-studied for x86 32-bit; x64 support is more limited.
 - Some filters reject uppercase vs lowercase, shrinking the pool further.
"""


HELP_NOP = """
╔══════════════════════════════════════════════════════════════════════╗
║ NOP Sleds ║
╚══════════════════════════════════════════════════════════════════════╝

Concept:
 A NOP sled (NOP slide) is a sequence of no-operation instructions
 placed before the shellcode in a buffer overflow exploit. When the
 instruction pointer lands anywhere in the sled, it slides forward
 until it hits the actual shellcode.

 This dramatically increases reliability: instead of needing an exact
 return-address hit, *any* address within the sled will work.

Common NOP instructions:

 x86 / x64:
 Byte | Mnemonic
 ──────┼────────────────────
 0x90 | NOP (1 byte)
 0x66 | operand-size override prefix (harmless in sled)
 0x90 | repeated = long NOP sled

 Multi-byte NOP-like instructions (undirected, no side effects):
 0x87 0xDB | XCHG EAX, EBX
 0x96 | XCHG EAX, ESI
 0x97 | XCHG EAX, EDI
 0x42 | INC EDX (safe if EDX value doesn't matter)
 0x40 | INC EAX (safe if EAX value doesn't matter)

 Modern compilers emit multi-byte NOPs for alignment:
 0x66 0x90 | 2-byte NOP
 0x0F 0x1F 0x00 | 3-byte NOP
 0x0F 0x1F 0x40 0x00 | 4-byte NOP
 0x0F 0x1F 0x44 0x00 0x00 | 5-byte NOP

Evasion with NOP sleds:
 - Use different NOP-like instructions to evade NOP-sled signatures.
 - Interleave decoded multi-byte NOPs to avoid byte-level pattern match.
 - Randomize sled instructions per-run to break static signatures.

Example payload layout:
 [AAAA...padding...] [return_addr] [NOP SLED] [SHELLCODE]
"""


def xor_encode(shellcode_hex: str, key: int = 0x55) -> str:
 """
 XOR-encode shellcode given as hex string.
 Returns hex string of encoded shellcode.
 """
 try:
 raw = bytes.fromhex(shellcode_hex)
 except ValueError:
 print(f"[!] Invalid hex string: {shellcode_hex}")
 sys.exit(1)

 if key < 0 or key > 255:
 print(f"[!] Key must be 0-255, got {key}")
 sys.exit(1)

 encoded = bytes([b ^ key for b in raw])
 return encoded.hex()


def generate_nop_sled(count: int, variant: str = "basic") -> str:
 """
 Generate a NOP sled of `count` bytes, as a hex string.
 Variants: basic (0x90), mixed (random NOP-like), multi-byte
 """
 if count < 1:
 return ""

 # Single-byte NOP-like instructions
 NOP_BYTES = [0x90, 0x42, 0x40, 0x96, 0x97, 0x50, 0x58]

 # Multi-byte NOP sequences
 MULTI_NOPS = [
 bytes([0x66, 0x90]),
 bytes([0x0F, 0x1F, 0x00]),
 bytes([0x0F, 0x1F, 0x40, 0x00]),
 bytes([0x0F, 0x1F, 0x44, 0x00, 0x00]),
 ]

 if variant == "basic":
 sled = bytes([0x90] * count)
 elif variant == "mixed":
 parts = []
 remaining = count
 while remaining > 0:
 b = random.choice(NOP_BYTES)
 parts.append(bytes([b]))
 remaining -= 1
 sled = b"".join(parts)
 elif variant == "multi":
 parts = []
 remaining = count
 while remaining > 0:
 chosen = random.choice(MULTI_NOPS)
 if len(chosen) <= remaining:
 parts.append(chosen)
 remaining -= len(chosen)
 else:
 parts.append(bytes([0x90]))
 remaining -= 1
 sled = b"".join(parts)
 else:
 print(f"[!] Unknown variant: {variant} (use: basic, mixed, multi)")
 sys.exit(1)

 return sled.hex()


def main():
 parser = argparse.ArgumentParser(
 description="Exploit-Dev-Toolkit — Shellcode Encoder Reference"
 )

 group = parser.add_mutually_exclusive_group()
 group.add_argument("--xor", action="store_true", help="Show XOR encoding reference")
 group.add_argument("--alphanumeric", action="store_true", help="Show alphanumeric shellcode reference")
 group.add_argument("--nop", action="store_true", help="Show NOP sled reference")
 group.add_argument("--xor-encode", metavar="HEX_SHELLCODE", help="XOR-encode shellcode (hex input)")
 group.add_argument("--nop-gen", metavar="COUNT", type=int, help="Generate a NOP sled of COUNT bytes")

 parser.add_argument("--key", type=int, default=0x55, help="XOR key (0-255, default: 0x55)")
 parser.add_argument("--variant", default="basic", choices=["basic", "mixed", "multi"],
 help="NOP sled variant (default: basic)")

 args = parser.parse_args()

 if args.xor:
 print(HELP_XOR)
 elif args.alphanumeric:
 print(HELP_ALPHANUMERIC)
 elif args.nop:
 print(HELP_NOP)
 elif args.xor_encode:
 result = xor_encode(args.xor_encode, args.key)
 print(f"Original: {args.xor_encode}")
 print(f"Key: 0x{args.key:02x} ({args.key})")
 print(f"Encoded: {result}")
 print(f"Length: {len(bytes.fromhex(result))} bytes")
 elif args.nop_gen:
 result = generate_nop_sled(args.nop_gen, args.variant)
 print(f"NOP sled ({args.nop_gen} bytes, variant: {args.variant}):")
 print(result)
 else:
 print(HELP_XOR)
 print(HELP_ALPHANUMERIC)
 print(HELP_NOP)
 print()
 print("─" * 66)
 print("Quick reference: run with --xor, --alphanumeric, --nop,")
 print("--xor-encode <hex>, or --nop-gen <count>")


if __name__ == "__main__":
 main()