smallprox/README.md

smallprox

smallprox is a lightweight, zero-dependency reverse proxy written in Go. It accepts incoming client connections over TLS 1.2 (or configurable TLS versions) and forwards requests to backends running modern TLS protocols (such as TLS 1.3) or any SSL/TLS version.

Key Features

• TLS Protocol Bridging: Solves the incompatibility where legacy clients (e.g. PowerShell scripts configured for TLS 1.2) need to access backends requiring TLS 1.3.
• Zero Configuration HTTPS: Generates an in-memory self-signed certificate on startup with localhost and IP Subject Alternative Names (SANs) if no cert/key files are provided.
• Full Backend Trust: Bypasses backend certificate checks (InsecureSkipVerify: true) to work with self-signed, untrusted, or internal certificates.
• Virtual Host & SNI Support: Automatically updates the Host header to match the destination backend (can be disabled with -preserve-host).
• Zero External Dependencies: Built entirely with Go standard library (net/http, crypto/tls, crypto/x509, net/http/httputil).

---

Installation & Building

# Clone and build
cd smallprox
go build -o smallprox.exe .

---

Usage

smallprox -backend <url> [options]

If no backend is provided, usage instructions are automatically printed.

Command-line Options

Flag	Short	Default	Description
-backend	-b	(Required)	Target backend URL (e.g. https://tls13.example.com)
-listen	-l	:8443	Address and port to bind
-tls-min		1.2	Minimum incoming TLS version (1.0, 1.1, 1.2, 1.3)
-tls-max		1.2	Maximum incoming TLS version (1.0, 1.1, 1.2, 1.3)
-cert			Path to custom TLS certificate PEM file (optional)
-key			Path to custom TLS private key PEM file (optional)
-http		false	Listen in plain HTTP mode instead of HTTPS
-preserve-host		false	Preserve incoming Host header instead of target host
-version	-v		Print version and exit
-help	-h		Show help message

---

Examples

1. Basic TLS 1.2 Proxy to TLS 1.3 Backend

.\smallprox.exe -backend https://api.example.com

Listens on https://127.0.0.1:8443 with TLS 1.2 and proxies to https://api.example.com.

2. Custom Port and TLS Range

.\smallprox.exe -listen :9443 -backend https://api.example.com -tls-min 1.2 -tls-max 1.3

3. Using Custom Certificates

.\smallprox.exe -backend https://api.example.com -cert server.crt -key server.key

4. Plain HTTP Ingress to HTTPS Backend

.\smallprox.exe -http -listen :8080 -backend https://api.example.com

---

PowerShell Client Example

To communicate through smallprox from a PowerShell session requiring TLS 1.2 and trusting self-signed certificates:

# Enforce TLS 1.2 in PowerShell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# Trust local self-signed certificate
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

# Make request through proxy
$response = Invoke-RestMethod -Uri "https://localhost:8443/api/v1/resource" -Method Get
Write-Output $response

---

Running Tests

go test -v ./...