README.md

Overview

Exitmap is a fast and modular Python-based scanner for
Tor exit relays. Exitmap modules implement tasks
that are run over (a subset of) all exit relays. If you have a background in
functional programming, think of exitmap as a map() interface for Tor exit
relays: Modules can perform any TCP-based networking task like fetching a web
page, uploading a file, connecting to an SSH server, or joining an IRC channel.

In practice, exitmap is useful to monitor the reliability and trustworthiness of
exit relays. The Tor Project uses exitmap to check for false negatives on the
Tor Project's check service and to find
malicious exit relays. It is
easy to develop new modules for exitmap; just have a look at the file HACKING in
the doc/ directory or check out one of the existing modules.

Exitmap uses Stem to create circuits to all given
exit relays. Each time tor notifies exitmap of an established circuit, a module
is invoked for the newly established circuit. Modules can be pure Python
scripts or executables. For executables,
torsocks is necessary.

Finally, note that exitmap is a network measurement tool and of little use to
ordinary Tor users. The Tor Project is already running the tool regularly.
More exitmap scans just cause unnecessary network load. The only reason exitmap
is publicly available is because its source code and design might be of interest
to some.

Installation

Exitmap uses the library Stem to communicate with Tor. There are
plenty of ways to install Stem.
The easiest might be to use pip in combination with the provided
requirements.txt file:

$ pip install -r requirements.txt

Running exitmap

The only argument exitmap requires is the name of a module. For example, you
can run exitmap with the checktest module by running:

$ ./bin/exitmap checktest

The command line output will then show you how Tor bootstraps, the output of the
checktest module, and a scan summary. If you don't need three hops and prefer
to use two hops with a static first hop, run: