hotspot-socks-proxy
A high-performance SOCKS5 proxy server designed to route traffic through WiFi interfaces. Perfect for scenarios where you need to ensure traffic goes through a specific network interface.
Features
Core Functionality
- SOCKS5 proxy server with multi-process support
- Automatic WiFi interface detection and validation
- Built-in DNS resolution with multiple fallback options
- Process pool management with automatic recovery
- Clean shutdown handling
Performance & Reliability
- Multi-process architecture for optimal performance
- Thread-safe statistics tracking
- Automatic process recovery on failure
- Configurable DNS resolvers with fallback mechanisms
- Connection pooling and timeout handling
User Interface
- Real-time terminal UI with bandwidth monitoring
- Live connection statistics
- Clean terminal interface with borders
- Keyboard controls (Ctrl-C to exit)
- Automatic unit scaling for bandwidth display
Network Management
- Automatic WiFi interface detection
- Interface validation and filtering
- IP address management
- Support for both wireless and fallback interfaces
Additional Features
- Clipboard integration for easy proxy configuration sharing
- Support for both Windows and Unix-like systems
- Root privilege checking
- Comprehensive error handling and reporting
Installation
pip install hotspot-socks-proxy
Usage
Run the proxy server (requires root/admin privileges):
# Basic usage
sudo hotspot-proxy proxy
# Custom port and processes
sudo hotspot-proxy proxy --port 9050 --processes 4
Options
--processes/-p: Number of proxy processes (default: CPU count)--port: Port to listen on (default: 9050)
Example Code
from hotspot_socks_proxy.core.proxy import create_proxy_server
# Start a SOCKS proxy server on localhost:9050 with 4 processes
create_proxy_server("127.0.0.1", 9050, 4)
Requirements
- Python >= 3.12
- Root/Administrator privileges for proper operation
- Required packages (automatically installed):
- typer: CLI interface
- prompt-toolkit: Terminal UI
- rich: Pretty output formatting
- psutil: System and process utilities
- pyperclip: Clipboard integration
- dnspython: DNS resolution
Development
Project Structure
src/hotspot_socks_proxy/
├── cmd/ # Command-line interface modules
│ ├── cli.py # Main CLI entry point
│ ├── find_wifi.py # WiFi interface detection
│ ├── http.py # HTTP proxy implementation
│ └── socks.py # SOCKS proxy interface
├── core/ # Core functionality
│ ├── lib/ # Core library components
│ │ ├── proxy_server.py # Multi-process server
│ │ ├── proxy_stats.py # Statistics tracking
│ │ ├── proxy_ui.py # Terminal UI
│ │ └── socks_handler.py # SOCKS protocol handler
│ ├── exceptions.py # Custom exceptions
│ ├── network.py # Network interface management
│ └── proxy.py # Main entry point
Documentation
Full documentation is available at [GitHub Pages URL].
License
This project is licensed under the GPL-3.0 License.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1 maintainer
Metadata
1 maintainer
Release files for hotspot-socks-proxy 3.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| hotspot_socks_proxy-3.4.0.tar.gz | 23.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hotspot_socks_proxy-3.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 48.8 kB
Release files / hotspot_socks_proxy-3.4.0.tar.gz
| Download URL | hotspot_socks_proxy-3.4.0.tar.gz |
|---|---|
| Size | 23.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
11470a1a8ef6ffefc6b4f99e9acaa14c461377bf6e462f5cb4b0bc8bcff88182
|
|
BLAKE2b-256 checksum How to use checksums |
20c9833e069025988152e9091f68fbae55c7a9bcefe210e201634da0d1f433e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.13.0
|
Release files / hotspot_socks_proxy-3.4.0-py3-none-any.whl
| Download URL | hotspot_socks_proxy-3.4.0-py3-none-any.whl |
|---|---|
| Size | 25.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69940d007abe5e5b11390f40260cd1260dd86ab23c95d8d7c8864095483aca11
|
|
BLAKE2b-256 checksum How to use checksums |
318beda41dba27ca7bd5446951cde02df46b00c3aed811c88807d3c598d04d01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.13.0
|
Security for hotspot-socks-proxy 3.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
