A comprehensive Python library for managing Tor processes with full lifecycle control. dtor handles everything from automatic binary downloads to hidden service management, providing a simple and powerful interface for Tor integration.
🚀 Automatic Setup
- Automatic Tor binary download for your platform (Linux, Windows, macOS)
- Smart version detection and caching
- Zero manual configuration required
🔒 Hidden Services
- Easy hidden service creation and management
- Runtime hidden service support (ADD_ONION)
- Automatic hostname and key generation
- Port mapping and collision resolution
⚙️ Process Management
- Full Tor process lifecycle control (start/stop/restart)
- Process monitoring and health checks
- Stale process cleanup
- Cross-platform support
🌐 Port Management
- SOCKS and Control port configuration
- Runtime port addition
- Automatic port conflict detection and resolution
- Multiple port support
🎛️ Control Protocol
- Full Tor control protocol support
- Cookie authentication
- Command execution and response parsing
- Real-time configuration updates
pip install dtorfromdtorimportTorHandler# Initialize handlerhandler=TorHandler(recover=False)
# Download Tor binaries (automatic platform detection)handler.download_and_install_tor_binaries()
# Configure portshandler.add_socks_port(9050)
handler.add_control_port(9051)
# Start Torhandler.start_tor_service()
# Create a hidden servicehandler.register_hidden_service(port=80, target_port=8080)
handler.save_torrc_configuration()
# Stop Tor when donehandler.stop_tor_service()handler=TorHandler()
# Enable automatic port conflict resolutionhandler.socks_port_collision_resolve=Truehandler.control_port_collision_resolve=True# Add ports - will auto-resolve if already in usehandler.add_socks_port(9050)
handler.add_control_port(9051)Runtime Hidden Services
# Start Tor firsthandler.start_tor_service()
# Add hidden service at runtime (no restart needed)result=handler.register_runtime_hidden_service(
port=80, target_port=8080, temporary=False
)
ifresult:
print(f"Onion address: {result['onion_address']}")
print(f"Service key: {result['service_key']}")# Send commands to Tor control portresponses=handler.send_control_commands([
"GETINFO version",
"GETINFO status/bootstrap-phase",
"GETINFO network-status"
])
foridx, responseinresponses.items():
print(f"{response['command']}: {response['response']}")# Get process informationprocess=handler.get_tor_process()
ifprocess:
print(f"PID: {process.pid}")
print(f"Status: {process.status()}")
print(f"Memory: {process.memory_info().rss/1024/1024:.2f} MB")
print(f"CPU: {process.cpu_percent()}%")Multiple Hidden Services
handler=TorHandler()
# Register multiple servicesservices= [
(80, 8080, "HTTP"),
(443, 8443, "HTTPS"),
(22, 2222, "SSH")
]
forport, target, nameinservices:
result=handler.register_hidden_service(
port=port, target_port=target
)
print(f"Registered {name}: {port} -> {target}")
# Save configurationhandler.save_torrc_configuration()handler=TorHandler(
recover=True# Load existing configuration on startup
)handler.max_socks_ports=3# Maximum SOCKS portshandler.max_control_ports=3# Maximum control portshandler.max_hidden_services=3# Maximum hidden serviceshandler.debug=True# Enable debug logginghandler.log_level=0# 0=INFO, 1=WARNING, 2=ERRORBy default, dtor creates the following directory structure:
tor_handler_files/
├── tor_binaries/ # Tor executables
│ ├── tor/
│ └── data/
├── cache/ # Downloaded archives
└── config/
└── torrc # Tor configuration
- ✅ Linux (Ubuntu, Debian, RHEL, etc.)
- ✅ Windows (7, 8, 10, 11)
- ✅ macOS (Intel & Apple Silicon)
- Python 3.8+
- Python 3.9
- Python 3.10
- Python 3.11
- Python 3.12
psutil>=5.9.0- Process managementrequests>=2.28.0- HTTP requests for binary downloads
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Run the comprehensive test suite:
python test.pyThis project is licensed under the MIT License - see the LICENSE file for details.
Ahmad Yousuf
- Email: 0xAhmadYousuf@protonmail.com
- GitHub: @QudsLab
- Tor Project for the amazing anonymity network
- All contributors and users of this library
- PyPI:https://pypi.org/project/dtor/
- GitHub:https://github.com/QudsLab/dtor
- Issues:https://github.com/QudsLab/dtor/issues
- Tor Project:https://www.torproject.org/
This tool is for educational and research purposes. Users are responsible for complying with all applicable laws and regulations. The authors are not responsible for any misuse of this software.