Skip to content

Latest commit

 

History

History
111 lines (80 loc) · 4.02 KB

README.md

File metadata and controls

111 lines (80 loc) · 4.02 KB
Raw

Build Status

Coverage Status

#oppy 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 protocol specification.

For full documentation, see: oppy-docs

###Warning 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 with.

###Installation

First, install the dependencies:

$ pip -r requirements.txt

Now you're ready to clone this repository:

$ git clone https://github.com/nskinkel/oppy

Next, 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, docs, and data directories.

###Usage 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 oppy (e.g. 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.