Index
This is the full documentation of ADAPT - Accelerated Development & Adaption of Pluggable Transports. It'll help you get started with developing Tor Pluggable Transports while trying to avoid as much Tor-Specific headaches as possible so you can focus on your Implementation and not be at the mercy of the Tor-Network having a good or bad day.
Abbreviations
There are several terms and abbreviations used in this documentation. For clarity, they are listed here:
PT - Pluggable Transport
PT-client - The part of the PT, which is running on the user's machine
PT-bridge - In documentation also often referred to as 'PT-server', but for clarity in this project always referred to as 'PT-bridge' is the part of the PT, which is running on a server and acts as a bridge into the Tor network.
PPT - Python Pluggable Transport. This is name of the framework for easily building pluggable transports, implemented in this project.
Where do I find what?
The documentation is split into several parts:
General Information: This section talks about the theory behind Pluggable Transports and provides important foundational knowledge for implementing PTs. It also provides specific implementation examples which can be generalized for any type of deployment.
Local Hosting: Here's all the Info about locally hosting and using PTs.
Docker: Here's everything regarding PTs hosted fully under docker. Note that hosting a client under docker and a bridge locally and vice versa is possible.
Shadow: This is the full documentation for the Shadow Network Simulator. It provides developers with a very quick, easy and most importantly deterministic way of testing their PTs without having to rely on the whims of the Tor-Network.
Python Pluggable Transport: This piece of documentation contains information on the Python Pluggable Transport, which can either help you understand and implement Pluggable Transports in another programming language or implement a Pluggable Transport within the framework very quickly and easily (for simple transports in as few as 13 lines of code!).
Project layout
The following shows the Layout of the Project. Relevant files have small comments behind them to tell you what they roughly are. Important files will have their documentation pages linked.
.github/
├── workflows/
│ └── ci.yml # CI-Config for deploying the documentation page.
docker_deployment/
├── bridge/
│ ├── dockerfile # Dockerfile for the Tor Pluggable Transport bridge under Docker.
│ ├── entrypoint.sh # Entrypoint script, executed by the container when it starts.
│ └── torrc # Tor config for the docker bridge.
├── client/
│ ├── dockerfile # Dockerfile for the Tor Pluggable Transport client under Docker.
│ ├── entrypoint.sh # Entrypoint script, executed by the container when it starts.
│ └── torrc # Tor config for the docker client.
├── bridge-logs.sh # Live view of the docker bridge's logs.
├── client-logs.sh # Live view of the docker client's logs.
└── docker-compose.yml # Compose file for easily starting the containers.
docs/
├── index.md # Full documentation title page.
└── [Further Documentation]
local_deployment/
├── bridge-torrc # Tor config for locally running the pluggable transport bridge.
├── client-torrc # Tor config for locally running the pluggable transport client.
├── run-bridge.sh # A script for locally running the pluggable transport bridge.
└── run-client.sh # A script for locally running the pluggable transport client.
pythonPluggableTransport
├── dist/ # Output directory for PyInstaller. This directory is generated once 'build.sh' is run and should not be committed to git
│ └── ppt # ELF binary including the transports to be used by tor or shadow. Generated by 'build.sh'
├── helpers/ # Boilerplate code for running a Pluggable Transport
│ ├── __init__.py # __init__.py to tell Python that this directory is a package
│ ├── config.py # Configuration parser functions as well as a dataclass to store the config
│ ├── ipc.py # Inter process communication to cleanly talk to tor
│ ├── pt_client.py # Logic to run a connection as pt-client
│ ├── pt_bridge.py # Logic to run a connection as pt-bridge
│ ├── relay.py # Wiring of dataflow (bidirectional between pt-wire and tor, including handeling of de-/encryption)
│ ├── socks5.py # SOCKS5 connection logic
│ └── transport.py # Blueprint for how a generic transport has to look
├── transports/
│ ├── __init__.py # Register the directory as a package and import all transports to fire @register decorators
│ ├── foobar.py # 'foobar' transport, which replaces any binary 1 with a "foo" and any binary 0 with a "bar". Inefficient but pretty to look at in wireshark.
│ ├── invert.py # 'invert' transports, that XORs data with 0xFF thus inverting every bit.
│ └── [further transports].py # any self built transports go here and have to be imported in this directory's __init__.py
├── build.sh # Script to build a binary of the transports to be used in deployment
├── main.py # Entrypoint for the PPT
├── ppt.spec # PyInstaller build specification to correctly build the binary
└── test_pt.py # Testscript to quickly validate the integrity of a pluggable transport without having to build the binary
shadow/
├── conf/ # A ton of shadow configuration. Taken directly from the examples in the Shadow Git repo.
│ └── [...]
├── shadow.data.template/ # Config for all the nodes in the Shadow network, many taken from the examples in the Shadow Git repo.
│ └── [...]
├── lyrebird # The executable for lyrebird, a pluggable transport implementing obfs3 and obfs4.
├── run_shadow.sh # Convenience script for running the shadow simulation. Automatically clears the last simulation for a clean re-run.
├── shadow.yaml # The main configuration for the Shadow simulator. Includes a description of each node and what they do.
└── topology.gml # The Topology of the Shadow network. Defines which nodes exist and can talk to whom.
.gitignore
mkdocs.yml # Config for the full documentation
readme.md # Basic readme to get started
requirements.txt # Python requirements for building the documentation using mkdocs