initial commit

2026-08-27 12:00:08 -06:00
parent 46e778812a
commit 1dc9e36fc8
6 changed files with 778 additions and 0 deletions
@@ -1,2 +1,97 @@
 # 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
+
+```powershell
+# Clone and build
+cd smallprox
+go build -o smallprox.exe .
+```
+
+---
+
+## Usage
+
+```powershell
+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
+```powershell
+.\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
+```powershell
+.\smallprox.exe -listen :9443 -backend https://api.example.com -tls-min 1.2 -tls-max 1.3
+```
+
+### 3. Using Custom Certificates
+```powershell
+.\smallprox.exe -backend https://api.example.com -cert server.crt -key server.key
+```
+
+### 4. Plain HTTP Ingress to HTTPS Backend
+```powershell
+.\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:
+
+```powershell
+# 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
+
+```powershell
+go test -v ./...
+```