Home

Awesome

mkonion

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.

Usage

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.

Requirements

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.

Recommendations

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.

Overview

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?

Why Onion Services?

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:

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.

License

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