Metadata-Version: 2.4
Name: nixort-iprotator
Version: 1.0.0
Summary: Advanced IP Rotation Tool via Tor Network
Home-page: https://gitlab.com/Nixort/IPRotator
Author: Nixort
Author-email: Nixort <nixort@example.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/Nixort/IPRotator
Project-URL: Documentation, https://gitlab.com/Nixort/IPRotator/-/blob/main/README.md
Project-URL: Repository, https://gitlab.com/Nixort/IPRotator.git
Project-URL: Issues, https://gitlab.com/Nixort/IPRotator/-/issues
Keywords: tor,proxy,ip-rotation,privacy,anonymity,socks5
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: PySocks>=1.7.1
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: psutil>=5.9.6
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<div align="center">

![IPRotator Logo](https://img.shields.io/badge/IPRotator-1.0.0-blue?style=for-the-badge&logo=tor-project)

# 🌐 IPRotator

**Advanced IP Rotation Tool via Tor Network**

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?logo=python)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-1.0.0-blue)](https://gitlab.com/Nixort/IPRotator)
[![Pipeline](https://img.shields.io/badge/Pipeline-passing-brightgreen)](https://gitlab.com/Nixort/IPRotator/-/pipelines)

[![Windows](https://img.shields.io/badge/Windows-Supported-0078D6?logo=windows)](https://microsoft.com)
[![Linux](https://img.shields.io/badge/Linux-Supported-FCC624?logo=linux)](https://kernel.org)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker)](https://docker.com)

</div>

---

## 📋 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [Proxy Scanning](#-proxy-scanning)
- [Docker](#-docker)
- [API Reference](#-api-reference)
- [Security](#-security)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [Uninstallation](#️-uninstallation)
- [License](#-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)

```bash
pip install iprotator
```

### From Source

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

### Development Installation

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

### Using Docker

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

---

## 🚀 Quick Start

### 1. Start IPRotator

```bash
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

```yaml
# 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/](https://bridges.torproject.org/)

---

## 🎮 Usage

### Command Line Options

```bash
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

```bash
# 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

```python
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

```bash
# 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

```python
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

```bash
# 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

```yaml
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

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

---

## 📚 API Reference

### IPRotator Class

```python
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

```python
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

```python
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

```bash
# 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

```bash
# 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

```bash
# Enable debug logging
iprotator -v

# Check logs
tail -f iprotator.log
```

### Getting Help

- [GitLab Issues](https://gitlab.com/Nixort/IPRotator/-/issues)
- [Documentation](https://nixort.gitlab.io/iprotator)

---

## 🤝 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

```bash
# 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

[![Pipeline Status](https://gitlab.com/Nixort/IPRotator/badges/main/pipeline.svg)](https://gitlab.com/Nixort/IPRotator/-/pipelines)
[![Coverage Report](https://gitlab.com/Nixort/IPRotator/badges/main/coverage.svg)](https://gitlab.com/Nixort/IPRotator/-/jobs)

---

## 🗺️ 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

```bash
# Uninstall the package
pip uninstall iprotator -y
```

### Remove Configuration and Data Files

#### Windows

```powershell
# 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

```bash
# 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)

```bash
# 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](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [Tor Project](https://www.torproject.org/) — For the amazing anonymity network
- [Rich](https://github.com/Textualize/rich) — For beautiful terminal UI
- [PySocks](https://github.com/Anorov/PySocks) — For SOCKS proxy support

---

<div align="center">

**Made with ❤️ by [Nixort](https://gitlab.com/Nixort)**

⭐ Star us on GitLab — it helps!

</div>
