# The Vanguards Onion Service Addon

[![Build Status](https://travis-ci.org/mikeperry-tor/vanguards.png?branch=master)](https://travis-ci.org/mikeperry-tor/vanguards) [![Coverage Status](https://coveralls.io/repos/github/mikeperry-tor/vanguards/badge.png?branch=master)](https://coveralls.io/github/mikeperry-tor/vanguards?branch=master)

Even after deployment of the [new v3 onion service
protocol](https://gitweb.torproject.org/torspec.git/tree/proposals/224-rend-spec-ng.txt),
the attacks facing onion services are wide-ranging, and still require
more extensive modifications to fix in Tor-core itself.

Because of this, we have decided to rapid-prototype these defenses in a
controller addon in order to make them available ahead of their official
Tor-core release, for onion services that require high security as soon as
possible.

For details about the defenses themselves, please see
[README\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_TECHNICAL.md).

For additional security information, please see
[README\_SECURITY.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md).

# Installation Methods

There are several ways to use this addon. At the moment, the safest is to run
it directly from git.

Packages for popular UNIX-like systems should be available soon.

## Running this addon directly from git

**This is the safest option to use, since it avoids having pip and/or
virtualenv download packages from PYPI without verification.**

1. Retrieve this repository and optionally verify a signed git version tag.
2. [Install Stem](https://stem.torproject.org/download.html)
3. Run **./src/vanguards.py**

If your control port is on an alternate IP and Port, specify that with
**--control_host _IP_ --control_port _portnum_**.

If you are using a control socket, specify its full path with
**--control_socket /path/to/socket**.

Note that **./src/vanguards.py** has several other options under **--help**.

## Using VirtualEnv

**This option tells virtualenv not to download packages, and only downloads
pip packages with --require-hashes. It should be safe.**

To install Stem and Vanguards into their own python virtualenv, run:

```
torsocks ./setup.sh
source vanguardenv/bin/activate
vanguards
```

If you do not want your environment to be in the vanguardenv subdirectory, you
can specify a different directory as an argument to **setup.sh**.

## Pip

This project is also listed on the Python Package Index. To install the
latest release via pip **without any verification**, do:

```
torsocks pip install vanguards
```

# How to use the addon

## Configuration

All of the subsystems of this addon can be tuned via a configuration file.
Check out this documented [example configuration file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf) for more information.

Configuration files can be specified on the command line. The default is to
read **vanguards.conf** from the current working directory. If the environment
variable **$VANGUARDS\_CONFIG** is set, the config file will be read from the
file specified in that variable.

## Onion service use

This addon is primarily intended for onion service operators. To use it,
set up your onion service to expose a control port listener using the
ControlPort or ControlSocket torrc directives:

```
ControlPort 9099             # or ControlSocket /path/to/socket
CookieAuthentication 1
DataDirectory /path/to/tor/datadir
```

and then run:

```
vanguards --control\_port=9099     # (or --control\_socket /path/to/socket).
```

## Client use

It is also possible to use the vanguards addon as a regular Tor client with
Tor Browser or with Onionshare.

To use it with Tor Browser, all you have to do is start Tor Browser, and then run:
```
  ./src/vanguards.py --control_port 9151
```

To use it with Onionshare, set up your Tor to expose a control port and attach
both onionshare and the vanguards addon to it.

## Performance Tuning

For very high traffic onion services, we recommend using
[PyPy](https://pypy.org) instead of CPython. PyPy contains a JIT that should
make this addon run considerably faster.

The easiest way to use PyPy is to do **sudo apt-get install pypy** or
equivalent before running **./setup.sh** as per above. The setup.sh script will
then see that pypy is installed, and use it by default in the resulting
virtualenv.

To switch to pypy after running **setup.sh**, simply remove the vanguardenv
directory and run **setup.sh** again.

If you want to use pypy outside of a virtualenv, install Stem on your system (use 1.5.4 or earlier, since Stem 1.6.0 is [incompatible with pypy at the moment](https://trac.torproject.org/projects/tor/ticket/26207), and then run the addon directly from the source tree with:

```
  pypy ./src/vanguards.py
```

Additionally, you can disable components to reduce processing overhead. Try
disabling Rendguard first. If that is still insufficient, disable Bandguards.

Vanguards by itself should not require much overhead, but if even that is too
much, you can run the following once per hour from cron to update your torrc
with fresh layer2 and layer3 guards:

```
  pypy ./src/vanguards.py --one_shot_vanguards
```

# What do the logs mean?

This is an experimental addon with many heuristics that still need tuning.
Events that represent severe issues are at WARN level. You should
react to these events. Warns are currently emitted for the following
conditions:

1. When your service is disconnected from the Tor network, we WARN. Downtime
can be a side channel signal or a passive information leak,
and you should ensure your Internet connection is reliable to minimize
downtime of your service as much as possible.
2. When a hidden service descriptor circuit sends more than 30KB, we WARN. If this
happens, it is either a bug, a heavily-modified hidden service descriptor,
or an actual attack.
3. When you set ExcludeNodes in Tor to exclude countries, but do not give
Tor a GeoIP file, we WARN.
4. If you disable killing circuits in the rendguard component, we WARN when
use counts for rends are exceeded.
5. With Tor 0.3.4.10 and above, we WARN upon receipt of any dropped/ignored cell.

Events that are detected by heuristics that still need tuning are at NOTICE
level. They may be a bug, a false positive, or an actual attack. If in doubt,
don't panic. Please check the [Github
issues](https://github.com/mikeperry-tor/vanguards/issues/) to see if any
known false positives are related to these lines, and if not, consider filing
an issue. Please redact any relay fingerprints from the messages before
posting.

# What other attacks are there against Onion Services?

In addition to the attacks that the vanguards addon mitigates (which are
documented in
[README\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_TECHNICAL.md)),
there are many other attacks on onion services. Most of these attacks are
theoretical and have not been observed in the wild, but that does not make
them impossible. The attacks that you are at risk for depends upon who is
interested in trying to deanonymize you, and what their capabilities are.

To help make this more clear, we're going to first go through the general
taxonomy of adversaries, along with their capabilities and the types of
attacks they can perform, in the [Adversaries](#adversaries) section.

In the [What can I do to be safer?](#what-can-i-do-to-be-safer) section, we'll
give some specific recommendations that will help defend against these
adversaries.

# Adversaries

Adversaries can be roughly categorized as having one or more of four
positions: [Client](#adversaries-client), [Network](#adversaries-network),
[Local](#adversaries-local), or [Global](#adversaries-global).

Adversaries can have more than one position at the same time, and each of
these positions can be either "**active**", or "**passive**". For brevity, we
do not make heavy use of the **active/passive** distinction in this document.

The adversary may also have additional outside information or suspicions that
can help them mount their attacks.

Each of the adversary subsections below starts with a list of capabilities
that the adversary has, and this list is followed by additional paragraphs
that describe the specific attacks that provide those capabilities. When
relevant, we link to our specific mitigation recommendations from each attack
description paragraph.

We classify each adversary capability using the following action verbs that
describe the scope of that capability:

 1. **Suspect** - When we say **"suspect"** with respect to a capability, that
means that the adversary can perform an attack to obtain this information, but
they will not have high certainty that they are correct. Depending on the
attack, they may end up suspecting a lot of unrelated Tor clients as a result
of their attack. These attacks may also fail to suspect the client that is
actually of interest to them.
 2. **Confirm** - When we say **"confirm"** with respect to a capability,
that means that the adversary is able to use an attack to confirm outside
information, prior suspicion, or speculation with extremely high certainty.
 3. **Determine** - When we say **"determine"** with respect to a capability, that
means that the adversary can perform an attack to obtain the described
information with extremely high certainty in a relatively short amount of
time, if the conditions for the attack are met.

Attacks that merely allow the adversary to **suspect** information are not
typically useful, unless there is also an attack that allows the adversary to
**confirm** that information.

Attacks that allow an adversary to **confirm** information are not useful
unless the adversary has some prior information or suspicion.

Attacks that **determine** information right away are thus more powerful
than attacks that **confirm** information, because they do not require any
prior information or suspicion. They are also more useful to the adversary
than attacks that allow them to **suspect** information, because they provide
a very high degree of certainty.

## Adversaries: Client

Client adversaries are those that attack your onion service using nothing more
than a Tor client and normal internet access.

In addition to nuisances such as DoS attacks, these adversaries can
perform anonymity attacks that provide the following capabilities:

1. **Determine** if a specific onion service is exploitable, and if so, exploit it (possibly learning the IP address).
2. **Determine** if a specific onion service is also listening on a public IP address, by scanning the public internet for it.
3. **Determine** if a specific onion service always goes down at the same time as
a public Tor relay goes down.
4. **Determine** that a specific onion service is running the vanguards addon.
5. **Suspect** that a specific onion service is using [OnionBalance](https://github.com/DonnchaC/onionbalance).
6. **Suspect** that a specific onion service may be using a particular Guard.

Capabilities #1-3 should be self-explanatory.

For capability #4, the client adversary can **determine** that a specific onion
service address is running the vanguards addon by observing how that onion
service behaves. In particular, it can attempt one of the attacks that the
vanguards addon defends against, and see if the onion service closes circuits
in response. In these cases, log lines will be emitted by the vanguards addon
at NOTICE level or above. If you do not want client adversaries to be able to
easily detect this addon, you can set **close_circuits=False** in
[vanguards.conf](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf).
However, a network adversary who runs your Guard node can still **determine**
that you use this addon (see the [network adversary
section](#adversaries-network) for details).

For capability #5, the client adversary can **suspect** that a specific onion
service address is running
[OnionBalance](https://github.com/DonnchaC/onionbalance). This is because the
onion service descriptors for OnionBalance instances will often contain more
introduction points than normal, and these introduction points may even be
split across multiple distinct onion service descriptors. (The client only
**suspects** this because both of these things can happen in normal onion
service operation as well). To reduce the ability of the client adversary to
**suspect** this, set **DISTINCT_DESCRIPTORS=False** and
**MAX_INTRO_POINTS=7** in your OnionBalance configuration.

For capability #6, the client adversary may be able to **suspect** that a specific
onion service is using a particular guard by attacking that guard. If that
guard goes down or becomes slower, they may notice the effect on that onion
service. This is one of the reasons why the vanguards addon uses two guards in
a balanced way by default. Additionally, the adversary may be able to flood an
onion service with traffic to notice spikes in our public relay bandwidth
statistics at the guard.  Setting **circ_max_megabytes** in
[vanguards.conf](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf)
to an appropriate value for your service can help you detect and mitigate this
attack.

## Adversaries: Network

Network adversaries are those that run relays in the Tor network, and/or that
compromise Tor relays. They can also use the network (or a Tor client) to
inject traffic of their choice (especially against onion services).

The vanguards addon is designed to protect against network adversaries.
Setting aside the attacks that the vanguards addon defends against (which are
documented in
[README\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/reamde/README_TECHNICAL.md)),
network adversaries can still perform attacks that provide the following
capabilities:

1. **Determine** your Guard relays, if they run one of your Layer2 middle relays.
2. **Determine** that you are running an onion service that is using the vanguards
   addon, if they run one of your Guard relays.
3. **Confirm** that a specific onion service is using their Guard or Layer2 middle
   relays, if it is.
4. **Confirm** that a specific onion service is not using their Guard or Layer2
   middle relays, if it is not.

The vanguards addon is designed to make the network adversary's attacks as
difficult and unlikely as possible, and to take as long as possible, but they
can still succeed if you get unlucky. The Tor Project takes these attacks
seriously, and they are topics of [active
research](https://blog.torproject.org/tors-open-research-topics-2018-edition),
but for now, the vanguards addon is the best way we have to defend against
this adversary class.

For statistics on how long capability #1 takes, please see [our analysis of
our parameter
choices](https://github.com/asn-d6/vanguard_simulator/wiki/Optimizing-vanguard-topologies).

For capability #2, if you are using a guard relay run by the network adversary, they can
**determine** that you are running an onion service that is using the
vanguards addon through [circuit fingerprinting attacks](https://www.usenix.org/node/190967).
All of your onion service circuits (which are recognizable via the techniques
from that paper) will be made to a small set of layer2 vanguard relays. Normal
onion services (which are also recognizable at the guard relay via these same
techniques) will make circuits to the entire set of relays in the Tor network.
This discrepancy allows a malicious guard to determine that you are using the
vanguards addon.

For capability #3 and #4, the network adversary is able to perform
**confirmation** attacks to **confirm** that you are or are not using their
Guard or middle relays via the following mechanisms:

1. Inject special types of traffic at specific times towards your onion service (as was done [by CMU with RELAY_EARLY](https://blog.torproject.org/tor-security-advisory-relay-early-traffic-confirmation-attack), and [shown in the DropMark attack](https://petsymposium.org/2018/files/papers/issue2/popets-2018-0011.pdf)).
2. Inject large amounts of traffic towards your onion service, and look for these additional traffic patterns on their relays.
3. Close circuits at their relays, and observe if this causes any of their connections to your onion service to close.
4. Utilize [cryptographic tagging attacks](https://lists.torproject.org/pipermail/tor-dev/2012-March/003347.html) to mark circuits at their relays, and observe this mark at other relays (such
as the Rendezvous Point).

The vanguards addon has additional checks to detect activity related to these attacks, as well. Those details are covered in
[README\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/reamde/README_TECHNICAL.md).

## Adversaries: Local

Local adversaries include your WiFi [router
administrator](https://nakedsecurity.sophos.com/2018/04/18/russias-grizzly-steppe-gunning-for-vulnerable-routers/), ISP, hosting provider, or VPN, as well as the ISP or hosting provider of
the Tor relays you use to connect to the Tor network, and any other ISPs and
[routers](https://spectrum.ieee.org/tech-talk/computing/hardware/us-suspicions-of-chinas-huawei-based-partly-on-nsas-own-spy-tricks) along your path to the Tor network.

The local adversary has less surveillance resolution than the network
adversary, because Tor's TLS encryption prevents it from knowing  which of
your packets belong to which Tor circuit. This means that the local adversary
cannot perform most of the fingerprinting and related attacks that the network
adversary can perform.

However, local adversaries still have the following capabilities:

1. **Determine** that you are using the public Tor network.
2. **Suspect** that your Tor client might be running an unknown onion service.
3. **Suspect** that your Tor client might be running the vanguards addon (soon to be
   fixed).
4. **Confirm** that you are running a specific onion service address, if you are
   running a specific service that is of interest to them.

For capability #1, local adversaries can **determine** that you are running Tor
because the list of Tor relays is public, and connections to them are obvious.
[Using a bridge with your onion service](#the-best-way-to-use-bridges) can
help mitigate this attack.

For capability #2, local adversaries might **suspect** that your Tor client could
be an unknown onion service because it exhibits traffic patterns that are
unlike most other Tor clients. Your connections will stay open all of the
time, and you will regularly transmit data while other nearby humans are
asleep, as well as while they are awake. Your traffic will also be
asymmetrical. While most Tor clients download, you will likely be doing a lot
of uploading. [Using or running a bridge or Tor
relay](#Use-Bridges-or-Run-a-Relay-or-Bridge) with your
Onion Service can help conceal these traffic patterns, especially when [used
in combination with OnionBalance](#using-onionbalance).

For capability #3, local adversaries might also **suspect** that you could be
using the vanguards addon, at least until [Proposal
291](https://gitweb.torproject.org/torspec.git/tree/proposals/291-two-guard-nodes.txt)
is turned on. This is because you will be using two Guards in a balanced way,
as opposed to using a second Guard only sometimes (as normal clients do
today). Proposal 291 is a consensus parameter change. The rest of the Tor
Project has to agree that this is a good idea, and the change will be
immediate. I am convinced that worse attacks are possible without this
consensus parameter change, but discussion and deliberation of all possible
attacks and all possible future alternatives can take a while. Sometimes
years. In the meantime, I am still convinced it is safer for onion services to
use two guards in a balanced way, even if they stand out for doing so.

With capability #2 and #3, the local adversary may **suspect** that you could be
running an onion service, and maybe even one that wants high security, but
they will not know which onion service it is.

For capability #4, if the adversary is interested in deanonymizing a small set of
specific onion service addresses, they can attempt to **confirm** that you are
running one of these specific services on their local network via a few
different attack vectors:

1. Block your connection to Tor (or disable your internet connection) to see if any onion services they care about go down.
2. Send lots of traffic to the onion service to see if you get more traffic on your internet connection.
3. Kill your TCP connections to see if any of their connections to that onion service close.
4. If you weren't using vanguards, they can confirm an onion service even
   easier (see [Proposal 291](https://gitweb.torproject.org/torspec.git/tree/proposals/291-two-guard-nodes.txt) for details).

The first two vectors of this **confirmation** attack can be mitigated by
[using OnionBalance](#using-onionbalance), and by setting
**circ_max_megabytes** in your
[vanguards.conf](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf)
to an appropriate value for your service.

Unfortunately, the third vector is not possible to fully mitigate until Tor
supports datagram transports and [conflux-style session
resumption](https://www.cypherpunks.ca/~iang/pubs/conflux-pets.pdf).

However, [monitoring your service closely](#monitor-your-service) for
connectivity loss can help you detect attempts by the adversary to **confirm**
your service location. The vanguards addon will emit NOTICE and WARN messages
related to connectivity loss, and your service will become unreachable.

## Adversaries: Global

A global adversary is an adversary that can observe large portions of the
internet. [The Five Eyes](https://en.wikipedia.org/wiki/Five_Eyes) and its
extended versions are the canonical example of this adversary. However,
adversaries that can compromise a large number of internet routers (such as
[Russia](https://nakedsecurity.sophos.com/2018/04/18/russias-grizzly-steppe-gunning-for-vulnerable-routers/)
or
[China](https://spectrum.ieee.org/tech-talk/computing/hardware/us-suspicions-of-chinas-huawei-based-partly-on-nsas-own-spy-tricks))
are also in this class.

The global adversary can perform most of the attacks that the local adversary
can, but everywhere. (It may be significantly more expensive for the global
adversary to perform **active** attacks than it is for the local adversary to
do so, but for the most part this degrades their capability only slightly).

The global adversary has the following capabilities:

1. **Determine** a list of most/all IPs that connect to the public Tor network.
2. **Suspect** which of these IPs might be running onion services.
3. **Suspect** which of these IPs might be using the vanguards addon (soon to be fixed).
4. **Suspect** that an IP might be running a specific onion service address, if it is
   running a specific service that is of interest to them.

The mitigations for these are the same as they are for the local adversary.

This same adversary can theoretically perform additional attacks to attempt to
deanonymize all Tor traffic all of the time, but [there are
limits](http://archives.seul.org/or/dev/Sep-2008/msg00016.html) to how well
those attacks scale. These limits are also the reason that the global
confirmation attack has been degraded to "**suspect**" for #4.

For capability #4, the global adversary becomes more certain in their
suspicion if they are able to induce the onion service to transmit
significantly more traffic than its baseline for a long period of time. Again,
the mitigations for this are to use [OnionBalance](#using-onionbalance), use
or run
[a bridge](#Use-Bridges-or-Run-a-relay-or-Bridge) with your
onion service, and/or set **circ_max_megabytes** in your
[vanguards.conf](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf)
to an appropriate value for your service.


# What can I do to be safer?

Quite a few things. Using the vanguards addon is a good start, but it is not
the whole picture.

There are four classes of things you can do to improve your position against
various attacks:

1. [Have Good Opsec](#have-good-opsec)
2. [Use Bridges or Run a Relay or Bridge](#use-bridges-or-run-a-relay-or-bridge)
3. [Configure OnionBalance Correctly](#using-onionbalance)
4. [Monitor Your Service](#monitor-your-service)

## Have Good Opsec

Before worrying about any of these advanced attacks on the Tor network, you
should make sure that your onion service is not leaking basic info via the
application layer, or by allowing connections outside of Tor.

For information about how to do this, you should have a look at the [Riseup Onion Services Best Practices document](https://riseup.net/en/security/network-security/tor/onionservices-best-practices).

## Use Bridges or Run a Relay or Bridge

Tor has only basic defenses against traffic analysis at the moment. We are
working on more, but in the meantime, using a bridge or running a relay or
bridge can provide some additional protection against traffic analysis
performed by local and global adversaries.

Bridges can help conceal the fact that you are connecting to the Tor network.
If you use a bridge address that is not known to the adversary, both the local
and global adversaries will have a harder time performing their attacks.

Running a relay or bridge with your service can help the traffic patterns of
your service blend in with the rest of the Tor network, but this is tricky to
set up correctly, and you must take additional steps to decorrelate your
service uptime from your relay uptime.

### The Best Way To Use Bridges

Right now, the best bridge protocol to use is obfs4, because it has additional
traffic analysis obfuscation techniques that make it harder for the local and
global adversaries to use bandwidth side channels and other traffic
characteristics.

To use obfs4, obtain two bridges from
[bridges.torproject.org](https://bridges.torproject.org/bridges?transport=obfs4)
and add them to your torrc like so:

```
UseBridges 1
Bridge obfs4 85.17.30.79:443 FC259A04A328A07FED1413E9FC6526530D9FD87A cert=RutxZlu8BtyP+y0NX7bAVD41+J/qXNhHUrKjFkRSdiBAhIHIQLhKQ2HxESAKZprn/lR3KA iat-mode=2
Bridge obfs4 38.229.1.78:80 C8CBDB2464FC9804A69531437BCF2BE31FDD2EE4 cert=Hmyfd2ev46gGY7NoVxA9ngrPF2zCZtzskRTzoWXbxNkzeVnGFPWmrTtILRyqCTjHR+s9dg iat-mode=2

ClientTransportPlugin obfs2,obfs3,obfs4,scramblesuit exec /usr/bin/obfs4proxy
```

Note the use of the iat-mode=2 parameter. Setting iat-mode=2 (as opposed to
iat-mode=0 or 1) causes obfs4 to inject traffic timing changes into your
outgoing traffic, which is exactly the direction you want as a service. The
bridge itself does not need to have the same setting.

You can get that obfs4proxy binary as a debian package, or from a recent Tor
Browser version, or [build it from source](https://gitweb.torproject.org/pluggable-transports/obfs4.git/).

### The Best Way to Run Tor Relays Or Bridges With Your Service

Instead of using bridges, another alternative is to use the Tor network itself
as cover traffic for your service by running a relay or bridge. If your relay
or bridge is used enough (especially by other onion service client and service
traffic), this will help obscure your service's traffic.

The seemingly obvious approach would be to use the same Tor process for your
relay as you use for your onion service. This will accomplish the traffic
blending on the same TLS connections as relayed Tor traffic. Unfortunately,
because Tor is single threaded, your onion service activity can still cause
stalls in the overall network activity of your relay. See
[Ticket #16585](https://trac.torproject.org/projects/tor/ticket/16585) for the gory
details. Worse still, if it is the same process, your Tor relay will report
your onion service history in its read/write statistics, which result in a
[noticeable asymmetry in these
statistcis](https://trac.torproject.org/projects/tor/ticket/8742).

However, if you run your Tor relay as a separate process on the same machine
as your onion service Tor process, but **also** use that relay locally as a
bridge, your onion service activity will not directly block the relay
activity, but will still share all of its outbound TLS connections to other
relays. For this, you would add something like the following to your onion
service torrc:

```
UseBridges 1
Bridge 127.0.0.1:9001                # 9001 is the relay process's OR port.
```

The story deepens, however. When you do this, **your onion service uptime will
be strongly correlated to your relay uptime, and both are now very
easily observable by client adversaries**.

[OnionBalance](#using-onionbalance) is one way to address this (ie: running
several Tor relays on different machines, each with their own OnionBalance
Backend Instance).

To look as much like a normal onion service as possible, you should use two
Tor relays, and each on different machines in different data centers. In this
way, your traffic will appear as an onion service that is using your two
guards, and your onion service as a whole won't go down unless both of your
relays are down.

## Using OnionBalance

[OnionBalance](https://onionbalance.readthedocs.io/en/latest/getting-started.html#architecture)
can help protect against some forms of traffic analysis and confirmation
attacks. It does this at the expense of more exposure to a larger number of
local adversaries, though, and if the adversary can tell that you are using
OnionBalance, they can counteract many of the benefits.

Despite exposing you to more local adversaries, OnionBalance helps protect
against local adversaries because they will no longer be able to observe all
of your onion service traffic, and it is more difficult for them to impact
your reachability for a reachability confirmation attack.

Additionally, when OnionBalance is used in combination with the addon's
bandguards component option **circ_max_megabytes**, this can help protect
against bandwidth confirmation attacks that send high volumes of traffic to
interesting onion services and watch for any evidence of results on a local
internet connection.

However, OnionBalance needs some tweaks to avoid giving an advantage to the
network adversary. Because multiple instances of the vanguards addon do not
communicate through OnionBalance, each additional instance of the vanguards
addon will choose different layer2 and layer3 guards. These additional layer2
and layer3 guards increase the overall exposure to guard discovery attacks. In
cases where it is just as bad for the adversary to discover any of your onion
service instances as it is to discover all of them, then obviously each
additional instance lowers your security a bit.

### How to OnionBalance

To attempt to conceal the fact that you are using OnionBalance, you want your
OnionBalance service to produce descriptors with similar numbers of
introduction points as normal services. Normal services typically have between
3 and 7 introduction points. This means you should set the OnionBalance
setting **MAX_INTRO_POINTS=7**, and also set **DISTINCT_DESCRIPTORS=False**,
to prevent it from generating multiple descriptors.

To keep your layer2 and layer3 vanguards in sync between your OnionBalance
Management Server and the backend instances, first run vanguards on your
Management Server.

Then, once per hour, copy the **vanguards.state** file from your OnionBalance
Management Server to each of your Backend Instances, via tor+scp or some other
secure mechanism. (The UNIX crontab program is a good way to do this copy
hourly).

When each Backend Instance gets this copied statefile (let's call it
**mgmt-vanguards.state**), it should run
```
  ./src/vanguards.py --one_shot_vanguards --state mgmt-vanguards.state
```

This will cause the Backend Instance to update its tor settings with the same
layer2 and layer3 guard information as on the management side. It does not
matter if your Backend Instances cannot write to their torrc files. The
settings will still be updated.

Then, to benefit from the other defenses, each Backend Instance should run a
separate vanguards process with a different state file, but with vanguards
itself disabled. This is done with something like:
```
  ./src/vanguards.py --disable_vanguards --state backend-vanguards.state
```

These backend instances will then still monitor and react to bandwidth side
channel attacks and Rendezvous Point overuse, while still using the same
layer2 and layer3 guards as your Management Server.

## Monitor Your Service

As we discussed above, confirmation attacks can be performed by local and
global adversaries that block your access to Tor (or kill your Tor
connections) to **confirm** if this impacts the reachability of a suspect hidden
service or not. This is a good reason to monitor your onion service reachability very
closely with monitoring software like [Nagios](https://www.nagios.org/) or
[Munin](http://munin-monitoring.org/).

If you use OnionBalance, you need to monitor the ability of each of your
Backend Instances to connect to Tor and receive connections to their unique
backend onion service addresses. If the adversary **suspects** that you are
using OnionBalance, they can perform reachability confirmation attacks against
the specific backend instances, so monitoring their uptime is a wise move.

If you use bridges or run relays, you should monitor their uptime as well, and
replace them immediately if they go down.

The vanguards addon also emits WARN messages when it detects that you have lost
connectivity to the Tor network, or when you still have connectivity to the Tor
network, but you are unable to build circuits. It also emits NOTICE messages
if any connections were forcibly closed while they had active circuits on them.

You should add the output of the vanguards addon to your monitoring
infrastructure for this reason (in addition to watching for evidence of
the other attacks the addon detects).

# What does this addon do?

This addon uses the [Stem Tor control port
library](https://stem.torproject.org/) to connect to a Tor control port
listening on port 9051 (or on an alternate user-specified port, or UNIX file
system socket).

This addon protects against guard discovery and related traffic analysis
attacks. A guard discovery attack enables an adversary to determine the guard
node(s) that are in use by a Tor client and/or Tor onion service. Once the
guard node is known, traffic analysis attacks that can deanonymize an onion
service (or onion service user) become easier.

The most basic form of this attack is to make many connections to a Tor onion
service, in order to force it to create circuits until one of the adversary's
relay is chosen for the middle hop next to the guard. That is possible because
middle hops for rendezvous circuits are picked from the set of all relays:

![Current Onion Service Paths](https://raw.githubusercontent.com/asn-d6/vanguard_simulator/illustrations/illustrations/current_system.jpg)

This attack can also be performed against clients, by inducing them to create
lots of connections to different onion services, by for example, injecting
lots of onion-hosted images/elements into a page.

A traffic analysis side channel can be used to confirm that the malicious node
is in fact part of the rendezvous circuit, leading to the discovery of that
onion service's or client's guard node. From that point, the guard node can be
compromised, coerced, or surveilled to determine the actual IP address of the
onion service or client.

To defend against these attacks, this addon has three defense subsystems:
Vanguards, Rendguard, and Bandguards.

All three subsystems apply to both service-side and client-side onion service
activity. With Tor v0.3.5.1 and Vanguards v0.3.0 and above, the Bandguards
subsystem also applies to client traffic that exits the Tor network to the
normal Internet.

## The Vanguards Subsystem

The Vanguards subsystem uses the [Tor control
protocol](https://gitweb.torproject.org/torspec.git/tree/control-spec.txt) to
select nodes from the Tor consensus for use with the torrc options HSLayer2Nodes
and HSLayer3Nodes.

Each of these options is assigned its own set of nodes, which are rotated
based on the randomized selection algorithm specified in [the Mesh Vanguards
Proposal](https://gitweb.torproject.org/torspec.git/tree/proposals/292-mesh-vanguards.txt).

These options ensure that all onion service circuits are restricted to a set
of second and third layer guards, instead of sampling random ones from the
whole network every time.

The change to fixed nodes for the second and third layer guards is designed
to force the adversary to have to run many more nodes, and to execute both an
active sybil attack, as well as a node compromise attack. In particular, the
addition of second layer guard nodes means that the adversary goes from being
able to discover your guard in minutes by running just one middle node, to
requiring them to sustain the attack for weeks or even months, even if they
run 5% of the network.

The analysis behind our choice for the number of guards at each layer, and for
rotation duration parameters is [available on
GitHub](https://github.com/asn-d6/vanguard_simulator/wiki/Optimizing-vanguard-topologies).
Here is how our current vanguard 2-3-8 topology looks like:

![Vanguard Layer Topology](https://raw.githubusercontent.com/asn-d6/vanguard_simulator/illustrations/illustrations/vanguard_system.jpg)

Furthermore, to better protect the identity of these new pinned guard nodes,
and to avoid linkability of activity, the circuit lengths have been
altered for rendezvous point circuits, hidden service directory circuits, and
introduction point circuits. You can see them here (where L1 is the first
layer guard, L2 is second layer guard, L3 is third layer guard, M is random
middle):

![Vanguard Path
Lengths](https://raw.githubusercontent.com/asn-d6/vanguard_simulator/illustrations/illustrations/new_paths.jpg)

The number of nodes in each of these sets, as well as the ranges on rotation
times for each set, can be specified as config file parameters. The subsystem
currently uses 2 entry guards, 3 layer2 guards, and 8 layer3 guards.

High load onion services may consider using 4 layer2 guards by changing the
**num_layer2_guards** option in the [configuration
file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf), but going beyond that is not recommended.

## The Rendguard Subsystem

The Rendguard subsystem keeps track of how often various relays appear in the
rendezvous point position on the service side of an onion service. Since
rendezvous points are chosen by the client that connects to a service, it
is possible for clients to [choose malicious, colluding rendezvous
points](https://www.ieee-security.org/TC/SP2013/papers/4977a080.pdf) to
help them mount guard discovery and other attacks.

This subsystem emits warnings and optionally closes the circuit when a
rendezvous point is chosen too often compared to its consensus weight (the
"too often" limit is set by the **rend_use_max_use_to_bw_ratio** config
option, which defaults to 5X of a relay's consensus weight).

We assign an aggregate weight of **rend_use_max_consensus_weight_churn**
(default: 1% of consensus total) for relays that are not in our current
consensus that are used as rendezvous points. It is valid to use relays that
are not in the consensus as rendezvous points, and this can happen naturally
when a client's consensus is from a different time period as the service's
consensus. To prevent arbitrary computers from being used as rendezvous
points, we set this bound on the maximum amount of consensus churn, and use
that to limit all rendezvous requests that are not present in the service's
consensus.

When rendezvous points are overused and blocked by the addon, the effect is
that clients get connection refused responses when they attempt to use
rendezvous points that are already overused. Since the adversary gets to pick
their rendezvous point, they can trigger these limits at will, and cause
popular rendezvous points to be blocked by your service. If this happens, you
can set **rend_use_close_circuits_on_overuse** to false in your configuration
file. If you do this, rendezvous overuse messages will appear at WARN level,
but circuits will not be closed.

## The Bandguards Subsystem

The bandguards subsystem performs accounting to watch for signs of bandwidth
sidechannel attacks on individual onion service circuits as well as exit
circuits. It then closes circuits that exceed these limits and emits log
messages. While we expect the default values to be set properly, these limits
can be tuned through configuration as well. See the [configuration
file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf)
for more details.

These limits (along with a reason for checking them) are as follows:

1. ***Dropped Cell Limit***

   Back in 2014, the Tor network [was attacked](https://blog.torproject.org/tor-security-advisory-relay-early-traffic-confirmation-attack) by Carnegie Mellon researchers ([likely on behalf of the FBI)](https://blog.torproject.org/did-fbi-pay-university-attack-tor-users). The attack injected a side channel using a special packet type that could be recognized at both ends of a Tor circuit.

   This side channel was fixed. Unfortunately, there are many other side channels available that allow an adversary to inject traffic that is ignored by a Tor client.

   These remaining side channels are not as severe -- they cannot immediately be recognized by colluding relays using packet information alone. Instead the adversary must rely on packet volume and timing information in order to recognize the signal. However, if the volume of injected traffic is large enough or other conditions are right, [it may still be possible](https://petsymposium.org/2018/files/papers/issue2/popets-2018-0011.pdf) to use statistical methods to recover a signal.

   The component uses
[new control port features](https://trac.torproject.org/projects/tor/ticket/25903) and [improved connection tracking in Tor](https://trac.torproject.org/projects/tor/ticket/25573) to measure
the quantity of traffic that Tor decides to drop from a circuit, to protect against
[DropMark](https://petsymposium.org/2018/files/papers/issue2/popets-2018-0011.pdf)
attacks.

   The allowed dropped cell count is 0, and cannot be configured.

2. ***Total Hidden Service Descriptor Kilobytes***

   In addition to injecting relay cells that are dropped, it is also possible for relays to inject data at the end of an onion service descriptor, or in response to an onion service descriptor submission. Tor will continue reading this data prior to attempting to parse the descriptor or response, and these parsers can be convinced to discard additional data.

   The bandguards subsystem sets a limit on the total amount of traffic allowed on onion service descriptor circuits (currently 30 kilobytes). Once this limit is exceeded, the circuit is closed and a WARN log message is emitted by the bandguards subsystem.

   If your service uses OnionBalance, or has set a large number of custom
introduction points, you may need to raise this limit via the
**circ_max_hsdesc_kilobytes** setting in the [configuration
file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf).

3. ***Total Circuit Megabytes***

   A final vector for injecting side channel traffic is at the application layer.

   If an attacker wants to introduce a side channel towards an onion service, they can fetch large quantities of data from that service, or make large HTTP posts towards the service, in order to generate detectable traffic patterns.

   These traffic patterns can be detected in Tor's public relay bandwidth
statistics, as well as via netflow connection volume records. The Tor Project
is currently working on various mechanisms to reduce the granularity of these
statistics (and has already reduced them to 24 hours of aggregate data), and
has also deployed padding mechanisms to limit the resolution of netflow traffic
logs, but it is not clear that these mechanisms are sufficient to obscure very
large volumes of traffic.

   Because of this, the bandguards subsystem has the ability to limit the
total number of bytes sent over a circuit before a WARN is emitted and the
circuit is closed.  This limit is currently set to 0 (which means unlimited).
If you know a reasonable bound for the amount of data your application or
service should send on a circuit, be sure to set it to that value.

   **If your service or application depends upon the ability of people to make
very very large transfers (such as OnionShare, or a SecureDrop instance), you
should keep this disabled, or at best, set it to multiple gigabytes.**

   If your service is a normal website that does not transmit large content,
100 megabytes is a reasonable value for this setting.

   We believe that using two entry guards makes closing the circuit a
worthwhile defense for applications where it is possible to use it. If the
adversary is forced to split their side channel across multiple circuits, they
won't necessarily know which guard node each circuit traversed. This should
increase the quantity of data they must inject in order to successfully mount
this attack (and by more than just a factor of two, because of this uncertainty).

   Long-term, this feature is meant to be deployed in combination with
[conflux traffic
splitting](https://www.cypherpunks.ca/~iang/pubs/conflux-pets.pdf) so that we
can tear down one path of a circuit after over-use without loss of
connectivity, and reconnect the remaining portion to a new circuit.

   If you wish to enable this defense, change the value of
**circ_max_megabytes** in the [configuration file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf).

4. ***Max Circuit Age***

   Since Tor currently rotates to new TLS connections every week, if a circuit stays open longer than this period, then it will cause its old TLS connection to be held open. After a while, the circuit will be one of the few things using that TLS connection. This lack of multiplexing makes traffic analysis easier.

   For an example of an attack that makes use of this type of side channel, see [TorScan](https://eprint.iacr.org/2012/432.pdf). For additional discussion, see Tor Ticket [#22728](https://trac.torproject.org/projects/tor/ticket/22728) and [#23980](https://trac.torproject.org/projects/tor/ticket/23980).

   For this reason, if your onion service does not require long-lived circuits, it is wise to close any that hang around for long enough to approach this rotation time.

   The current default for maximum circuit age is 24 hours, and can be changed
via **circ_max_age_hours** in the [configuration
file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf).

5. ***Connectivity to the Tor Network***

   Reachability itself is a side-channel. An adversary can correlate your
uptime to other events to reduce your anonymity, or even actively attempt to
influence connectivity to parts of the Tor network to determine if a specific
service is using them. Because of this, we have added monitoring of connectivity
to the Tor Network. The addon will alert you if all of your guard connections
go down, or if you are unable to build circuits for a set amount of time.

   Obviously, clients may want to disable this monitoring, especially if they
are disconnected frequently. To disable these checks, change the
***circ_max_disconnected_secs*** and ***conn_max_disconnected_secs***
configuration settings to 0.

# Security Information

For additional security information, please see
[README\_SECURITY.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md).

# How to run the tests

This repository is configured to run unit tests on every commit in a pinned
virtual environment via [Travis CI](https://travis-ci.org/mikeperry-tor/vanguards/).

You can run the tests yourself with the python-tox and python-pytest packages,
simply by running 'tox' in the root directory of this source tree. This will
re-create the same test environment run on Travis CI, with the same pinned
dependency versions.

To use your distribution's packages instead, run:

```
 tox -c tox-systemonly.ini
```

or for each python version individually as:

```
 TOXENV=py2 tox -c tox-systemonly.ini
 TOXENV=py3 tox -c tox-systemonly.ini
 TOXENV=pypy tox -c tox-systemonly.ini
```


This will run python2, python3, and pypy tests, **as well as check your
system-installed packages for known vulnerabilities against
https://pyup.io/safety**.

To run just the tests in the bare source tree against the git checkout in
combination with system-wide packages, with no installation or known
vulnerability checks, run:

```
 PYTHONPATH=src python2 -m pytest tests/
 PYTHONPATH=src python3 -m pytest tests/
 PYTHONPATH=src pypy -m pytest tests/
```

After system-wide installation of the vanguards package, you can run the tests
without the PYTHONPATH specifier, to check the installed package:

```
 python2 -m pytest tests/
 python3 -m pytest tests/
 pypy -m pytest tests/
```