oppy is a Tor onion proxy implementation written in Python. Any further references to "Tor" or "tor"
refer to the protocol, unless otherwise noted, and do not imply endorsement
from The Tor Project organization.
oppy is produced independently from the
Tor® anonymity software and carries no guarantee from The Tor Project about
quality, suitability or anything else.
oppy is free software, distributed under the "modified"
(or 3-clause) BSD license.
To learn more about what Onion Proxies do, please see
tor-spec.txt, the Tor
For full documentation, see: oppy-docs
oppy is provided in the hope it will be useful, however oppy will NOT
provide strong anonymity.
oppy is just a prototype: it's not very well
tested yet, and it makes a number of simplifications.
If you need strong anonymity, please use the official Tor software from The Tor Project.
oppy is, at the moment, mainly meant for developers and hackers to play
First, install the dependencies:
$ pip -r requirements.txt
Now you're ready to clone this repository:
$ git clone https://github.com/nskinkel/oppy
cd to the top-level
oppy directory and add it to your python path
$ export PYTHONPATH=$PYTHONPATH:$(pwd)
Note: the "top-level" directory that should be added to your python path
is the directory containing the
oppy aims to be a fully functional Tor client and can be used just the
same way as a regular Tor client.
oppy supports the following arguments:
-l --log-level python log level, defauls to INFO -f --log-file filename to write logs to, defaults to sys.stdout -p --SOCKS-port local port for oppy's SOCKS interface to listen on (defaults to 10050) -h --help print these options
To run oppy at the DEBUG log level on port 10050, from the oppy/oppy directory run:
$ ./oppy -l debug -p 10050
oppy will print some information as it gathers network status documents and
starts building circuits. After the first circuit opens up,
oppy will be
listening on port 10050 for incoming SOCKS 5 connections.
You can tell any application that can use a SOCKS 5 proxy to use
SSH or Firefox) - just configure that application to use SOCKS 5 on localhost
on the port that
oppy is running on.
You can also tell the Tor Browser to use
oppy instead of its own Tor process.
If you're using a web browser with
oppy, browse to
Tor check to verify
oppy is working.
####Warning: You will not get strong anonymity by running, say, vanilla Firefox through a tor process and using "normal" browsing habits. See a list of warnings for some reasons why this is not sufficient for strong anonymity.
###Bugs and Simplifications Made A few of the major "noticeable" simplifications that directly impact regular usage include:
- oppy doesn't know how to recover from RelayEnd cells sent because of reasons like EXIT_POLICY. In these cases oppy just closes the stream, so this can sometimes look, to the user, like oppy is just not working.
- oppy doesn't currently calculate circuit build timeouts or try to rebuild slow circuits (or circuits which become unresponsive). Again, this can look to the user like oppy has stopped working (e.g. web pages may stop loading if a stream gets assigned to a slow/unresponsive circuit).
- oppy doesn't yet put a timeout on downloading server descriptors, so sometimes this will hang if oppy chooses a bad V2Dir cache.
For a more complete list of the simplifications oppy makes, see: simplifications.md.