<h1 align="center">🧅 𝙏𝙤𝙧𝙍𝙪𝙣𝙣𝙚𝙧</h1>
<p align="center">TorRunner is a Python package designed to facilitate the deployment of Tor hidden services. It simplifies the process by allowing you to set up and run a hidden service that listens on a specified port. This package automates the installation and configuration of the Tor software, removing the need for manual setup and making it easier to get started.</p>
<p align="center"><a rel="noreferrer noopener" href="https://github.com/tn3w/TorRunner"><img alt="Github" src="https://img.shields.io/badge/Github-141e24.svg?&style=for-the-badge&logo=github&logoColor=white"></a> <a rel="noreferrer noopener" href="https://pypi.org/project/tor-runner/"><img alt="PyPI" src="https://img.shields.io/badge/PyPi-141e24.svg?&style=for-the-badge&logo=python&logoColor=white"></a> <a rel="noreferrer noopener" href="https://libraries.io/pypi/tor-runner"><img alt="Libraries.io" src="https://img.shields.io/badge/Libraries.io-141e24.svg?&style=for-the-badge&logo=npm&logoColor=white"></a></p>
<br>
## Special thanks
This project uses the Vanguards implementation of [mikeperry-tor](https://github.com/mikeperry-tor) at [mikeperry-tor/vanguards](https://github.com/mikeperry-tor/vanguards) under MIT license found [here](https://github.com/mikeperry-tor/vanguards/blob/master/LICENSE), the socks implementation of [Anorov](https://github.com/Anorov) at [Anorov/PySocks](https://github.com/Anorov/PySocks) under BSD License found [here](https://github.com/Anorov/PySocks/blob/master/LICENSE) and the win_inet_pton implementation of [hickeroar](https://github.com/hickeroar) at [hickeroar/win_inet_pton](https://github.com/hickeroar/win_inet_pton) under Public Domain License found [here](https://github.com/hickeroar/win_inet_pton/blob/master/LICENSE).
## 📌 Planned for the future
- [x] Vanguards
- [ ] Auto Bridge Updates
- [ ] Multi Threads
- [ ] Tor version check & auto update
- [x] Proxy mode [only for urllib implemented]<br>
❌ (not feasible) Tor preinstalled
## 🚀 Installation
Make sure you have the latest version of Python and Pip installed.
1. Create an virtual env with `python3 -m venv .venv` and `source .venv/bin/activate`
2. Install TorRunner with pip `pip install tor-runner` or manually via `git clone https://github.com/tn3w/TorRunner` or download the zip [here](https://github.com/tn3w/TorRunner/archive/refs/heads/master.zip).
3. If you installed it manually, run `pip install .` in the downloaded and extracted folder.
4. [Optional] Install stem with `pip install stem` if you want to use Vanguards.
<br>
Quick command (Linux / macOS):
```bash
python -m venv .venv; source .venv/bin/activate; pip install tor-runner
```
Quick command (Windows):
```bash
python -m venv .venv; .venv/Scripts/activate.bat; pip install tor-runner
```
## Examples
### TorProxy
TorRunner has the ability to route your urllib requests through Tor.
Example:
```python
import time
import urllib.request
import urllib.error
from tor_runner import TorProxy
proxy = TorProxy()
proxy.start()
print("SocksPort running on 127.0.0.1:" + str(proxy.socks_port))
with proxy.urllib():
start_time = time.time()
url = "https://check.torproject.org/?lang=en_US"
try:
response = urllib.request.urlopen(url)
content = response.read().decode('utf-8')
if "Congratulations" in content:
print("Connected to Tor!")
elif "Sorry" in content:
print("Not connected to Tor")
except urllib.error.URLError as e:
print(f"Error connecting to {url}: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
first_byte_time = time.time() - start_time
print(f"Time to first byte: {first_byte_time:.4f} seconds")
```
---
### On the command line
```bash
tor_runner --help
```
Output:
```
usage: tor_runner [-h] [-p PORT] [-l [LISTENER ...]] [-t THREADS] [-d [HIDDEN_SERVICE_DIRS ...]] [-b [BRIDGES ...]] [-s SOCKS_PORT] [-v [VANGUARDS]] [--bridge-quantity BRIDGE_QUANTITY]
[--default-bridge-type DEFAULT_BRIDGE_TYPE] [--direct] [--delete] [--quiet]
Run as a Tor hidden service, allowing configuration of listeners, hidden service directories, and bridges.
options:
-h, --help show this help message and exit
-p PORT, --port PORT HTTP port for the hidden service to listen on.
-l [LISTENER ...], --listener [LISTENER ...]
List of listeners in the format 'tor_port,listen_port'.
-t THREADS, --threads THREADS
How many times Tor should start. (default: 1)
-d [HIDDEN_SERVICE_DIRS ...], --hidden-service-dirs [HIDDEN_SERVICE_DIRS ...]
Directories for storing hidden service keys and hostname files.
-b [BRIDGES ...], --bridges [BRIDGES ...]
List of bridges to use for connecting to the Tor network.
-s SOCKS_PORT, --socks-port SOCKS_PORT
SOCKS port for Tor connections.
-v [VANGUARDS], --vanguards [VANGUARDS]
Enables Vanguards with an optional thread count to protect against guard discovery and related traffic analysis attacks.
--bridge-quantity BRIDGE_QUANTITY
Number of bridges to use for connecting to the Tor network.
--default-bridge-type DEFAULT_BRIDGE_TYPE
Default bridge type to use when connecting to Tor.
--direct Executes your command directly via Tor.
--delete Delete all data associated with tor_runner.
--quiet Run the script in quiet mode with no output.
```
---
### Without an App
```python
from tor_runner import TorRunner
# Uses 11 default obfs4 bridges to connect
runner = TorRunner(
hs_dirs = ["/path/to/hs"], bridges = [],
default_bridge_type = "obfs4", bridge_quantity = 11
)
if __name__ == '__main__':
# Forwards 5000 -> 80 and 22 -> 22
runner.run([(5000, 80), (22, 22)], socks_port = 9050, quite = False, wait = True)
```
---
### For Flask
```python
from flask import Flask
from tor_runner import TorRunner
app = Flask(__name__)
# Uses 11 default obfs4 bridges to connect
runner = TorRunner(default_bridge_type = "obfs4", bridge_quantity = 11)
@app.route('/')
def index():
"""
Route accessible via the Tor network
"""
return 'Hello, Anonymous!🖐️'
if __name__ == '__main__':
runner.flask_run(app, host = '127.0.0.1', port = 9000)
```
---
### For Sanic
```python
from sanic import Sanic, HTTPResponse
from sanic.response import text
from tor_runner import TorRunner
app = Sanic(__name__)
# Uses 11 default obfs4 bridges to connect
runner = TorRunner(default_bridge_type = "obfs4", bridge_quantity = 11)
@app.route('/')
async def index(request) -> HTTPResponse:
"""
Route accessible via the Tor network
"""
return text('Hello, Anonymous!🖐️')
if __name__ == '__main__':
runner.sanic_run(app, host = '127.0.0.1', port = 8000, workers = 16)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tn3w/TorRunner",
"name": "tor-runner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "tor, flask, sanic, hidden-service, security, privacy",
"author": "TN3W",
"author_email": "tn3w@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/9d/a7/21cae9c93137931f971c803b595ce54435de632211eb716b6a0fffc557bb/tor_runner-1.5.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\ud83e\uddc5 \ud835\ude4f\ud835\ude64\ud835\ude67\ud835\ude4d\ud835\ude6a\ud835\ude63\ud835\ude63\ud835\ude5a\ud835\ude67</h1>\n<p align=\"center\">TorRunner is a Python package designed to facilitate the deployment of Tor hidden services. It simplifies the process by allowing you to set up and run a hidden service that listens on a specified port. This package automates the installation and configuration of the Tor software, removing the need for manual setup and making it easier to get started.</p>\n<p align=\"center\"><a rel=\"noreferrer noopener\" href=\"https://github.com/tn3w/TorRunner\"><img alt=\"Github\" src=\"https://img.shields.io/badge/Github-141e24.svg?&style=for-the-badge&logo=github&logoColor=white\"></a> <a rel=\"noreferrer noopener\" href=\"https://pypi.org/project/tor-runner/\"><img alt=\"PyPI\" src=\"https://img.shields.io/badge/PyPi-141e24.svg?&style=for-the-badge&logo=python&logoColor=white\"></a> <a rel=\"noreferrer noopener\" href=\"https://libraries.io/pypi/tor-runner\"><img alt=\"Libraries.io\" src=\"https://img.shields.io/badge/Libraries.io-141e24.svg?&style=for-the-badge&logo=npm&logoColor=white\"></a></p>\n\n<br>\n\n## Special thanks\nThis project uses the Vanguards implementation of [mikeperry-tor](https://github.com/mikeperry-tor) at [mikeperry-tor/vanguards](https://github.com/mikeperry-tor/vanguards) under MIT license found [here](https://github.com/mikeperry-tor/vanguards/blob/master/LICENSE), the socks implementation of [Anorov](https://github.com/Anorov) at [Anorov/PySocks](https://github.com/Anorov/PySocks) under BSD License found [here](https://github.com/Anorov/PySocks/blob/master/LICENSE) and the win_inet_pton implementation of [hickeroar](https://github.com/hickeroar) at [hickeroar/win_inet_pton](https://github.com/hickeroar/win_inet_pton) under Public Domain License found [here](https://github.com/hickeroar/win_inet_pton/blob/master/LICENSE).\n\n## \ud83d\udccc Planned for the future\n- [x] Vanguards\n- [ ] Auto Bridge Updates\n- [ ] Multi Threads\n- [ ] Tor version check & auto update\n- [x] Proxy mode [only for urllib implemented]<br>\n\u274c (not feasible) Tor preinstalled\n\n## \ud83d\ude80 Installation\nMake sure you have the latest version of Python and Pip installed.\n\n1. Create an virtual env with `python3 -m venv .venv` and `source .venv/bin/activate`\n2. Install TorRunner with pip `pip install tor-runner` or manually via `git clone https://github.com/tn3w/TorRunner` or download the zip [here](https://github.com/tn3w/TorRunner/archive/refs/heads/master.zip).\n3. If you installed it manually, run `pip install .` in the downloaded and extracted folder.\n4. [Optional] Install stem with `pip install stem` if you want to use Vanguards.\n\n<br>\n\nQuick command (Linux / macOS):\n```bash\npython -m venv .venv; source .venv/bin/activate; pip install tor-runner\n```\n\nQuick command (Windows):\n```bash\npython -m venv .venv; .venv/Scripts/activate.bat; pip install tor-runner\n```\n\n## Examples\n### TorProxy\nTorRunner has the ability to route your urllib requests through Tor.\n\nExample:\n```python\nimport time\nimport urllib.request\nimport urllib.error\nfrom tor_runner import TorProxy\n\nproxy = TorProxy()\nproxy.start()\nprint(\"SocksPort running on 127.0.0.1:\" + str(proxy.socks_port))\n\nwith proxy.urllib():\n start_time = time.time()\n url = \"https://check.torproject.org/?lang=en_US\"\n\n try:\n response = urllib.request.urlopen(url)\n content = response.read().decode('utf-8')\n\n if \"Congratulations\" in content:\n print(\"Connected to Tor!\")\n\n elif \"Sorry\" in content:\n print(\"Not connected to Tor\")\n\n except urllib.error.URLError as e:\n print(f\"Error connecting to {url}: {e}\")\n except Exception as e:\n print(f\"Unexpected error: {e}\")\n\n first_byte_time = time.time() - start_time\n print(f\"Time to first byte: {first_byte_time:.4f} seconds\")\n```\n\n---\n\n### On the command line\n```bash\ntor_runner --help\n```\n\nOutput:\n```\nusage: tor_runner [-h] [-p PORT] [-l [LISTENER ...]] [-t THREADS] [-d [HIDDEN_SERVICE_DIRS ...]] [-b [BRIDGES ...]] [-s SOCKS_PORT] [-v [VANGUARDS]] [--bridge-quantity BRIDGE_QUANTITY]\n [--default-bridge-type DEFAULT_BRIDGE_TYPE] [--direct] [--delete] [--quiet]\n\nRun as a Tor hidden service, allowing configuration of listeners, hidden service directories, and bridges.\n\noptions:\n -h, --help show this help message and exit\n -p PORT, --port PORT HTTP port for the hidden service to listen on.\n -l [LISTENER ...], --listener [LISTENER ...]\n List of listeners in the format 'tor_port,listen_port'.\n -t THREADS, --threads THREADS\n How many times Tor should start. (default: 1)\n -d [HIDDEN_SERVICE_DIRS ...], --hidden-service-dirs [HIDDEN_SERVICE_DIRS ...]\n Directories for storing hidden service keys and hostname files.\n -b [BRIDGES ...], --bridges [BRIDGES ...]\n List of bridges to use for connecting to the Tor network.\n -s SOCKS_PORT, --socks-port SOCKS_PORT\n SOCKS port for Tor connections.\n -v [VANGUARDS], --vanguards [VANGUARDS]\n Enables Vanguards with an optional thread count to protect against guard discovery and related traffic analysis attacks.\n --bridge-quantity BRIDGE_QUANTITY\n Number of bridges to use for connecting to the Tor network.\n --default-bridge-type DEFAULT_BRIDGE_TYPE\n Default bridge type to use when connecting to Tor.\n --direct Executes your command directly via Tor.\n --delete Delete all data associated with tor_runner.\n --quiet Run the script in quiet mode with no output.\n```\n\n---\n\n### Without an App\n```python\nfrom tor_runner import TorRunner\n\n# Uses 11 default obfs4 bridges to connect\nrunner = TorRunner(\n hs_dirs = [\"/path/to/hs\"], bridges = [],\n default_bridge_type = \"obfs4\", bridge_quantity = 11\n)\n\nif __name__ == '__main__':\n # Forwards 5000 -> 80 and 22 -> 22\n runner.run([(5000, 80), (22, 22)], socks_port = 9050, quite = False, wait = True)\n```\n\n---\n\n### For Flask\n```python\nfrom flask import Flask\nfrom tor_runner import TorRunner\n\napp = Flask(__name__)\n\n# Uses 11 default obfs4 bridges to connect\nrunner = TorRunner(default_bridge_type = \"obfs4\", bridge_quantity = 11)\n\n@app.route('/')\ndef index():\n \"\"\"\n Route accessible via the Tor network\n \"\"\"\n\n return 'Hello, Anonymous!\ud83d\udd90\ufe0f'\n\nif __name__ == '__main__':\n runner.flask_run(app, host = '127.0.0.1', port = 9000)\n```\n\n---\n\n### For Sanic\n```python\nfrom sanic import Sanic, HTTPResponse\nfrom sanic.response import text\nfrom tor_runner import TorRunner\n\napp = Sanic(__name__)\n\n# Uses 11 default obfs4 bridges to connect\nrunner = TorRunner(default_bridge_type = \"obfs4\", bridge_quantity = 11)\n\n@app.route('/')\nasync def index(request) -> HTTPResponse:\n \"\"\"\n Route accessible via the Tor network\n \"\"\"\n\n return text('Hello, Anonymous!\ud83d\udd90\ufe0f')\n\nif __name__ == '__main__':\n runner.sanic_run(app, host = '127.0.0.1', port = 8000, workers = 16)\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "TorRunner is designed to facilitate the deployment of Tor hidden services.",
"version": "1.5",
"project_urls": {
"Homepage": "https://github.com/tn3w/TorRunner"
},
"split_keywords": [
"tor",
" flask",
" sanic",
" hidden-service",
" security",
" privacy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5ac8b197b08650c17e63804e8ce7c029bac80df6d74dddbbe3a247118f3a050",
"md5": "ad47f98b7b202c29abf6f31a02d2a987",
"sha256": "b465b98a597f104b4bf6907b828bdc7d381bfb64ee4a8d32297154ebe69fb624"
},
"downloads": -1,
"filename": "tor_runner-1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad47f98b7b202c29abf6f31a02d2a987",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 63053,
"upload_time": "2024-10-27T11:16:06",
"upload_time_iso_8601": "2024-10-27T11:16:06.347636Z",
"url": "https://files.pythonhosted.org/packages/d5/ac/8b197b08650c17e63804e8ce7c029bac80df6d74dddbbe3a247118f3a050/tor_runner-1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9da721cae9c93137931f971c803b595ce54435de632211eb716b6a0fffc557bb",
"md5": "a98f758a6e061548772c6d201ec1314c",
"sha256": "a82d985979d7dda8bfbe898ae0dc0030c0092c65c90e69d55ae0aa6a89ea61d3"
},
"downloads": -1,
"filename": "tor_runner-1.5.tar.gz",
"has_sig": false,
"md5_digest": "a98f758a6e061548772c6d201ec1314c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 58336,
"upload_time": "2024-10-27T11:16:07",
"upload_time_iso_8601": "2024-10-27T11:16:07.834903Z",
"url": "https://files.pythonhosted.org/packages/9d/a7/21cae9c93137931f971c803b595ce54435de632211eb716b6a0fffc557bb/tor_runner-1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-27 11:16:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tn3w",
"github_project": "TorRunner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tor-runner"
}
JSON
