Transparent Proxy Server

A Transparent HTTP/HTTPS proxy server with authentication, content filtering, caching, and rate limiting capabilities.

About

Transparent Proxy Server is a high-performance, production-ready HTTP/HTTPS proxy solution built with Java. It provides enterprise-grade features including authentication, content filtering, response caching, and rate limiting - all wrapped in an intuitive JavaFX-based management interface.

Perfect for:

• Corporate networks requiring content filtering
• Development environments needing request inspection
• Educational institutions managing internet access
• Security-conscious organizations monitoring web traffic

The proxy supports both HTTP and HTTPS protocols, with full CONNECT method tunneling for secure connections. It's designed to be lightweight, easy to deploy, and highly configurable to meet your specific requirements.

Key Highlights:

• 🚀 Built with Java 17 (LTS) for long-term support
• 🎨 Modern JavaFX GUI for easy management
• 🐳 Docker-ready for containerized deployments
• 📦 Simple Maven-based build process
• 🔧 Highly configurable via properties file

Features

• 🔐 Token-based Authentication - Secure client authentication with configurable filtering
• 🚫 Content Filtering - Block access to specific hosts based on client authentication
• ⚡ Caching - HTTP response caching with Last-Modified header validation
• 🛡️ Rate Limiting - Per-IP rate limiting to prevent abuse
• 🔒 HTTPS Support - Full HTTPS tunneling via CONNECT method
• 📊 Client Management - Track and log client requests
• 🖥️ Professional GUI - JavaFX-based management interface
• 📝 Comprehensive Logging - Structured logging with SLF4J and Logback
• 🐳 Docker Support - Containerized deployment ready

Table of Contents

• About
• Features
• Quick Start
• Installation
• Configuration
• Usage
• Testing Host Blocking
• Architecture
• API Reference
• Docker Deployment
• Contributing
• Troubleshooting
• Support

Quick Start

Prerequisites

• ☕ Java 17 (LTS) - Download JDK 17
• 📦 Maven 3.6+

5-Minute Setup

# 1. Clone the repository
git clone https://github.com/ErselSeyit/Transparent_Proxy.git
cd Transparent_Proxy

# 2. Build the project
mvn clean package

# 3. Run with GUI
mvn javafx:run

In the GUI:

1. Click "File" → "Start Proxy"
2. Configure your browser to use proxy localhost:8080
3. Navigate to any website
4. Login with token: 8a21bce200 (no filtering) or 51e2cba401 (with filtering)

Installation

Option 1: Build from Source (Recommended)

# Clone the repository
git clone https://github.com/ErselSeyit/Transparent_Proxy.git
cd Transparent_Proxy

# Build with Maven
mvn clean package

# The executable JAR will be in target/transparent-proxy-1.0.0.jar

Option 2: Using Docker

# Build and run
docker-compose up

# The proxy will be available at localhost:8080

Configuration

Edit src/main/resources/config.properties to customize the proxy settings:

# Server Configuration
port=8080                    # Proxy listening port
httpPort=80                  # Target HTTP port
httpsPort=443               # Target HTTPS port

# Performance
threadPoolSize=50           # Number of worker threads

# Security
rateLimitPerMinute=100      # Max requests per IP per minute

Restart the proxy after making changes.

Usage

Running with GUI (Recommended)

# Using Maven
mvn javafx:run

# OR using the JAR directly
java -jar target/transparent-proxy-1.0.0.jar

What happens:

• A JavaFX window opens
• Click "File" → "Start Proxy"
• Proxy starts on port 8080
• You'll see logs in the window

Running Headless (Command Line)

java -cp target/transparent-proxy-1.0.0.jar com.proxy.transparent.ProxyServer

What happens:

• Proxy starts in terminal
• No GUI window
• Logs appear in console
• Press Ctrl+C to stop

Configuring Your Browser

Chrome/Edge

1. Settings → System → Open your computer's proxy settings
2. Under "Manual proxy setup":
   • Turn ON "Use a proxy server"
   • Address: 127.0.0.1 or localhost
   • Port: 8080
   • Click "Save"

Firefox

1. Settings → General
2. Scroll to "Network Settings"
3. Click "Settings..."
4. Select "Manual proxy configuration"
5. HTTP Proxy: 127.0.0.1
6. Port: 8080
7. Check "Use this proxy server for all protocols"
8. Click OK

Authentication Tokens

Default tokens (configure in AuthenticationService.java):

• 8a21bce200 - Access without content filtering
• 51e2cba401 - Access with content filtering enabled

⚠️ Important: These are demonstration tokens. In production, use secure token storage.

Testing Host Blocking

⚠️ Common Mistake

DON'T: Open http://localhost:8080 in your browser
DO: Configure your browser to USE the proxy, then navigate to external sites

Step-by-Step Guide

1. Start the Proxy

   mvn javafx:run

   • Click "File" → "Start Proxy"
   • You should see "✓ Proxy server started successfully"

2. Add Host to Block List

   • In GUI: "Filter" → "Add Host to Block List"
   • Enter: www.youtube.com
   • Click OK
   • You should see it in the "Blocked Hosts" list on the right

3. Configure Browser Proxy Settings

   • Follow the browser configuration steps above

4. Login to Proxy

   • Open a NEW browser tab/window
   • Navigate to ANY external website (e.g., http://www.google.com)
   • ⚠️ NOT localhost:8080 - that's the proxy itself!
   • You'll see the login page
   • Enter token: 51e2cba401 (this enables filtering)
   • Click "Login"

5. Test Blocking

   • Navigate to http://www.youtube.com
   • You should see: "403 Forbidden - Access to this host is forbidden"
   • Try a non-blocked site like http://www.google.com - should work normally

What You Should See in Logs

When you access youtube.com through the proxy, you should see:

Request from 0:0:0:0:0:0:0:1: GET http://www.youtube.com/ HTTP/1.1
Processing request to host: www.youtube.com (blocked: true, client filter: true)
Blocked request to filtered host: www.youtube.com from 0:0:0:0:0:0:0:1

Troubleshooting Blocking

"I still see the login page"

• You're accessing localhost:8080 directly
• Fix: Configure browser proxy settings, then navigate to external sites

"It's not blocking"

• Check logs for: Processing request to host: www.youtube.com
• If you don't see this, you're not accessing through the proxy
• Verify browser proxy settings are enabled
• Make sure you logged in with token 51e2cba401 (not 8a21bce200)

"Blocked: false in logs"

• Check if host is in block list (case-insensitive)
• Check if client has filtering enabled (token 51e2cba401)

Architecture

The project follows a clean, modular architecture:

src/main/java/com/proxy/transparent/
├── config/              # Configuration management
│   └── ProxyConfiguration.java
├── handler/             # Request handlers (HTTP/HTTPS)
│   ├── HttpRequestHandler.java
│   ├── HttpsRequestHandler.java
│   └── RequestHandler.java
├── model/               # Data models
│   ├── CachedResponse.java
│   ├── ClientInfo.java
│   └── HttpResponse.java
├── service/             # Business logic services
│   ├── AuthenticationService.java
│   ├── CacheService.java
│   ├── ClientManager.java
│   ├── FilterService.java
│   └── RateLimitService.java
├── ui/                  # JavaFX GUI
│   └── ProxyApplication.java
├── util/                # Utility classes
│   └── HttpUtils.java
└── ProxyServer.java     # Main server class

Request Flow

HTTP Request:

1. Client connects to ProxyServer
2. RequestHandler validates authentication and rate limit
3. HttpRequestHandler checks if host is filtered
4. Checks cache for response
5. Forwards to origin server if needed
6. Caches response and returns to client

HTTPS Request:

1. Client sends CONNECT request
2. RequestHandler validates authentication
3. HttpsRequestHandler checks if host is filtered
4. Sends 200 Connection Established
5. Creates TCP tunnel and forwards data bidirectionally

API Reference

ProxyServer Methods

// Create and start proxy
ProxyServer server = new ProxyServer();
server.start();

// Stop proxy
server.stop();

// Check if running
boolean running = server.isRunning();

// Access services
FilterService filterService = server.getFilterService();
ClientManager clientManager = server.getClientManager();

FilterService

// Block a host
filterService.addBlockedHost("example.com");

// Unblock a host
filterService.removeBlockedHost("example.com");

// Check if blocked
boolean blocked = filterService.isBlocked("example.com");

// Get all blocked hosts
List<String> blockedHosts = filterService.getBlockedHosts();

ClientManager

// Register a client
clientManager.registerClient("192.168.1.100", true);

// Generate report
clientManager.generateClientReport("192.168.1.100");

// Get client info
ClientInfo client = clientManager.getClient("192.168.1.100");

GUI Features

The JavaFX GUI provides:

• Start/Stop Controls - Manage the proxy server
• Filter Management - Add/remove blocked hosts
• Client Monitoring - View connected clients and their status
• Statistics Dashboard - Server metrics and performance
• Report Generation - Export client request logs
• Real-time Logs - View proxy activity in real-time

Docker Deployment

The project includes Docker configuration for easy deployment:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f proxy

# Stop services
docker-compose down

Services

• proxy - Main proxy server (port 8080)
• dns - Optional DNS server with dnsmasq (port 5354) - commented out by default

Logging

Logs are stored in the logs/ directory:

• proxy.log - All application logs (rolling daily)
• error.log - Error-level logs only

Configure logging in src/main/resources/logback.xml.

Testing

# Run all tests
mvn test

# Run with coverage
mvn test jacoco:report

# Run specific test
mvn test -Dtest=FilterServiceTest

Security Considerations

⚠️ Important Security Notes:

1. Authentication Tokens - Default tokens are for demonstration only. In production:

   • Store tokens securely (database, secrets manager)
   • Use strong, randomly generated tokens
   • Implement token expiration
   • Consider OAuth2 or JWT

2. HTTPS - The proxy tunnels HTTPS traffic but doesn't inspect it

3. Rate Limiting - Adjust rateLimitPerMinute based on your needs

4. Logging - Be mindful of logging sensitive information

Performance Tuning

• Thread Pool Size: Adjust based on expected concurrent connections (default: 50)
• Cache: Monitor cache size and implement eviction if needed
• Rate Limiting: Balance security with usability (default: 100 requests/minute)

Troubleshooting

Proxy won't start

# Check if port is already in use
netstat -an | grep 8080  # Linux/Mac
netstat -an | findstr 8080  # Windows

# Try a different port in config.properties
port=8081

Browser can't connect

1. Verify proxy is running (check GUI status or logs)
2. Check firewall settings
3. Ensure correct proxy configuration in browser
4. Check logs in logs/proxy.log

"Login Failed"

• Ensure you're using a valid token
• Default tokens: 8a21bce200 or 51e2cba401
• Check logs for authentication attempts

High memory usage

Reduce thread pool size in config:

threadPoolSize=20

"Cannot find config.properties"

Make sure config.properties is in the same directory as the JAR, or specify path:

java -Dconfig.file=/path/to/config.properties -jar target/transparent-proxy-1.0.0.jar

"JavaFX not found"

Use Maven to run instead:

mvn javafx:run

Contributing

Contributions are welcome! Please follow these guidelines:

Development Setup

1. Prerequisites

   - Java 17 (LTS)
   - Maven 3.6+
   - Git

2. Fork and Clone

   git clone https://github.com/your-username/Transparent_Proxy.git
   cd Transparent_Proxy

3. Build

   mvn clean install

4. Run Tests

   mvn test

Coding Standards

• Use 4 spaces for indentation
• Maximum line length: 120 characters
• Use meaningful variable and method names
• Add JavaDoc for all public methods and classes
• Follow standard Java naming conventions

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Update documentation as needed
6. Submit a pull request with a clear description

Commit Messages

• Use present tense ("Add feature" not "Added feature")
• Use imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit first line to 72 characters
• Reference issues and pull requests

Example:

Add rate limiting service

- Implement per-IP rate limiting
- Add configurable limits
- Include unit tests

Fixes #123

License

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

Acknowledgments

• Built with JavaFX for the GUI
• Logging with SLF4J and Logback
• Build management with Maven

Support

For issues and questions:

• 📧 Email: erselseyit@gmail.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki

Roadmap

• Web-based admin interface
• RESTful API
• Advanced filtering (URL patterns, content inspection)
• Load balancing
• Metrics and monitoring (Prometheus/Grafana)
• Plugin system
• SSL certificate management

---

Made with ❤️ for the Java community