Scribd
Upload
42 views7 pages

Tor Hidden Service Setup for Flask Apps

This document provides a comprehensive guide for setting up a Python Flask web application as a Tor v3 hidden service on both Windows and Linux platforms. It includes detailed instructions for preparing the app, configuring Tor, implementing client authorization, testing, and security hardening. The guide also features example files and commands to facilitate the setup process.

Uploaded by

community.b52
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
42 views7 pages

Tor Hidden Service Setup for Flask Apps

This document provides a comprehensive guide for setting up a Python Flask web application as a Tor v3 hidden service on both Windows and Linux platforms. It includes detailed instructions for preparing the app, configuring Tor, implementing client authorization, testing, and security hardening. The guide also features example files and commands to facilitate the setup process.

Uploaded by

community.b52
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Tor website setup (Windows & Linux) — Python +

Flask
A step-by-step printable guide to host a Python web app behind a Tor v3 hidden service on
Windows and Linux. Includes example torrc , a minimal Flask app, running Tor, client
authorization, systemd unit for Linux, running as a Windows background task, testing,
security hardening, and optional client instructions.

Contents
1. Goals and assumptions
2. Quick architecture
3. Files included in this guide
4. Part A — Prepare the Python web app (cross-platform)
5. Part B — Tor setup on Windows
6. Part C — Tor setup on Debian/Ubuntu Linux
7. Part D — Optional: client authorization (stealth clients)
8. Part E — Testing & troubleshooting
9. Part F — Security hardening
10. Appendix: Useful commands and examples

1. Goals and assumptions


• Goal: run a local Python web app (Flask) bound to [Link]:8080 , and expose it as a Tor v3
hidden service (onion) so remote Tor clients can reach it via an .onion address.
• You control both machines and have permission to run Tor and the app.
• This guide shows both Windows (Tor Expert Bundle + Python) and Linux (Debian/Ubuntu) (Tor
package + systemd) instructions.
• The app listens on [Link] (localhost) — never bind to [Link] for better security.

2. Quick architecture
• Your Python app runs locally on [Link]:8080 .
• Tor runs on the same host and has a Hidden Service configured that maps HiddenServicePort
<port> [Link]:8080 .
• Tor publishes an onion address; remote Tor clients connect to that onion address and Tor forwards
traffic to your local Flask app.

1
3. Files included in this guide (copy/paste)
• [Link] — minimal Flask HTML page. (Example provided.)
• torrc — Tor configuration snippets for Windows and Linux.
• [Link] — example systemd unit for the Python app (Linux).

4. Part A — Prepare the Python web app (cross-platform)


Create a directory for your project (e.g., C:\tor\site on Windows or /opt/onion-site on Linux).

Install Python & Flask

• Windows: install Python from [Link] (include pip). Open PowerShell:

python -m pip install --upgrade pip


pip install flask

• Linux (Debian/Ubuntu):

sudo apt update


sudo apt install python3 python3-venv python3-pip -y
python3 -m pip install --user --upgrade pip
python3 -m pip install --user flask

Create ``

# [Link]
from flask import Flask, Response
app = Flask(__name__)

HTML_PAGE = '''<!doctype html>


<html><head><meta charset="utf-8"><title>Onion Site</title></head>
<body><h1>Welcome to my Onion Service</h1>
<p>Served by Flask on [Link]:8080</p></body></html>'''

@[Link]('/')
def index():
return Response(HTML_PAGE, mimetype='text/html')

if __name__ == '__main__':
[Link](host='[Link]', port=8080)

2
Test locally

• Run:

python [Link]

• Open: [Link] in a browser — you should see the page.

5. Part B — Tor setup on Windows

5.1 Download Tor Expert Bundle

1. Download Tor Expert Bundle (ZIP) from the official Tor Project site: [Link]
download/tor/
2. Extract to C:\tor (example path). You should have C:\tor\[Link] .

5.2 Create torrc for the hidden service

In C:\tor create a file named torrc (no .txt extension). Example content to expose web and SFTP
(optional):

# web hidden service


HiddenServiceDir C:\tor\myservice\hidden_service
HiddenServiceVersion 3
HiddenServicePort 80 [Link]:8080

# optional additional service (e.g., ssh on local 22)


# HiddenServiceDir C:\tor\sftp_service\hidden_service
# HiddenServiceVersion 3
# HiddenServicePort 2222 [Link]:22

Notes:

• Tor will create the hidden_service dir and generate keys. The onion address appears in
hostname file inside that folder.
• If you want client authorization, see Part D.

5.3 Start Tor

Open PowerShell and run (explicit path recommended):

cd C:\tor
. [Link] -f C:\tor\torrc --Log "notice stdout"

3
Look for lines:

• Hidden service directory C:\tor\myservice\hidden_service/


• Your v3 Hidden Service is available at <[Link]>

Copy the onion address from C:\tor\myservice\hidden_service\hostname .

5.4 Run Flask app and test

• Start python [Link] (ensure it binds to [Link]:8080 ).


• Open Tor Browser and visit [Link] (use HTTP unless you added TLS).

5.5 Run Tor as a Windows service (optional)

• For background running, use Task Scheduler or nssm to register [Link] as a service.
• Alternatively, start Tor via a startup script.

6. Part C — Tor setup on Debian/Ubuntu Linux

6.1 Install Tor

Use the Tor Project repo for latest or the distro package for simplicity. Quick commands (distro repo):

sudo apt update


sudo apt install tor -y

Tor's config lives in /etc/tor/torrc (system-wide) or you can use a custom torrc.

6.2 Add hidden service to /etc/tor/torrc

Add this block (requires root to edit):

HiddenServiceDir /var/lib/tor/myservice/hidden_service
HiddenServiceVersion 3
HiddenServicePort 80 [Link]:8080

Save and restart Tor:

sudo systemctl restart tor


sudo journalctl -u tor -n 200 --no-pager

Check the onion address:

4
sudo cat /var/lib/tor/myservice/hidden_service/hostname

6.3 Create systemd service for the Flask app (optional)

Create /etc/systemd/system/[Link] :

[Unit]
Description=Onion Flask App
After=[Link]

[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/onion-site
ExecStart=/usr/bin/python3 /opt/onion-site/[Link]
Restart=on-failure
PrivateTmp=true
NoNewPrivileges=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=[Link]

Enable & start:

sudo systemctl daemon-reload


sudo systemctl enable --now onion-app

7. Part D — Optional: Client authorization (stealth)


Client authorization limits which Tor clients can connect to your onion service.

On the server torrc add (example):

HiddenServiceDir /var/lib/tor/myservice/hidden_service
HiddenServiceVersion 3
HiddenServicePort 80 [Link]:8080
HiddenServiceAuthorizeClient stealth client1

5
Restart Tor. Tor will create an authorized_clients file inside the HiddenServiceDir containing a token
line. Copy the generated token (it looks like descriptor:x25519:... ) to the client side.

On a client machine (with Tor), place that token in the Tor data directory ~/.tor/authorized_clients/
(or configure Tor Browser/Orbot per docs) so the client can authenticate when connecting.

8. Part E — Testing & troubleshooting


Tor log tips

• Start Tor with --Log "notice stdout" to see live logs.


• Common issues:
• Unable to open configuration file → torrc missing or wrong path.
• Bootstrapped 55% → network connectivity; firewall or ISP may block Tor. Use bridges if needed.

Quick tests

• Local check: curl [Link]


• Tor Browser: open [Link]
• Using curl via local Tor SOCKS proxy (Tor default 9050 or Tor Browser 9150):

curl --socks5-hostname [Link]:9050 [Link]

Permissions

• Linux: ensure /var/lib/tor/myservice/hidden_service is owned by debian-tor:debian-


tor and not world-readable.

sudo chown -R debian-tor:debian-tor /var/lib/tor/myservice/hidden_service


sudo chmod 700 /var/lib/tor/myservice/hidden_service

9. Part F — Security hardening


• Bind only to localhost ([Link]). Do not bind the app to [Link].
• Run app as unprivileged user. Do not run as root or Administrator.
• Protect HiddenServiceDir: backup and store the private key ( hs_ed25519_secret_key ) offline if
you need to keep the same onion identity. Treat it as a secret.
• Enable authentication inside your app (API tokens, SSH keys for SFTP) — Tor hides network location
but not your app-level authentication.
• Use HTTPS internally if you want end-to-end TLS in addition to Tor (optional) — careful with certs
and client trust.
• Monitor logs: Tor logs ( /var/log/tor or tor stdout), and app logs.

6
• Update software: keep Tor and Python packages updated.

10. Appendix: Useful commands and examples


Windows: start Tor with torrc

C:\tor\[Link] -f C:\tor\torrc --Log "notice stdout"

Linux: restart tor

sudo systemctl restart tor


sudo journalctl -u tor -f

View onion hostname

• Windows: type C:\tor\myservice\hidden_service\hostname


• Linux: sudo cat /var/lib/tor/myservice/hidden_service/hostname

curl via Tor SOCKS

curl --socks5-hostname [Link]:9050 [Link]

Build a Windows .exe for client uploader (PyInstaller)

pip install pyinstaller


pyinstaller --onefile client_send.py

End — Checklist to go live

If you want, I can now:

• convert this document into a downloadable PDF (I can generate it and provide a download link), or
• add screenshots and exact GUI steps for Windows (Notepad save-as, Task Scheduler, WinSCP config),
or
• produce a ready-to-run ZIP with [Link] , torrc examples and [Link] file for Linux.

Tell me which you want next.

Common questions

Powered by AI

Binding the Flask app to 127.0.0.1 instead of 0.0.0.0 is recommended for security reasons. This setting restricts the server's accessibility to only the localhost, preventing external entities from accessing the web service directly through the local network. It enhances security by ensuring that all access must go through the Tor network using the hidden service, preventing exposure of the application to potential external threats on the network .

Monitoring and updating software when maintaining a Tor hidden service is essential for security and functionality. Regular updates address security vulnerabilities and provide new features or improvements. Efficiently achieving this involves keeping servers updated through package managers or official repositories, reviewing logs for anomalous activity, using automated tools where possible for updates, and monitoring official channels for critical security announcements to act promptly .

To harden the security of a Tor hidden service, several measures are recommended: Bind the Flask app only to localhost (127.0.0.1) to prevent unwanted network access; run the app as an unprivileged user, not as root or Administrator, to minimize security risks; protect the HiddenServiceDir by storing the private key offline to maintain the onion identity; implement authentication mechanisms inside your app; consider using HTTPS internally for end-to-end encryption; keep both the Tor and Python software updated; and diligently monitor log files for any suspicious activity .

To configure a Linux system for hosting a Python Flask app using a Tor hidden service, you start by installing Tor using either the distro package or Tor Project repository for the latest version. The hidden service needs to be added to '/etc/tor/torrc', specifying 'HiddenServiceDir', 'HiddenServiceVersion', and 'HiddenServicePort'. After saving changes, restart Tor with 'sudo systemctl restart tor'. To manage the Flask app, create a systemd service file to enable automatic management, starting the service with 'sudo systemctl enable --now onion-app'. Check the generated onion address using 'sudo cat /var/lib/tor/myservice/hidden_service/hostname' .

To set up a Python web app behind a Tor v3 hidden service on a Windows system, you must follow these key steps: First, download the Tor Expert Bundle from the official Tor website and extract it to a location like C:\tor. Next, create a 'torrc' file in the Tor directory to configure the hidden service, specifying parameters like 'HiddenServiceDir' and 'HiddenServicePort'. Start the Flask app ensuring it binds to 127.0.0.1:8080. Then, start Tor using PowerShell with the included torrc file. Finally, use the 'hostname' file located in the 'HiddenServiceDir' to find your onion address and test the setup using a Tor Browser .

To create a systemd service for running a Flask app on Linux, a service file is added at '/etc/systemd/system/onion-app.service'. This file includes configuration under '[Unit]', '[Service]', and '[Install]' sections, with specifics such as 'User', 'ExecStart', and 'WorkingDirectory'. The service can be managed with commands 'sudo systemctl daemon-reload', 'sudo systemctl enable --now onion-app', which enable and start the service automatically on system boot .

Using Tor Browser for testing hidden services is significant because it ensures the service can be accessed as intended over the Tor network, providing an environment that reflects typical user experiences. To test the service, start the Flask application, ensure Tor is running with the correct configuration, and use Tor Browser to visit the onion address provided in the 'hostname' file. This demonstrates the service's functionality and reachability from external clients, ensuring end-to-end validation of the setup .

The 'torrc' file plays a critical role in configuring a Tor hidden service, as it specifies the service's behavior and connectivity features. Key configurations it must include are 'HiddenServiceDir', to designate where configuration files and keys are stored, and 'HiddenServicePort', linking the local web service port to the service accessed by Tor clients. These settings help establish the hidden service and dictate how remote Tor clients interact with it .

To troubleshoot a non-functioning Tor hidden service, start by checking Tor logs for errors, using the '--Log "notice stdout"' option for live logs. Verify the configuration file paths and syntax if "Unable to open configuration file" errors appear. If the process halts at "Bootstrapped 55%", investigate network connectivity, possibly using bridges to bypass restrictions. Test local connectivity with tools like 'curl' and ensure proper permissions for directories. Additionally, review the onion address and configure your client for any required authorization .

Adding client authorization for Tor hidden services involves editing the 'torrc' file to include 'HiddenServiceAuthorizeClient stealth [client-name]', then restarting Tor. This process generates an 'authorized_clients' file in the HiddenServiceDir containing client tokens. These tokens must be transferred to the client's machine and configured into Tor to allow access to the service. Client authorization is significant because it offers an added layer of access control, ensuring that only designated clients can connect to the service, thereby enhancing security and privacy by preventing unauthorized access .

You might also like