98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# 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 ./...
|
|
```
|