CycleTLS-Proxy

README

CycleTLS-Proxy

Advanced TLS Fingerprint Proxy Server

A high-performance HTTP proxy that enables TLS fingerprint spoofing to mimic various browsers and clients. Built on top of CycleTLS, this proxy allows you to make HTTP requests while appearing as different browsers with authentic TLS signatures.

Features

• 🔒 TLS Fingerprint Spoofing - Mimic Chrome, Firefox, Safari, Edge, and mobile browsers
• ⚡ High Performance - Built with FastHTTP for exceptional speed and low latency
• 🔄 Session Management - Persistent sessions with automatic connection reuse
• 🎯 Flexible API - Simple HTTP header-based configuration
• 🐳 Docker Ready - Production-ready container with health checks
• 📊 Comprehensive Logging - Detailed request/response logging with structured output
• 🔧 Easy Integration - Works with any HTTP client in any programming language
• 🌐 Proxy Support - Optional upstream proxy configuration
• ⏱️ Configurable Timeouts - Per-request timeout control
• 🏥 Health Monitoring - Built-in health check endpoint

Supported Browser Profiles

Profile ID	Browser	Platform	TLS Version	HTTP Version
chrome	Chrome 120	Linux	1.3	h2
chrome_windows	Chrome 120	Windows	1.3	h2
firefox	Firefox 121	Linux	1.3	h2
firefox_windows	Firefox 121	Windows	1.3	h2
safari	Safari 17	macOS	1.3	h2
safari_ios	Safari 17.1.1	iOS	1.3	h2
edge	Edge 120	Windows	1.3	h2
okhttp	OkHttp 4.12.0	Android	1.3	h2
chrome_legacy_tls12	Chrome 91	Windows	1.2	h2

Quick Start

Installation Options

Option 1: Pre-built Binary (Recommended)

# Download the latest release (replace {VERSION} with actual version, e.g., v1.0.0)
curl -L -o cycletls-proxy https://github.com/Danny-Dasilva/CycleTLS-Proxy/releases/download/{VERSION}/cycletls-proxy-{VERSION}-linux-amd64
chmod +x cycletls-proxy

# Or for other platforms:
# macOS Intel: cycletls-proxy-{VERSION}-darwin-amd64  
# macOS Apple Silicon: cycletls-proxy-{VERSION}-darwin-arm64
# Windows: cycletls-proxy-{VERSION}-windows-amd64.exe

# Run the proxy
./cycletls-proxy

Option 2: Docker

# Pull and run the Docker image
docker run -p 8080:8080 dannydasilva/cycletls-proxy:latest

# Or using docker-compose
docker-compose up -d cycletls-proxy

Option 3: Build from Source

# Clone the repository
git clone https://github.com/Danny-Dasilva/CycleTLS-Proxy.git
cd CycleTLS-Proxy

# Install dependencies (requires local CycleTLS)
go mod download

# Build and run
go build -o cycletls-proxy ./cmd/proxy
./cycletls-proxy

Basic Usage

Once the server is running on http://localhost:8080, you can make requests using any HTTP client:

# Basic GET request with Chrome fingerprint
curl -H "X-URL: https://httpbin.org/json" \
     -H "X-IDENTIFIER: chrome" \
     http://localhost:8080

# POST request with custom headers
curl -X POST \
     -H "X-URL: https://httpbin.org/post" \
     -H "X-IDENTIFIER: firefox" \
     -H "Content-Type: application/json" \
     -d '{"key": "value"}' \
     http://localhost:8080

API Documentation

Headers

All proxy requests are configured using HTTP headers:

Required Headers

• X-URL - Target URL to proxy the request to
  • Example: X-URL: https://api.example.com/data

Optional Headers

• X-IDENTIFIER - Browser profile to use (default: chrome)

  • Example: X-IDENTIFIER: firefox
  • See Supported Browser Profiles for options

• X-SESSION-ID - Session identifier for connection reuse

  • Example: X-SESSION-ID: my-session-123
  • Sessions persist connections and cookies

• X-PROXY - Upstream proxy server (HTTP/SOCKS)

  • Example: X-PROXY: http://proxy.example.com:8080
  • Example: X-PROXY: socks5://127.0.0.1:9050

• X-TIMEOUT - Request timeout in seconds (1-300, default: 30)

  • Example: X-TIMEOUT: 60

• X-TLS13-AUTORETRY - Automatically retry with TLS 1.3 compatible curves (true/false, default: false)

  • Example: X-TLS13-AUTORETRY: true

Standard HTTP Headers

All standard HTTP headers (except X-* headers) are forwarded to the target server:

curl -H "X-URL: https://api.example.com" \
     -H "X-IDENTIFIER: chrome" \
     -H "Authorization: Bearer token123" \
     -H "Content-Type: application/json" \
     -H "Custom-Header: value" \
     http://localhost:8080

Endpoints

GET /health

Returns server health status and statistics:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "dev",
  "proxy": {
    "profiles_available": 9,
    "active_sessions": 5,
    "default_timeout": "30s"
  },
  "system": {
    "uptime": "running"
  }
}

All Other Endpoints

Forward requests to the specified X-URL with TLS fingerprint spoofing.

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	8080
LOG_LEVEL	Logging level (debug, info, warn, error)	info

Example Configuration

export PORT=8080
export LOG_LEVEL=debug
./cycletls-proxy

Usage Examples

cURL Examples

# GET request with different browsers
curl -H "X-URL: https://httpbin.org/user-agent" -H "X-IDENTIFIER: chrome" http://localhost:8080
curl -H "X-URL: https://httpbin.org/user-agent" -H "X-IDENTIFIER: firefox" http://localhost:8080
curl -H "X-URL: https://httpbin.org/user-agent" -H "X-IDENTIFIER: safari_ios" http://localhost:8080

# Session management
curl -H "X-URL: https://httpbin.org/cookies/set/session/abc123" -H "X-SESSION-ID: user1" http://localhost:8080
curl -H "X-URL: https://httpbin.org/cookies" -H "X-SESSION-ID: user1" http://localhost:8080

# Using upstream proxy
curl -H "X-URL: https://httpbin.org/ip" -H "X-PROXY: socks5://127.0.0.1:9050" http://localhost:8080

# POST with JSON
curl -X POST \
     -H "X-URL: https://httpbin.org/post" \
     -H "X-IDENTIFIER: edge" \
     -H "Content-Type: application/json" \
     -d '{"username":"test","password":"secret"}' \
     http://localhost:8080

Python Examples

import requests

# Simple GET request
response = requests.get(
    "http://localhost:8080",
    headers={
        "X-URL": "https://httpbin.org/json",
        "X-IDENTIFIER": "chrome"
    }
)
print(response.json())

# POST with session
session = requests.Session()
session.headers.update({"X-SESSION-ID": "python-session"})

# Login request
login_response = session.post(
    "http://localhost:8080",
    headers={
        "X-URL": "https://httpbin.org/post",
        "X-IDENTIFIER": "firefox",
        "Content-Type": "application/json"
    },
    json={"username": "user", "password": "pass"}
)

# Authenticated request using same session
data_response = session.get(
    "http://localhost:8080",
    headers={
        "X-URL": "https://httpbin.org/get",
        "X-IDENTIFIER": "firefox"
    }
)

Node.js Examples

const axios = require('axios');

// GET request with Chrome fingerprint
async function makeRequest() {
    try {
        const response = await axios.get('http://localhost:8080', {
            headers: {
                'X-URL': 'https://httpbin.org/json',
                'X-IDENTIFIER': 'chrome'
            }
        });
        
        console.log(response.data);
    } catch (error) {
        console.error('Request failed:', error.message);
    }
}

// Session-based requests
const sessionId = 'nodejs-session-' + Math.random().toString(36).substr(2, 9);

async function makeSessionRequest(url, data = null) {
    const headers = {
        'X-URL': url,
        'X-IDENTIFIER': 'firefox',
        'X-SESSION-ID': sessionId
    };
    
    if (data) {
        headers['Content-Type'] = 'application/json';
        return axios.post('http://localhost:8080', data, { headers });
    } else {
        return axios.get('http://localhost:8080', { headers });
    }
}

makeRequest();

Go Examples

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    client := &http.Client{}
    
    // GET request
    req, _ := http.NewRequest("GET", "http://localhost:8080", nil)
    req.Header.Set("X-URL", "https://httpbin.org/json")
    req.Header.Set("X-IDENTIFIER", "chrome")
    
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
    
    // POST request with JSON
    payload := map[string]string{"key": "value"}
    jsonData, _ := json.Marshal(payload)
    
    req, _ = http.NewRequest("POST", "http://localhost:8080", bytes.NewBuffer(jsonData))
    req.Header.Set("X-URL", "https://httpbin.org/post")
    req.Header.Set("X-IDENTIFIER", "safari")
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-SESSION-ID", "go-session")
    
    resp, err = client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ = io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Docker Deployment

Basic Deployment

version: '3.8'

services:
  cycletls-proxy:
    image: dannydasilva/cycletls-proxy:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Production Deployment with Nginx

version: '3.8'

services:
  cycletls-proxy:
    image: dannydasilva/cycletls-proxy:latest
    expose:
      - "8080"
    environment:
      - PORT=8080
      - LOG_LEVEL=info
    restart: unless-stopped
    
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - cycletls-proxy
    restart: unless-stopped

Scaling with Docker Swarm

# Deploy as a service
docker service create \
  --name cycletls-proxy \
  --replicas 3 \
  --publish published=8080,target=8080 \
  --env PORT=8080 \
  dannydasilva/cycletls-proxy:latest

# Scale the service
docker service scale cycletls-proxy=5

Monitoring & Observability

Health Checks

# Check server health
curl http://localhost:8080/health

# Monitor with script
while true; do
  curl -s http://localhost:8080/health | jq '.proxy.active_sessions'
  sleep 5
done

Logging

The server provides structured JSON logs:

{
  "level": "info",
  "time": "2024-01-15T10:30:00Z",
  "message": "Processing proxy request",
  "method": "GET",
  "target_url": "https://api.example.com/data",
  "identifier": "chrome",
  "session_id": "session123",
  "timeout": "30s"
}

Metrics Collection

For production monitoring, consider integrating with:

• Prometheus - Metrics collection and alerting
• Grafana - Visualization dashboards
• ELK Stack - Log aggregation and analysis

Security Considerations

Network Security

• Deploy behind a reverse proxy (Nginx, Traefik)
• Use HTTPS termination at the proxy level
• Implement rate limiting to prevent abuse
• Consider IP whitelisting for sensitive deployments

Access Control

# Example Nginx configuration for access control
location /proxy/ {
    proxy_pass http://cycletls-proxy:8080/;
    
    # Rate limiting
    limit_req zone=api burst=10 nodelay;
    
    # IP whitelisting
    allow 10.0.0.0/8;
    deny all;
    
    # Header validation
    if ($http_x_url = "") {
        return 400;
    }
}

Best Practices

1. Run as non-root user (default in Docker)
2. Use resource limits to prevent DoS
3. Monitor for unusual patterns in logs
4. Regularly update to latest version
5. Validate input at application level

Troubleshooting

Common Issues

Connection Errors

# Test connectivity
curl -v http://localhost:8080/health

# Check if target URL is reachable
curl -H "X-URL: https://httpbin.org/get" -H "X-IDENTIFIER: chrome" -v http://localhost:8080

SSL/TLS Issues

# Test with different profiles
curl -H "X-URL: https://badssl.com/" -H "X-IDENTIFIER: chrome_legacy_tls12" http://localhost:8080

Performance Issues

# Check active sessions
curl -s http://localhost:8080/health | jq '.proxy.active_sessions'

# Monitor resource usage
docker stats cycletls-proxy

Debug Mode

# Run with debug logging
LOG_LEVEL=debug ./cycletls-proxy

# Or with Docker
docker run -e LOG_LEVEL=debug -p 8080:8080 dannydasilva/cycletls-proxy

Getting Help

1. Check the issues page
2. Review the CycleTLS documentation
3. Enable debug logging and examine output
4. Provide minimal reproduction example when reporting bugs

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/Danny-Dasilva/CycleTLS-Proxy.git
cd CycleTLS-Proxy

# Install dependencies
go mod download

# Run tests
go test ./...

# Build and run
go build -o cycletls-proxy ./cmd/proxy
./cycletls-proxy

Acknowledgments

• Built on top of CycleTLS
• Thanks to the Go community for excellent networking libraries

Support

If you find this project useful, consider:

• Starring the repository
• Reporting bugs and feature requests
• Contributing code or documentation
• Sharing with others who might benefit

---