marionette

Marionette is a programmable client-server proxy that enables the user to control network traffic features with a lightweight domain-specific language.

⚠️ Pre-alpha software - Not suitable for real-world deployment.

Installation

pip install marionette-tg

Quick Start

# Start the SOCKS backend
./examples/socksserver --local_port 8081 &

# Start the marionette server
./bin/marionette_server --server_ip 127.0.0.1 --proxy_ip 127.0.0.1 --proxy_port 8081 --format dummy &

# Start the marionette client
./bin/marionette_client --server_ip 127.0.0.1 --client_ip 127.0.0.1 --client_port 8079 --format dummy &

# Test the connection
curl --socks4a 127.0.0.1:8079 example.com

Features

• Programmable traffic shaping using a domain-specific language
• Format-Transforming Encryption (FTE) for protocol obfuscation
• Template grammars for generating realistic traffic patterns
• Pluggable architecture for custom protocol handlers

Documentation

Full documentation, DSL reference, and example formats are available on GitHub.

References

1. Protocol Misidentification Made Easy with Format-Transforming Encryption (CCS 2013)
2. Marionette: A Programmable Network Traffic Obfuscation System (USENIX Security 2015)

License

MIT License - see LICENSE for details.