SiteProxy/README.md

# 🔒 Secure Site Proxy

A secure, self-hosted web proxy with authentication, rate limiting, and caching capabilities.

## ✨ Features

- 🔐 **Secure Authentication** - Username/password protection with session management
- 🚦 **Rate Limiting** - Prevent abuse with configurable request limits
- 💾 **Memory Caching** - Intelligent caching for improved performance
- 🛡️ **SSRF Protection** - Comprehensive blocking of private networks and internal services
- 🔄 **Content Rewriting** - Automatic URL rewriting for seamless proxied browsing
- ⏱️ **Session Management** - Secure session handling with automatic expiration
- 🐳 **Docker Support** - Easy deployment with Docker and Docker Compose
- 📊 **Statistics API** - Monitor cache usage and performance

## 🚀 Quick Start

### Prerequisites

- Docker and Docker Compose (recommended)
- OR Go 1.21+ for manual build

### Option 1: Docker Compose (Recommended)

```bash
# 1. Clone the repository
git clone https://github.com/xofine/siteproxy.git
cd siteproxy

# 2. Create and configure environment file
cp .env.example .env
nano .env  # Edit AUTH_PASSWORD and SESSION_SECRET

# 3. Deploy
docker-compose up -d

# 4. Check logs
docker-compose logs -f

# 5. Access the service
# Open http://localhost:8080 in your browser
```

### Option 2: Manual Build

```bash
# 1. Clone and configure
git clone https://github.com/xofine/siteproxy.git
cd siteproxy
cp .env.example .env
nano .env

# 2. Build
go mod init siteproxy
go build -o siteproxy .

# 3. Run
./siteproxy

# 4. Access
# Open http://localhost:8080 in your browser
```

## ⚙️ Configuration

All configuration is done through environment variables in the `.env` file.

### Authentication Settings

```env
AUTH_USERNAME=admin                          # Login username
AUTH_PASSWORD=your_secure_password_here      # Login password (CHANGE THIS!)
SESSION_SECRET=random_64_char_string         # Session encryption key
SESSION_TIMEOUT=30m                          # Session expiration time
```

### Security Settings

```env
RATE_LIMIT_REQUESTS=100                      # Max requests per window
RATE_LIMIT_WINDOW=1m                         # Rate limit time window
MAX_RESPONSE_SIZE=52428800                   # Max response size (50MB)
```

### Proxy Settings

```env
ALLOWED_SCHEMES=http,https                   # Allowed URL schemes
USER_AGENT=Mozilla/5.0...                    # User agent for requests
```

### Blacklist Configuration

```env
# Domain blacklist (supports wildcards)
BLOCKED_DOMAINS=localhost,127.0.0.1,0.0.0.0,*.local,internal,metadata.google.internal,169.254.169.254

# CIDR blacklist (private networks)
BLOCKED_CIDRS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16,::1/128,fc00::/7,fe80::/10,100.64.0.0/10
```

### Cache Settings

```env
CACHE_ENABLED=true                           # Enable/disable caching
CACHE_MAX_SIZE=104857600                     # Max cache size (100MB)
CACHE_TTL=1h                                 # Cache entry TTL
```

### Server Settings

```env
PORT=8080                                    # Server port
```

## 🔒 Security Best Practices

### Essential Security Measures

1. **Change Default Credentials**
   ```bash
   # Generate strong password
   openssl rand -base64 32
   ```

2. **Use Strong Session Secret**
   ```bash
   # Generate random session secret
   openssl rand -hex 32
   ```

3. **Deploy Behind HTTPS**
   - Use Nginx, Caddy, or Traefik as reverse proxy
   - Enable SSL/TLS certificates (Let's Encrypt)

4. **Use Cloudflare Access**
   - Add additional authentication layer
   - Protect against DDoS attacks
   - Hide origin server IP

5. **Network Isolation**
   - Deploy in isolated Docker network
   - Use firewall rules to restrict access
   - Disable unnecessary ports

### Example Nginx Configuration

```nginx
server {
    listen 443 ssl http2;
    server_name proxy.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 📊 API Endpoints

### Public Endpoints

- `GET /login` - Login page
- `POST /login` - Submit credentials
- `GET /health` - Health check endpoint

### Protected Endpoints (Require Authentication)

- `GET /` - Main proxy interface
- `GET /proxy?url=<target>` - Proxy request to target URL
- `GET /stats` - Cache statistics (JSON)
- `GET /logout` - Logout and clear session

### Statistics Response Example

```json
{
  "entries": 42,
  "size": 15728640
}
```

## 🏗️ Architecture

```
┌─────────────┐
│   Browser   │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ Cloudflare      │ (Optional)
│ Access          │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  SiteProxy      │
│  ┌───────────┐  │
│  │ Auth      │  │
│  ├───────────┤  │
│  │ Rate      │  │
│  │ Limiter   │  │
│  ├───────────┤  │
│  │ Validator │  │
│  ├───────────┤  │
│  │ Cache     │  │
│  ├───────────┤  │
│  │ Proxy     │  │
│  └───────────┘  │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│ Target Website  │
└─────────────────┘
```

## 🛠️ Development

### Project Structure

```
siteproxy/
├── main.go              # Application entry point
├── auth/
│   ├── middleware.go    # Authentication middleware
│   └── session.go       # Session management
├── proxy/
│   ├── handler.go       # Proxy request handler
│   ├── index.go         # Main page handler
│   └── stats.go         # Statistics handler
├── security/
│   ├── ratelimit.go     # Rate limiting
│   └── validator.go     # URL validation and SSRF protection
├── cache/
│   └── cache.go         # Memory cache implementation
├── config/
│   └── config.go        # Configuration loader
├── static/              # Static files (if any)
├── .env.example         # Example environment variables
├── Dockerfile           # Docker build configuration
├── docker-compose.yml   # Docker Compose configuration
├── go.mod               # Go module definition
└── README.md            # This file
```

### Running Tests

```bash
# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run with race detector
go test -race ./...
```

### Building for Production

```bash
# Build optimized binary
CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -ldflags="-s -w" -o siteproxy .

# Build for different platforms
GOOS=darwin GOARCH=amd64 go build -o siteproxy-darwin-amd64
GOOS=linux GOARCH=amd64 go build -o siteproxy-linux-amd64
GOOS=windows GOARCH=amd64 go build -o siteproxy-windows-amd64.exe
```

## 🐛 Troubleshooting

### Common Issues

**1. "Unauthorized" error after login**
- Check if SESSION_SECRET is set correctly
- Clear browser cookies and try again
- Verify AUTH_USERNAME and AUTH_PASSWORD in .env

**2. "Rate limit exceeded" error**
- Increase RATE_LIMIT_REQUESTS in .env
- Increase RATE_LIMIT_WINDOW for longer time window
- Wait for the rate limit window to reset

**3. "Invalid or blocked URL" error**
- Check if target domain is in BLOCKED_DOMAINS
- Verify target IP is not in private network range
- Ensure URL starts with http:// or https://

**4. Cache not working**
- Verify CACHE_ENABLED=true in .env
- Check CACHE_MAX_SIZE is sufficient
- Review /stats endpoint for cache statistics

**5. Docker container won't start**
- Check if port 8080 is already in use
- Verify .env file exists and is properly formatted
- Check Docker logs: `docker-compose logs`

### Debug Mode

Enable verbose logging:

```bash
# Add to .env
LOG_LEVEL=debug

# Or run with environment variable
LOG_LEVEL=debug ./siteproxy
```

## 📝 Changelog

### v1.0.0 (2024-01-XX)

- Initial release
- Basic proxy functionality
- Authentication system
- Rate limiting
- Memory caching
- SSRF protection
- Docker support

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

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 Pull Request

### Code Style

- Follow standard Go formatting (`gofmt`)
- Add comments for exported functions
- Write tests for new features
- Update documentation as needed

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## ⚠️ Disclaimer

This tool is provided for legitimate use only. Users are responsible for:

- Complying with applicable laws and regulations
- Respecting target website terms of service
- Not using for malicious purposes
- Ensuring proper authorization before proxying content

The authors are not responsible for misuse of this software.

## 🙏 Acknowledgments

- Built with Go standard library
- Inspired by various open-source proxy projects
- Security best practices from OWASP

## 📧 Support

- **Issues**: [GitHub Issues](https://github.com/xofine/siteproxy/issues)
- **Discussions**: [GitHub Discussions](https://github.com/xofine/siteproxy/discussions)
- **Security**: Report security issues to security@yourdomain.com

## 🔗 Links

- [Documentation](https://github.com/xofine/siteproxy/wiki)
- [Changelog](CHANGELOG.md)
- [Contributing Guidelines](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
```