nixort-iprotator 1.0.0

Advanced IP Rotation Tool via Tor Network

🌐 IPRotator

Advanced IP Rotation Tool via Tor Network

---

📋 Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Usage
• Proxy Scanning
• Docker
• API Reference
• Security
• Troubleshooting
• Contributing
• Uninstallation
• License

---

✨ Features

🔒 Privacy & Security

• Automatic IP Rotation — Rotate your IP address at configurable intervals
• Tor Network Integration — Leverages the power of the Tor anonymity network
• System Proxy Management — Automatically configures system-wide proxy settings
• Health Monitoring — Automatic restart on connection failures
• Bridge Support — Bypass censorship with obfs4 bridges

🖥️ Cross-Platform

• Windows — Full registry-based proxy configuration
• Linux — GNOME/KDE desktop environment support
• Docker — Containerized deployment ready

🚀 Advanced Capabilities

• Interactive Controls — Keyboard shortcuts for manual IP changes
• GeoIP Detection — See your exit node's country with emoji flags
• Bootstrap Visualization — Real-time connection progress
• Rich Terminal UI — Beautiful status display with colors
• Comprehensive Logging — Detailed logs for debugging

---

📦 Installation

From PyPI (Recommended)

pip install iprotator

From Source

git clone https://gitlab.com/Nixort/IPRotator.git
cd IPRotator
pip install -e .

Development Installation

git clone https://gitlab.com/Nixort/IPRotator.git
cd IPRotator
pip install -e ".[dev]"

Using Docker

docker pull registry.gitlab.com/nixort/iprotator:latest

---

🚀 Quick Start

1. Start IPRotator

iprotator

2. Interactive Controls

Once running, use these keyboard shortcuts:

Key	Action
N	Request new IP address
I	Check current IP
S	Show status
H	Show help
Q	Quit

3. Configure Your Browser

Set your browser to use SOCKS5 proxy:

• Host: 127.0.0.1
• Port: 9050 (default)

---

⚙️ Configuration

Configuration File Location

~/.config/iprotator/config.yaml

Example Configuration

# Tor network settings
tor:
  socks_port: 9050              # SOCKS5 proxy port
  control_port: 9051            # Tor control port
  rotation_interval_seconds: 300  # Auto-rotate every 5 minutes
  exclude_nodes: "{ru},{cn}"    # Exclude specific countries
  exit_nodes: "{us},{gb}"       # Prefer exit nodes from these countries
  use_bridges: false            # Enable bridges for censorship bypass

# Application settings
app:
  log_level: "INFO"             # DEBUG, INFO, WARNING, ERROR
  system_proxy: true            # Auto-configure system proxy
  auto_restart: true            # Restart on failure
  max_restarts: 5               # Max restart attempts

# Bridges (when use_bridges is true)
bridges:
  - "obfs4 192.95.36.142:443 CDF2E852BF539B82BD10E27E9115A31734E378C2 cert=qUVQ0srL1JI/vO6V6m/24anYXiJD3QPokHROnlQHM0lXKmM9fTde5gFIw1AnFcZ3J2eKjQ iat-mode=0"

Get bridges from: https://bridges.torproject.org/

---

🎮 Usage

Command Line Options

iprotator [OPTIONS]

Options:
  -c, --config PATH           Path to configuration file
  -p, --port INTEGER          SOCKS5 proxy port (default: 9050)
  --control-port INTEGER      Tor control port (default: 9051)
  -i, --interval INTEGER      Rotation interval in seconds
  --no-proxy                  Don't modify system proxy settings
  --daemon                    Run in background mode
  --install                   Install/Update Tor and exit
  --version                   Show version and exit
  -v, --verbose               Enable verbose logging
  -h, --help                  Show help message

Examples

# Start with default settings
iprotator

# Use custom config
iprotator -c /path/to/config.yaml

# Change SOCKS port
iprotator -p 1080

# Rotate every 60 seconds
iprotator -i 60

# Don't set system proxy
iprotator --no-proxy

# Install Tor only
iprotator --install

Programmatic Usage

from iprotator import IPRotator

# Create instance
rotator = IPRotator()

# Start (blocking)
rotator.run()

# Or start interactive mode
rotator.run_interactive()

---

🔍 Proxy Scanning

IPRotator can automatically scan for available proxy servers on your system and suggest the best one for Tor to use as an upstream connection.

Scan for Local Proxies

# Scan for available proxies
iprotator --scan-proxies

# Scan and automatically use best proxy
iprotator --auto-upstream

# Scan and start with best proxy
iprotator --scan-proxies --auto-upstream

Supported Proxy Types

• SOCKS5 — Shadowsocks, V2Ray, Clash (common ports: 1080, 10808, 7890)
• SOCKS4 — Legacy SOCKS proxies
• HTTP/HTTPS — HTTP proxies (common ports: 8080, 3128)

Example Output

🔍 Scanning for available proxies...
--------------------------------------------------
  ✓ Found working proxy: socks5://127.0.0.1:10808 (0.23s)
  ✓ Found working proxy: socks5://127.0.0.1:7890 (0.45s)
--------------------------------------------------

✓ Found 2 working proxy(s):
  1. SOCKS5 127.0.0.1:10808 (0.23s) 🇺🇸 United States
  2. SOCKS5 127.0.0.1:7890 (0.45s) 🇸🇬 Singapore

⭐ Best proxy: socks5://127.0.0.1:10808 (0.23s)

💡 To use this proxy as upstream, add to your config.yaml:

tor:
  upstream_proxy:
    enabled: true
    type: "socks5"
    host: "127.0.0.1"
    port: 10808

Programmatic Usage

from iprotator.proxy_scanner import ProxyScanner

# Create scanner
scanner = ProxyScanner(timeout=10)

# Scan for local proxies
proxies = scanner.scan_local_proxies()

# Get best proxy
best = scanner.get_best_proxy()
if best:
    print(f"Best proxy: {best.address} ({best.response_time:.2f}s)")

---

🐳 Docker

Run with Docker

# Run container
docker run -it --rm \
  -p 9050:9050 \
  -p 9051:9051 \
  registry.gitlab.com/nixort/iprotator:latest

# With custom config
docker run -it --rm \
  -p 9050:9050 \
  -p 9051:9051 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  registry.gitlab.com/nixort/iprotator:latest \
  -c /app/config.yaml

Docker Compose

version: '3.8'

services:
  iprotator:
    image: registry.gitlab.com/nixort/iprotator:latest
    container_name: iprotator
    ports:
      - "9050:9050"
      - "9051:9051"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - tor-data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-s", "--socks5-hostname", "127.0.0.1:9050", "https://check.torproject.org/api/ip"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  tor-data:

Build from Dockerfile

docker build -t iprotator:latest .
docker run -it --rm -p 9050:9050 iprotator:latest

---

📚 API Reference

IPRotator Class

class IPRotator:
    """Main IPRotator application class."""
    
    def __init__(self, config_path: Optional[str] = None)
    def start(self) -> None                    # Start IPRotator
    def run(self) -> None                      # Run (blocking)
    def run_interactive(self) -> None          # Run with keyboard controls
    def change_ip(self) -> bool                # Manually change IP
    def show_status(self) -> None              # Display status
    def shutdown(self) -> None                 # Graceful shutdown

TorManager Class

class TorManager:
    """Manages Tor process lifecycle."""
    
    def ensure_tor(self) -> bool               # Install/ensure Tor
    def start(self, on_bootstrap) -> bool      # Start Tor process
    def stop(self) -> None                     # Stop Tor process
    def send_newnym(self) -> bool              # Request new identity
    def check_ip(self) -> Optional[TorInfo]    # Check current IP

ProxyManager Class

class ProxyManager:
    """Manages system proxy settings."""
    
    def enable(self) -> bool                   # Enable system proxy
    def disable(self) -> bool                  # Disable system proxy

---

🔐 Security

Best Practices

1. Always verify Tor connection — Check https://check.torproject.org to confirm
2. Use HTTPS — Ensure websites use HTTPS for end-to-end encryption
3. Disable WebRTC — Prevent IP leaks in browsers
4. Use bridges — In censored regions, use obfs4 bridges
5. Regular updates — Keep IPRotator and Tor updated

Security Features

• ✅ Isolated Tor process
• ✅ No logging of sensitive data
• ✅ Automatic cleanup on exit
• ✅ Non-root Docker execution
• ✅ Secure signal handling

---

🔧 Troubleshooting

Common Issues

Tor won't start

# Check if ports are free
sudo lsof -i :9050
sudo lsof -i :9051

# Kill existing Tor processes
pkill -f tor

# Try with verbose logging
iprotator -v

Connection timeout

# Enable bridges in config.yaml
tor:
  use_bridges: true

bridges:
  - "obfs4 ..."

IP not changing

• Wait for circuit build (can take 30+ seconds)
• Check bootstrap progress in logs
• Try manual rotation with N key

Debug Mode

# Enable debug logging
iprotator -v

# Check logs
tail -f iprotator.log

Getting Help

• GitLab Issues
• Documentation

---

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Merge Request

Development Setup

# Clone repository
git clone https://gitlab.com/Nixort/IPRotator.git
cd IPRotator

# Install development dependencies
pip install -e ".[dev]"

# Run tests
make test

# Run linters
make lint

# Format code
make format

Code Standards

• Follow PEP 8 style guide
• Use type hints
• Write tests for new features
• Update documentation

---

📊 Project Statistics

---

🗺️ Roadmap

• macOS system proxy support
• Web UI for remote management
• REST API for programmatic control
• Multiple Tor instance support
• Load balancing across exit nodes
• Traffic statistics dashboard
• Plugin system

---

🗑️ Uninstallation

Remove IPRotator Package

# Uninstall the package
pip uninstall iprotator -y

Remove Configuration and Data Files

Windows

# Remove data directory
rmdir /s /q %USERPROFILE%\.iprotator
rmdir /s /q %USERPROFILE%\.config\iprotator

# Remove logs
del iprotator.log
del torrc

# Remove local config
del config.yaml

Linux/macOS

# Remove data directory
rm -rf ~/.iprotator
rm -rf ~/.config/iprotator

# Remove logs
rm -f iprotator.log
rm -f torrc

# Remove local config
rm -f config.yaml

Complete Cleanup (All Platforms)

# Stop any running iprotator processes first
# Windows:
taskkill /f /im python.exe 2>nul

# Linux/macOS:
pkill -f iprotator

# Then remove everything
pip uninstall iprotator -y
rm -rf ~/.iprotator ~/.config/iprotator
rm -f iprotator.log torrc config.yaml

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Tor Project — For the amazing anonymity network
• Rich — For beautiful terminal UI
• PySocks — For SOCKS proxy support

---

Made with ❤️ by Nixort

⭐ Star us on GitLab — it helps!