wiki:vanguards

Vanguards

Written: 2018-12-17 (by mathew)

( generally for Linux (Unix?), but some tips specific to Debian/Ubuntu/... )

Read:

Announcing the Vanguards Add-On for Onion Services | Tor Blog

The sources are at: git repo

Is a great boost to your anonimity when using Tor. Few downsides, lots of advantages.

It's used either by clients only, or by Tor Onion servers and other Tor Onion services. It can be used with Tor installed with your package manager of your Linux distro, as well as with Tor Browser Bundle. And it's easy to install it and use it.

These instructions and in greater part generally for Linux, and in minor part they are Debian/Ubuntu/... specific. Only minor changes for other distros are needed in some aspects below.

/your-chosen-dir/ can be /home/you/your-git-cloned-repos/ or somewhere else where you have privs as regular user.

$ cd /your-chosen-dir/

We'll get the repo with Tor, see: Git

As yourself (note the "$"):

$ t_git clone https://github.com/mikeperry-tor/vanguards

(of course you can as well run "git clone" instead of "t_git clone" above, in clear non-anonymous deep web, not in dark web)

First, you need to have stem package installed. The instructions below for Vanguards with either System Tor or Tor Browser Bundle do not mention it, but it's in the README's of the git repo.

Also, there are other ways to install Vanguards, f.e. there is vanguards package in Debian/Ubuntu/... but I'll restrict myself to installing and then using Vanguards from source. One of the reasons, there is no --correct me if I'm wrong-- vanguards package for Tor Browser Bundle, and the Debian vanguards package is all set for the Debian System Tor (but do correct me if I'm wrong).

Another reason is the main authors writes:

$ grep -A1 -r safes vanguards/
vanguards/README.md:There are several ways to use this addon. At the moment, the safest is to run
vanguards/README.md-it directly from git.

Vanguards with System Tor

As root (note the "#"):

# cp -ai /your-chosen-dir/vanguards/ /usr/lib/vanguards/

Keep the sources in /your-chosen-dir/vanguards/, you may like to use them for TorBrowser as well, to install a separate vanguards install for TorBrowser too, later.

Debian stock Tor runs as user debian-tor. So you need to:

# chown -R debian-tor:debian-tor /usr/lib/vanguards/

And you should now have the listing similar to:

# ls -l /usr/lib/vanguards/
total 124
-rw-r--r-- 1 debian-tor debian-tor  1989 2018-11-16 22:09 CHANGES.rst
-rw-r--r-- 1 debian-tor debian-tor  1066 2018-11-05 14:45 LICENSE
-rw-r--r-- 1 debian-tor debian-tor   316 2018-11-05 14:45 MANIFEST.in
-rw-r--r-- 1 debian-tor debian-tor  6726 2018-11-05 14:45 README.md
-rw-r--r-- 1 debian-tor debian-tor 25652 2018-11-16 22:09 README_SECURITY.md
-rw-r--r-- 1 debian-tor debian-tor 14003 2018-11-16 22:09 README_TECHNICAL.md
-rw-r--r-- 1 debian-tor debian-tor  1386 2018-11-05 14:45 README_TESTS.md
-rw-r--r-- 1 debian-tor debian-tor   306 2018-11-16 22:09 requirements.txt
-rw-r--r-- 1 debian-tor debian-tor   121 2018-11-05 14:45 setup.cfg
-rw-r--r-- 1 debian-tor debian-tor  2307 2018-11-16 22:09 setup.py
-rwxr-xr-x 1 debian-tor debian-tor  1070 2018-11-05 14:45 setup.sh
drwxr-xr-x 3 debian-tor debian-tor  4096 2018-12-14 17:20 src
-rw-r--r-- 1 debian-tor debian-tor  6500 2018-11-16 22:09 test-requirements.txt
drwxr-xr-x 2 debian-tor debian-tor  4096 2018-11-16 22:09 tests
-rw-r--r-- 1 debian-tor debian-tor   636 2018-11-05 14:45 TODO.txt
-rw-r--r-- 1 debian-tor debian-tor   456 2018-11-05 14:45 tox.ini
-rw-r--r-- 1 debian-tor debian-tor   870 2018-11-05 14:45 tox-systemonly.ini
-rw-r--r-- 1 debian-tor debian-tor  2002 2018-11-05 14:45 vanguards.1
-rw-r--r-- 1 debian-tor debian-tor  4279 2018-11-16 22:09 vanguards-example.conf

Why install it in /usr/lib/ ?

Because vanguards is written in Python, is made of python libraries, and while it is true that Debian stock Tor default and optional configuration (for an aditional Tor instance) are just fine in /usr/share/tor/, those are just config files (and geoip, if you install them), not libraries.

And python libraries are in /usr/lib . List those, you'll likely have a similar output:

# ls -1trd /usr/lib/python*
/usr/lib/python3
/usr/lib/python2.6
/usr/lib/python3.4
/usr/lib/python3.5
/usr/lib/python3.7
/usr/lib/python3.6
/usr/lib/python2.7

So /usr/lib/ is the most appropriate place. However, if you prefer, install them elsewhere, and modify these instructions accordingly.

Important: in case for some reason you need/decide you don't need/don't want it anymore, all you need to do to uninstall it is:

# rm -rf /usr/lib/vanguards/

Next, study the README's. These instructions are by no means a substitute for those, as well as the links given at top.

They are very instructive. Vanguards is pretty much a completed program, its development has been done, bugs fixed, and it is mostly in the maintainenance phase since weeks and longer by now. It is now stable and likely bug-free as much as any good program can be.

You need to run the vanguards install for your System Tor like this (users of other Linuces need to modify here, of course) as user debian-tor.

Before you run vanguards, make sure the system Tor is running. Vanguards is just its Add-On.

# service tor status
[ ok ] tor is running.

You can then start vanguards by sudo'ing and as root running:

# sudo -u debian-tor /usr/lib/vanguards/src/vanguards.py --help
usage: vanguards.py [-h] [--state STATE_FILE] [--generate_config WRITE_FILE]
                    [--loglevel LOGLEVEL] [--logfile LOGFILE]
                    [--config CONFIG_FILE] [--control_ip CONTROL_IP]
                    [--control_port CONTROL_PORT]
                    [--control_socket CONTROL_SOCKET]
                    [--control_pass CONTROL_PASS] [--retry_limit RETRY_LIMIT]
                    [--one_shot_vanguards] [--disable_vanguards]
                    [--disable_bandguards] [--disable_rendguard]
                    [--enable_cbtverify]

optional arguments:
  -h, --help            show this help message and exit
  --state STATE_FILE    File to store vanguard state
  --generate_config WRITE_FILE
                        Write config to a file after applying command args
  --loglevel LOGLEVEL   Log verbosity (DEBUG, INFO, NOTICE, WARN, or ERROR)
  --logfile LOGFILE     Log to LOGFILE instead of stdout
  --config CONFIG_FILE  Location of config file with more advanced settings
  --control_ip CONTROL_IP
                        The IP address of the Tor Control Port to connect to
                        (default: 127.0.0.1)
  --control_port CONTROL_PORT
                        The Tor Control Port to connect to (default: 9051)
  --control_socket CONTROL_SOCKET
                        The Tor Control Socket path to connect to (default: )
  --control_pass CONTROL_PASS
                        The Tor Control Port password (optional)
  --retry_limit RETRY_LIMIT
                        Reconnect attempt limit on failure (default: Infinite)
  --one_shot_vanguards  Set and write layer2 and layer3 guards to Torrc and
                        exit.
  --disable_vanguards   Disable setting any layer2 and layer3 guards.
  --disable_bandguards  Disable circuit side channel checks (may help
                        performance)
  --disable_rendguard   Disable rendezvous misuse checks (may help
                        performance)
  --enable_cbtverify    Enable Circuit Build Time monitoring

But that wasn't actually running it. I lied to you. For running vanguards in a client, you do need to first look with some attention to the --help that issued command can provide to you, so don't be angry at me :) .

Of the above, lots of those are for advanced configurations. and for services. If you are running just a client, this is a suggested way you can do it.

# cd /home/you

(or elsewhere, just know where your logs will be written to)

Now run (this is just one possible way you can do it):

# sudo -u debian-tor /usr/lib/vanguards/src/vanguards.py --loglevel NOTICE --logfile vanguards.log

This is the bare minimum though:

# sudo -u debian-tor /usr/lib/vanguards/src/vanguards.py

That will log on STDOUT, if you like it better that way.

Vanguards with Tor Browser Bundle

$ ls -l /home/you/tor-browser_en-US/Browser/TorBrowser/
total 20
drwx------ 5 you you 4096 2000-01-01 00:00 Data
drwx------ 7 you you 4096 2018-12-12 14:48 Docs
drwx------ 4 you you 4096 2018-12-12 14:48 Tor
drwxr-xr-x 3 you you 4096 2018-12-15 20:38 UpdateInfo

Make that directory look like:

$ ls -l /home/you/tor-browser_en-US/Browser/TorBrowser/
total 20
drwx------ 5 you you 4096 2000-01-01 00:00 Data
drwx------ 7 you you 4096 2018-12-12 14:48 Docs
drwx------ 4 you you 4096 2018-12-12 14:48 Tor
drwxr-xr-x 3 you you 4096 2018-12-15 20:38 UpdateInfo
drwxr-xr-x 5 you you 4096 2018-12-04 10:35 vanguards

That is, copy the cloned vanguards there:

(notice, no need to become root, simply as you)

$ cp -ai /your-chosen-dir/vanguards/ /home/you/tor-browser_en-US/Browser/TorBrowser/

It will look something like this:

$ ls -l /home/you/tor-browser_en-US/Browser/TorBrowser/vanguards/
total 124
-rw-r--r-- 1 you you  1989 2018-11-15 22:09 CHANGES.rst
-rw-r--r-- 1 you you  1066 2018-11-14 14:45 LICENSE
-rw-r--r-- 1 you you   316 2018-11-14 14:45 MANIFEST.in
-rw-r--r-- 1 you you  6726 2018-11-14 14:45 README.md
-rw-r--r-- 1 you you 25652 2018-11-15 22:09 README_SECURITY.md
-rw-r--r-- 1 you you 14003 2018-11-15 22:09 README_TECHNICAL.md
-rw-r--r-- 1 you you  1386 2018-11-14 14:45 README_TESTS.md
-rw-r--r-- 1 you you   306 2018-11-15 22:09 requirements.txt
-rw-r--r-- 1 you you   121 2018-11-14 14:45 setup.cfg
-rw-r--r-- 1 you you  2307 2018-11-15 22:09 setup.py
-rwxr-xr-x 1 you you  1070 2018-11-14 14:45 setup.sh
drwxr-xr-x 3 you you  4096 2018-12-14 17:20 src
-rw-r--r-- 1 you you  6500 2018-11-15 22:09 test-requirements.txt
drwxr-xr-x 2 you you  4096 2018-11-15 22:09 tests
-rw-r--r-- 1 you you   636 2018-11-14 14:45 TODO.txt
-rw-r--r-- 1 you you   456 2018-11-14 14:45 tox.ini
-rw-r--r-- 1 you you   870 2018-11-14 14:45 tox-systemonly.ini
-rw-r--r-- 1 you you  2002 2018-11-14 14:45 vanguards.1
-rw-r--r-- 1 you you  4279 2018-11-15 22:09 vanguards-example.conf
$ cd /home/you/tor-browser_en-US/Browser/TorBrowser/Data/Tor/

You can edit the torrc file that is empty in vanilla Tor Browser Bundle install, if you know what you are doing... "man tor" is a long time reference for accomplished tor users :) .

You should run:

$ /home/you/tor-browser_en-US/Browser/TorBrowser/vanguards/src/vanguards.py --help

and read the provided help carefully (the output is the same as given in the System Tor part above.

And once you want to run Vanguards for Tor Browser Bundle, first, in another terminal, start TorBrowser:

$ cd /home/you/tor-browser_en-US/Browser/
$ ./start-tor-browser

(or in some other way)

Go back to the terminal where you ran the --help. This is the long command, but it is self explanatory:

$ /home/you/tor-browser_en-US/Browser/TorBrowser/vanguards/src/vanguards.py --control_port 9151 --loglevel NOTICE --logfile vanguards.log

"9151" is necessary. "9051" is the Debian default control port, so it's occupied. Of course, all can be configured differently, if you, say, know that you need to.

Now issue:

$ Ctrl-Z

followed by:

$ bg

If all is well, it'll tell you:

[3]+  Running /home/you/tor-browser_en-US/Browser/TorBrowser/vanguards/src/vanguards.py --loglevel NOTICE --logfile vanguards.log &

meaning that you successfully sent the running Vanguards to background. It won't be logging anywhere but in the logfile you gave it, and it could appear to you it wasn't running. Nope. It is running, if you correctly followed the instructions, and I didn't mess anything up.

And you can run:

$ tail -f vanguards.log

to read the log messages as they are being written.

Concluding Notes

What you get with Vanguards, is, and this is from the long time regular reference of any wanna-be accomplished Tor user:

           C - G - L2 - L3 - Rend

           C - G - L2 - L3 - M - HSDir

           C - G - L2 - L3 - M - Intro

           S - G - L2 - L3 - M - Rend

           S - G - L2 - L3 - HSDir

           S - G - L2 - L3 - Intro

But please read about that yourself there.

The "there" being the long time returning-to reference of striving to become accomplished Tor users, which is, of course: "man tor" :) .

With vanguards you get a very much boosted anonymity, in case you don't make mistakes of your own, or your Tor --or any related part of your system that Tor needs for that matter-- gets compromised, or if you don't betray yourself by some other means.

And read the very useful links in Mike Perry's repo's README's, as well as: by no means allow yourself to skip the testimony of a leaked info how 3-hops only regular, non-vanguards-boosted Tor circuits can get sometimes even easily deanonymized (only 3 hops is the vanilla Tor, while Vanguards gives you 4 and 5 hops) in the link given at top, somewhere around here:

Announcing the Vanguards Add-On for Onion Services | Tor Blog (but wasn't there more that it is now on it there? I remember some of the contributors there spoke of some leaker, that was the word... who reported to him how the big companies deanonymize Tor when the hops are too few... But maybe I misremembered...)

Some downsides to using Vanguards exist too, and Mike Perry wrote about those in his README's --it's you are being recognizable as Vanguards user, because of your using of, usually, two Entry nodes, regular Tor uses only one--, but they will all be neutralized once Vanguards is hopefully fully integrated in Tor. Till then, use Vanguards in simple ways described in this Howto. Because the advantages far outsurpass the downsides.

Last modified 5 weeks ago Last modified on Dec 17, 2018, 4:42:10 PM