Overview

Huginn Proxy is a reverse proxy built on Tokio, Hyper, and Rustls. It routes incoming connections to backend services while passively extracting TLS (JA4), HTTP/2 (Akamai), and TCP SYN (p0f-style) fingerprints and injecting them as headers. TCP SYN fingerprinting is implemented via an XDP eBPF program using Aya. Fingerprinting libraries are provided by Huginn Net.

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

Quick Start

See examples/.

Features

• Configuration - One file, TOML or YAML (picked from the extension). Dynamic sections ( routes, backends, pools, headers, security filters, rate limits, …) hot-reload on SIGHUP or --watch; static sections (listen, TLS, fingerprint flags, logging, telemetry, timeouts, …) need a restart (reload ignores them). See DEPLOYMENT.md.
• IPv4 & IPv6 Dual-Stack - Listen on both address families simultaneously with per-family eBPF maps
• HTTP/1.x & HTTP/2 - Full support for both protocol versions
• Load Balancing - Round-robin load balancing across multiple backends
• Connection Pooling - Automatic connection reuse to backends for reduced latency (bypasses pooling per-route for fingerprinting)
• Path-based Routing - Route matching with prefix support, path stripping, and path rewriting
• Backend health checks - Optional TCP or HTTP GET probes with 502 fast-fail when an upstream is unhealthy
• Rate Limiting - Token bucket algorithm with multiple strategies (IP, Header, Route, Combined), global and per-route limits
• Header Manipulation - Add or remove request/response headers globally or per-route for security and customization
• 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), HTTP/2 (Akamai), and TCP SYN (p0f-style via eBPF) fingerprint extraction
• X-Forwarded- Headers* - Automatic injection of proxy forwarding headers
• Comprehensive Telemetry - Prometheus metrics covering requests, throughput, rate limiting, TLS, backends, and security features
• High Performance - Built on Tokio and Hyper
• Easy Deployment - Single binary, Docker-ready

See FEATURES.md for detailed descriptions and limitations of each feature. See SETTINGS.md for the full configuration reference (TOML and YAML).

For deployment instructions, see DEPLOYMENT.md.

Fingerprinting

Fingerprints are automatically extracted and injected as headers:

• TLS (JA4): x-huginn-net-ja4: sorted cipher suites and extensions, SHA-256 hashed. Standard FoxIO JA4. using huginn-net-tls
• TLS (JA4_r): x-huginn-net-ja4_r: original ClientHello order, SHA-256 hashed (FoxIO JA4_r)
• TLS (JA4_o): x-huginn-net-ja4_o: sorted, raw hex values without hashing (FoxIO JA4_o, useful for debugging)
• TLS (JA4_or): x-huginn-net-ja4_or: original order, raw hex values without hashing (FoxIO JA4_or)
• TLS (JA4_s_v1): x-huginn-net-ja4_s_v1: sorted cipher suites and extensions, SHA-256 hashed — version-stable variant that excludes browser-version-specific fields for a fingerprint consistent across minor browser updates
• TLS (JA4_sr_v1): x-huginn-net-ja4_sr_v1: original ClientHello order, SHA-256 hashed — same stability guarantee as JA4_s_v1 but preserving the raw extension ordering
• HTTP/2 (Akamai): x-huginn-net-akamai: Extracted from HTTP/2 connections only using huginn-net-http
• TCP SYN (p0f-style): x-huginn-net-tcp - Raw TCP SYN signature extracted via eBPF/XDP using huginn-net-tcp. Requires tcp_enabled = true and the ebpf-tcp feature. Present on all requests of a connection (the fingerprint is captured once at TCP accept time and reused). IPv4 and IPv6 SYNs are captured when the next header after the fixed IPv6 header is TCP (see FEATURES.md). See EBPF-SETUP.md for setup, kernel requirements, and deployment options.
• The proxy automatically injects standard X-Forwarded-* headers to inform backends about the original client request:

Examples:

# TLS — standard (FoxIO JA4)
x-huginn-net-ja4:      t13d3112h2_e8f1e7e78f70_b26ce05bbdd6
x-huginn-net-ja4_r:    t13d3112h2_002f,0033,...,ccaa_000a,..._0403,...
x-huginn-net-ja4_o:    t13d3112h2_d7c3e2abb617_cad92ccb4254
x-huginn-net-ja4_or:   t13d3112h2_1302,1303,..._0000,..._0403,...

# TLS — stable (version-invariant)
x-huginn-net-ja4_s_v1:  t13d3111h2_e8f1e7e78f70_375ca2c5e164
x-huginn-net-ja4_sr_v1: t13d3111h2_002f,0033,...,ccaa_000a,..._0403,...

# HTTP/2 (Akamai)
x-huginn-net-akamai:   3:100;4:10485760;2:0|1048510465|0|m,s,a,p

# TCP SYN (eBPF/XDP)
x-huginn-net-tcp:      4:64+0:0:1460:mss*44,7:mss,sok,ts,nop,ws:df,id+:0

# Forwarded
x-forwarded-for:       172.18.0.1
x-forwarded-host:      localhost
x-forwarded-port:      50908
x-forwarded-proto:     https

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

Performance

Benchmarked under realistic conditions — TLS termination, JA4 + Akamai + TCP SYN fingerprinting all enabled — huginn-proxy sustains ~25k req/s (HTTP/1.1) and ~11k req/s (HTTP/2) at c=512 on a single instance, with fingerprinting overhead of ~10–17 µs per request. Most proxy benchmarks you'll find online run plain HTTP without TLS or fingerprinting; this is measured with the full production feature set active.

See benches/README.md for full methodology, numbers, and how to reproduce them.

Deployment matrix

Published images (linux/amd64, linux/arm64), release binaries, and capabilities: * *DEPLOYMENT-MATRIX.md**. See also DEPLOYMENT.md and EBPF-SETUP.md; local Compose under examples/.

Architecture

For module structure and design decisions, see ARCHITECTURE.md.

Fingerprint	Header	eBPF agent required
TLS (JA4)	x-huginn-net-ja4	No
HTTP/2 (Akamai)	x-huginn-net-akamai	No
TCP SYN (p0f)	x-huginn-net-tcp	Yes - Linux only, kernel ≥ 5.11

GHCR: three container packages ( huginn-proxy, huginn-proxy-plain, huginn-proxy-ebpf-agent). How many you run depends on the setup:

• Proxy + eBPF agent (TCP SYN): huginn-proxy + huginn-proxy-ebpf-agent two containers; JA4, Akamai, and x-huginn-net-tcp.
• Proxy only (no TCP SYN): huginn-proxy-plain one container; JA4 and Akamai, no kernel SYN path.

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
• p0f v3: TCP SYN fingerprinting follows the p0f v3 specification by Michal Zalewski

Contributing

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