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.

Note

PunkProxy is free and open source under the Functional Source License (FSL-1.1-ALv2). Self-host at no cost, or use PunkSky managed hosting with SLAs and support.

Get started:

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

  • 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

  • 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 3 main components:

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), and serves metrics and health endpoints.

Control Plane (control/) The management API and certificate authority. RESTful API for configuration management, ACME certificate management, zone and destination configuration, and database-backed configuration storage.

Legbot (legbot/) A ACME client powered by the Go package Lego.

Quick Start

With Docker and Docker Compose: clone the repo from https://git.punksky.com/punksky/proxy/punkproxy.git/, set ACME_EMAIL, and run docker-compose up -d. Proxy runs on 9880 (HTTP) and 9443 (HTTPS); control plane API on 8088. Swagger at http://localhost:8088/swagger/index.html. For production, use prod-docker-compose.yml.

Pull images from docker.punksky.com for the fastest start.

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:

Variable Description
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:

Variable Description
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 require a Partner Program agreement.

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

Roadmap

Milestone 1 (In progress)

  • Domain level routing
  • ACME client
  • Force SSL redirect
  • JA3 fingerprinting
  • 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)

Repository: git.punksky.com