<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).
## 📌 Planned for the future
- [x] Vanguards
- [ ] Auto Bridge Updates
- [ ] Multi Threads
- [ ] Tor version check & auto update
- [ ] Proxy mode<br>
❌ (not feasible) Tor preinstalled
## Examples
Note: TorRunner uses only built-in Python libraries, if you want to use vanguards, install stem with `pip install stem` after you have created a virtual environment: `python3 -m venv .venv` and activated: `source .venv/bin/activate`.
### 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/2a/79/849cccc6e3810cb7d3d51e0d4269bac0b83f37611c3a8c8925bbee02309f/tor_runner-1.4.8.2.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).\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- [ ] Proxy mode<br>\n\u274c (not feasible) Tor preinstalled\n\n## Examples\nNote: TorRunner uses only built-in Python libraries, if you want to use vanguards, install stem with `pip install stem` after you have created a virtual environment: `python3 -m venv .venv` and activated: `source .venv/bin/activate`.\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.4.8.2",
"project_urls": {
"Homepage": "https://github.com/tn3w/TorRunner"
},
"split_keywords": [
"tor",
" flask",
" sanic",
" hidden-service",
" security",
" privacy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17f3eb565e50fe5d1baf29396de35a376b54089be34b6850e72232b332a50669",
"md5": "ceaffa796fb248a248834c0be20b31e0",
"sha256": "bd5329e517cf0a2dcaf36f16edb69f79f5a571cabc172a7c0fb43bafdd88c64c"
},
"downloads": -1,
"filename": "tor_runner-1.4.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ceaffa796fb248a248834c0be20b31e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 51327,
"upload_time": "2024-10-22T16:41:05",
"upload_time_iso_8601": "2024-10-22T16:41:05.466891Z",
"url": "https://files.pythonhosted.org/packages/17/f3/eb565e50fe5d1baf29396de35a376b54089be34b6850e72232b332a50669/tor_runner-1.4.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2a79849cccc6e3810cb7d3d51e0d4269bac0b83f37611c3a8c8925bbee02309f",
"md5": "4b8e80958bc87ef5232302c011e79c73",
"sha256": "ce29c7376511164d92b6908ea74bda5069da7a46aad7917a6444245b3fc3ee39"
},
"downloads": -1,
"filename": "tor_runner-1.4.8.2.tar.gz",
"has_sig": false,
"md5_digest": "4b8e80958bc87ef5232302c011e79c73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 47842,
"upload_time": "2024-10-22T16:41:06",
"upload_time_iso_8601": "2024-10-22T16:41:06.664265Z",
"url": "https://files.pythonhosted.org/packages/2a/79/849cccc6e3810cb7d3d51e0d4269bac0b83f37611c3a8c8925bbee02309f/tor_runner-1.4.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 16:41:06",
"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
