1# The Vanguards Onion Service Addon 2 3[](https://travis-ci.org/mikeperry-tor/vanguards) [](https://coveralls.io/github/mikeperry-tor/vanguards?branch=master) 4 5Even after deployment of the [new v3 onion service 6protocol](https://gitweb.torproject.org/torspec.git/tree/proposals/224-rend-spec-ng.txt), 7the attacks facing onion services are wide-ranging, and still require 8more extensive modifications to fix in Tor-core itself. 9 10Because of this, we have decided to rapid-prototype these defenses in a 11controller addon in order to make them available ahead of their official 12Tor-core release, for onion services that require high security as soon as 13possible. 14 15For details about the defenses themselves, please see 16[README\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_TECHNICAL.md). 17 18For additional security information, please see 19[README\_SECURITY.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md). 20 21# Installation Methods 22 23There are several ways to use this addon. At the moment, the safest is to run 24it directly from git. 25 26Packages for popular UNIX-like systems should be available soon. 27 28## Running this addon directly from git 29 30**This is the safest option to use, since it avoids having pip and/or 31virtualenv download packages from PYPI without verification.** 32 331. Retrieve this repository and optionally verify a signed git version tag. 342. [Install Stem](https://stem.torproject.org/download.html) 353. Run **./src/vanguards.py** 36 37If your control port is on an alternate IP and Port, specify that with 38**--control_host _IP_ --control_port _portnum_**. 39 40If you are using a control socket, specify its full path with 41**--control_socket /path/to/socket**. 42 43Note that **./src/vanguards.py** has several other options under **--help**. 44 45## Using VirtualEnv 46 47**This option tells virtualenv not to download packages, and only downloads 48pip packages with --require-hashes. It should be safe.** 49 50To install Stem and Vanguards into their own python virtualenv, run: 51 52``` 53torsocks ./setup.sh 54source vanguardenv/bin/activate 55vanguards 56``` 57 58If you do not want your environment to be in the vanguardenv subdirectory, you 59can specify a different directory as an argument to **setup.sh**. 60 61## Pip 62 63This project is also listed on the Python Package Index. To install the 64latest release via pip **without any verification**, do: 65 66``` 67torsocks pip install vanguards 68``` 69 70# How to use the addon 71 72## Configuration 73 74All of the subsystems of this addon can be tuned via a configuration file. 75Check out this documented [example configuration file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf) for more information. 76 77Configuration files can be specified on the command line. The default is to 78read **vanguards.conf** from the current working directory. If the environment 79variable **$VANGUARDS\_CONFIG** is set, the config file will be read from the 80file specified in that variable. 81 82## Onion service use 83 84This addon is primarily intended for onion service operators. To use it, 85set up your onion service to expose a control port listener using the 86ControlPort or ControlSocket torrc directives: 87 88``` 89ControlPort 9099 # or ControlSocket /path/to/socket 90CookieAuthentication 1 91DataDirectory /path/to/tor/datadir 92``` 93 94and then run: 95 96``` 97vanguards --control\_port=9099 # (or --control\_socket /path/to/socket). 98``` 99 100## Client use 101 102It is also possible to use the vanguards addon as a regular Tor client with 103Tor Browser or with Onionshare. 104 105To use it with Tor Browser, all you have to do is start Tor Browser, and then run: 106``` 107 ./src/vanguards.py --control_port 9151 108``` 109 110To use it with Onionshare, set up your Tor to expose a control port and attach 111both onionshare and the vanguards addon to it. 112 113## Performance Tuning 114 115For very high traffic onion services, we recommend using 116[PyPy](https://pypy.org) instead of CPython. PyPy contains a JIT that should 117make this addon run considerably faster. 118 119The easiest way to use PyPy is to do **sudo apt-get install pypy** or 120equivalent before running **./setup.sh** as per above. The setup.sh script will 121then see that pypy is installed, and use it by default in the resulting 122virtualenv. 123 124To switch to pypy after running **setup.sh**, simply remove the vanguardenv 125directory and run **setup.sh** again. 126 127If 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: 128 129``` 130 pypy ./src/vanguards.py 131``` 132 133Additionally, you can disable components to reduce processing overhead. Try 134disabling Rendguard first. If that is still insufficient, disable Bandguards. 135 136Vanguards by itself should not require much overhead, but if even that is too 137much, you can run the following once per hour from cron to update your torrc 138with fresh layer2 and layer3 guards: 139 140``` 141 pypy ./src/vanguards.py --one_shot_vanguards 142``` 143 144# What do the logs mean? 145 146This is an experimental addon with many heuristics that still need tuning. 147Events that represent severe issues are at WARN level. You should 148react to these events. Warns are currently emitted for the following 149conditions: 150 1511. When your service is disconnected from the Tor network, we WARN. Downtime 152can be a side channel signal or a passive information leak, 153and you should ensure your Internet connection is reliable to minimize 154downtime of your service as much as possible. 1552. When a hidden service descriptor circuit sends more than 30KB, we WARN. If this 156happens, it is either a bug, a heavily-modified hidden service descriptor, 157or an actual attack. 1583. When you set ExcludeNodes in Tor to exclude countries, but do not give 159Tor a GeoIP file, we WARN. 1604. If you disable killing circuits in the rendguard component, we WARN when 161use counts for rends are exceeded. 1625. With Tor 0.3.4.10 and above, we WARN upon receipt of any dropped/ignored cell. 163 164Events that are detected by heuristics that still need tuning are at NOTICE 165level. They may be a bug, a false positive, or an actual attack. If in doubt, 166don't panic. Please check the [Github 167issues](https://github.com/mikeperry-tor/vanguards/issues/) to see if any 168known false positives are related to these lines, and if not, consider filing 169an issue. Please redact any relay fingerprints from the messages before 170posting. 171
){kind=link}
){kind=link}