PunkProxy v5

PunkProxy is a modern, high-performance HTTP gateway and reverse proxy with a comprehensive REST API and cluster support. Built in Go, PunkProxy provides enterprise-grade features for routing, security, and traffic management at the edge.

Overview

PunkProxy is designed to serve as a flexible edge proxy solution that sits between your clients and backend services. It provides domain-level routing, automatic SSL/TLS certificate management, advanced security features, and a powerful control plane API for managing your infrastructure.

Key Features

Implemented Features

  • Domain-Level Routing - Route traffic to different backends based on domain names
  • Automatic SSL/TLS Management - Built-in ACME client (Let's Encrypt) for automatic certificate provisioning and renewal
  • Force SSL Redirect - Automatically redirect HTTP traffic to HTTPS
  • JA3 Fingerprinting - Advanced TLS fingerprinting for client identification and security analysis
  • Multi-Protocol Support - Full support for HTTP/3 (QUIC), HTTP/2, and HTTP/1.1
  • Control Plane API - RESTful API for managing zones, destinations, certificates, and settings
  • Cluster Support - Designed for distributed deployments with shared state
  • Prometheus Metrics - Built-in metrics endpoint for monitoring and observability
  • GeoIP Integration - Geographic location detection using MaxMind GeoIP databases
  • Session Management - Distributed session handling with Valkey (Redis-compatible)

Planned Features

  • File caching for improved performance
  • IP and GEO-based blocking
  • Coraza WAF integration for web application firewall capabilities
  • Rate limiting per zone and destination
  • Agent checking and validation
  • Zone-level custom rules
  • Image processing services (resizing, re-encoding)

Architecture

PunkProxy consists of two main components:

  1. Proxy Service (proxy/) - The high-performance edge proxy that handles incoming HTTP/HTTPS traffic

    • Handles TLS termination
    • Routes requests to configured backends
    • Implements security middleware (JA3, IP blocking, rate limiting)
    • Serves metrics and health endpoints

  2. Control Plane (control/) - The management API and certificate authority

    • RESTful API for configuration management
    • ACME certificate management
    • Zone and destination configuration
    • Database-backed configuration storage

Usage

Managing Zones

Zones represent a collection of domains that route to one or more backend destinations. Use the control plane API to:

  • Create zones with domain names
  • Configure SSL certificates (automatic via ACME or manual)
  • Set up backend destinations
  • Enable/disable zones
  • Configure zone-specific settings

API Documentation

The control plane exposes a Swagger/OpenAPI documentation endpoint. Once running, access it at:

http://localhost:8088/swagger/index.html

Metrics

Prometheus metrics are available at:

http://localhost:9191/metrics

Configuration

Environment Variables

Proxy Service:

  • HTTP - Comma-separated list of HTTP ports (default: 9880)
  • HTTPS - Comma-separated list of HTTPS ports (default: 9443)
  • CONTROL_PLANE - Control plane API URL (default: http://control)
  • VALKEY - Valkey/Redis connection string (default: valkey:6379)
  • SESSION_PREFIX - Session key prefix (default: session)

Control Plane:

  • DSN - PostgreSQL connection string
  • ACME_EMAIL - Email for ACME certificate registration
  • ACME_URI - ACME server URI (Let's Encrypt or test server)
  • DEBUG - Enable debug mode

License

This project is licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2).

This license allows:

  • ✅ Internal use
  • ✅ Non-commercial education and research
  • ✅ Professional services for licensees
  • ❌ Commercial products that compete with PunkSky

Future License Grant: After 2 years from the release date, the code will be available under the Apache License 2.0.

Roadmap

Milestone 1 (Completed)

  • [x] Domain level routing
  • [x] ACME client
  • [x] Force SSL redirect
  • [x] JA3 fingerprinting
  • [x] HTTP 3/2/1.1 support

Milestone 2 (In Progress)

  • [ ] File caching
  • [ ] IP and GEO blocking
  • [ ] Coraza WAF integration
  • [ ] Rate limiting

Milestone 3 (Planned)

  • [ ] Agent checking
  • [ ] Zone level rules

Milestone 4 (Planned)

  • [ ] Image services (resizing, re-encoding)

Security

PunkProxy includes several security features:

  • JA3 Fingerprinting - Identify and track clients based on TLS handshake characteristics
  • TLS Termination - Full control over TLS configuration and cipher suites
  • IP Blocking - Block traffic from specific IP addresses or ranges
  • GeoIP Blocking - Block traffic from specific geographic regions
  • WAF Integration - Web Application Firewall support via Coraza (planned)