Huginn Proxy

High-performance reverse proxy with passive fingerprinting capabilities powered by Huginn Net.

Overview

Huginn Proxy is a reverse proxy built in Rust that combines traditional load balancing and request forwarding with advanced passive fingerprinting capabilities. It leverages the Huginn Net fingerprinting libraries to extract TLS (JA4) and HTTP/2 (Akamai) fingerprints from client connections, injecting them as headers for downstream services.

Inspired by production-grade proxies like Pingora, Sozu, and rust-rpxy.

Note: This project is currently in active development.

Quick Start

Build

cargo build --release

Minimal Configuration

Create config.toml:

listen = "0.0.0.0:7000"

backends = [
  { address = "backend:8080", http_version = "preserve" }
]

routes = [
  { prefix = "/", backend = "backend:8080" }
]

[tls]
cert_path = "/path/to/cert.pem"
key_path = "/path/to/key.pem"
alpn = ["h2", "http/1.1"]

[fingerprint]
tls_enabled = true
http_enabled = true

Installation

From Source

git clone https://github.com/biandratti/huginn-proxy.git
cd huginn-proxy
cargo build --release

Docker

docker build -t huginn-proxy .
docker run -v /path/to/config.toml:/config.toml huginn-proxy /config.toml

Features

• HTTP/1.x & HTTP/2 - Full support for both protocol versions
• Load Balancing - Round-robin load balancing across multiple backends
• Path-based Routing - Route matching with prefix support, path stripping, and path rewriting
• Rate Limiting - Token bucket algorithm with multiple strategies (IP, Header, Route, Combined), global and per-route limits
• Security Headers - HSTS, CSP, X-Frame-Options, and custom headers
• IP Filtering (ACL) - Allowlist/denylist with CIDR notation support
• TLS Termination - Server-side TLS with ALPN, certificate hot reload (single certificate per configuration)
• TLS Session Resumption - Support for TLS 1.2 session IDs and TLS 1.3 session tickets
• mTLS (Mutual TLS) - Client certificate authentication for secure service-to-service communication
• Granular Timeouts - TLS handshake and connection handling timeouts for resource protection
• Host Header Preservation - Configurable forwarding of original Host header for virtual hosting
• Passive Fingerprinting - Automatic TLS (JA4) and HTTP/2 (Akamai) fingerprint extraction
• X-Forwarded- Headers* - Automatic injection of proxy forwarding headers
• High Performance - Built on Tokio and Hyper
• Easy Deployment - Single binary, Docker-ready

See FEATURES.md for detailed descriptions and limitations of each feature.

Fingerprinting

Fingerprints are automatically extracted and injected as headers:

• TLS (JA4): x-huginn-net-ja4 - Extracted from all TLS connections using huginn-net-tls
• HTTP/2 (Akamai): x-huginn-net-akamai - Extracted from HTTP/2 connections only using huginn-net-http

Examples:

x-huginn-net-ja4: t13d1516h2_8afaf4b9491c_00_0403040303030103010302_01
x-huginn-net-akamai: 1:65536,2:0,3:1000,4:6291456,6:262144|15663105|0|m,p,a,s

See JA4 specification and Blackhat EU 2017 for details.

Proxy Headers

The proxy automatically injects standard X-Forwarded-* headers to inform backends about the original client request:

• X-Forwarded-For: Client IP address (appended if already present)
• X-Forwarded-Host: Original Host header value
• X-Forwarded-Port: Client port number
• X-Forwarded-Proto: Protocol used (http or https)

These headers always override any client-provided values to prevent spoofing.

Health Check Endpoints

When telemetry.metrics_port is configured, Huginn Proxy exposes health check endpoints on the observability server (separate from the main proxy port):

• /health - General health check (200 OK if process is running)
• /ready - Readiness check (200 OK if backends configured, 503 otherwise) - for Kubernetes readiness probes
• /live - Liveness check (200 OK if process is running) - for Kubernetes liveness probes
• /metrics - Prometheus metrics endpoint

All endpoints return JSON responses (except /metrics which returns Prometheus format) and follow Kubernetes health check conventions.

Examples

See the examples/ directory for:

• Docker Compose setup with TLS termination
• Rate limiting configurations
• Advanced routing examples

Performance

• Fingerprinting Overhead: ~2.2% (minimal impact)
• Concurrent Connections: Handles thousands of concurrent connections
• Latency: Sub-millisecond overhead for fingerprint extraction

See benches/README.md for detailed benchmark results from development environment.

Roadmap

See ROADMAP.md for a detailed list of planned features and upcoming phases.

Related Projects

• Huginn Net - Multi-protocol passive fingerprinting library
• huginn-net-tls - JA4 TLS fingerprinting
• huginn-net-http - HTTP/2 Akamai fingerprinting

License

Dual-licensed under MIT or Apache 2.0.

Attribution

Huginn Proxy uses the Huginn Net fingerprinting libraries:

• JA4: TLS fingerprinting follows the JA4 specification by FoxIO, LLC
• Akamai HTTP/2: HTTP/2 fingerprinting follows the Blackhat EU 2017 specification

Contributing

Contributions are welcome! Please see our contributing guidelines for details.