mkonion is a very simple tool to allow you to set up a Tor Onion Service (also known as a Tor Hidden Service) for an existing Docker container. It takes advantage of docker inspect and other such features to figure out what ports you might want to add to your hidden service. I have plans to allow you to create multiple hidden services for a single container (I'm not sure why, but someone is bound to need that).

The point of this project is for this to be as turn-key as possible, in order to make it as easy as possible for people to try out Tor Onion Services with their existing Docker setup.

The basic usage is the following:

% mkonion [-k private_key] [-p [onion:]container]... <container>

Simple as that. You don't need to have any Tor setup, as mkonion includes inside it all of the required Dockerfile and configuration information to set up a new Tor container. If you want to take a closer look, check out fakebuild.go.

mkonion depends on first-class networking in the Docker daemon, which means your Docker daemon must be at least version 1.9.0. Any earlier versions could be made to work with some hacks, but without first-class networking it can't work reliably and easily.

It's recommended to route all of your main container's traffic exclusively through Tor (using the Tor networking driver), so if your service gets hacked the attacker cannot effectively retrieve your external IP address.

If you're planning to use this on a service which requires server anonymity as a constraint, ensure that you remove all uniquely identifying information. Running your service in Tor masks your IP address in some senses, if you route all of the traffic through Tor. But you should also take steps to configure your server to not leak information, as well as reducing how easily your writing can be fingerprinted.

Basically, mkonion automates the following steps:

1. Create a new bridge network, connect the target container to the network.
2. Generate a torrc which defines a Tor Onion Service that forwards all of the exposed ports of the target container to the new network's IP for the target.
3. Start a new Tor daemon in middle relay mode in a container connected to the new network.

You could in principle emulate mkonion with something like:

% docker network create --driver=bridge mkonion
% docker network connect mkonion <target>
% # Manually create a new torrc based on this:
% docker inspect <target>
% docker build -t <tor image> .
% docker run --net=mkonion <tor image>

But who wants all of that typing?

There are multiple reasons, the first and foremost being that it is (from my understanding of the underlying technology) much more privacy-preserving for your end users. If a user wants to access your website using Tor and you don't have a problem with that, you should provide an onion address because it will protect them from certain passive surveillance attacks (as well as misconfigurations that cause them to accidentally connect directly to your service).

However, there are other cool reasons to use Tor Onion Services:

• NAT Punching means that you can connect to a Tor Onion Service even if it is hosted behind a NAT. This is an incredibly useful feature (you can access your internal services from the internet with much fewer problems than port-forwarding what you need).

• Your host can be hidden, as the current incarnation of Tor Onion Service sets up a full Tor circuit for all three introduction points, the HSDir nodes and the rendezvous node. This results in both the client and server having quite good anonymity properties (although the server's anonymity properties are known to be weaker than the client, because the server can be coerced to send data through its Tor circuits).

• By making more services available through .onion addresses, Tor Onion Services become more normalised and people are far less suspicious of such addresses. This is critical for the movement for online privacy, making people aware of the benefits of Tor and of .onion addressing.

Most importantly, because this project is so simple to use and is self-contained, you lose nothing by starting this up on your services. At the very least, I hope you'll try this out on your local machine so you can access your local dockerised services from the internet using Tor.

This project is licensed under the MPLv2 License, which allows people to vendor this code into a non-GPL project without compromising the protection of the copyleft of users.

mkonion: create a Tor onion service for existing Docker containers
Copyright (C) 2016 Aleksa Sarai <cyphar@cyphar.com>

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.