RustFS Trusted Proxies

The rustfs-trusted-proxies module provides secure and efficient management of trusted proxy servers within the RustFS ecosystem. It is designed to handle multi-layer proxy architectures, ensuring accurate client IP identification while maintaining a zero-trust security model.

Modes

Simple default: only trusts forwarding headers when the direct peer IP is internal.
Legacy full mode: keeps the original proxy-chain validation, available via legacy_* helpers.

Features

Multi-Layer Proxy Validation: Supports Strict, Lenient, and HopByHop validation modes to accurately identify the real client IP address.
Zero-Trust Security: Verifies every hop in the proxy chain against a configurable list of trusted networks.
Cloud Integration: Automatic discovery of trusted IP ranges for major cloud providers including AWS, Azure, and GCP.
High Performance: Utilizes the moka cache for fast lookup of validation results and axum for a high-performance web interface.
Observability: Built-in support for Prometheus metrics and structured JSON logging via tracing.
RFC 7239 Support: Full support for the modern Forwarded header alongside legacy X-Forwarded-For headers.

Configuration

The module is configured primarily through environment variables:

Variable	Default	Description
`RUSTFS_TRUSTED_PROXY_ENABLED`	`true`	Enable the trusted proxy middleware
`RUSTFS_TRUSTED_PROXY_IMPLEMENTATION`	`simple`	Select `simple` or `legacy` implementation
`RUSTFS_TRUSTED_PROXY_VALIDATION_MODE`	`hop_by_hop`	Validation strategy (`strict`, `lenient`, `hop_by_hop`)
`RUSTFS_TRUSTED_PROXY_NETWORKS`	`127.0.0.1,::1,...`	Comma-separated list of trusted CIDR ranges
`RUSTFS_TRUSTED_PROXY_MAX_HOPS`	`10`	Maximum allowed proxy hops
`RUSTFS_TRUSTED_PROXY_CACHE_CAPACITY`	`10000`	Max entries in the validation cache
`RUSTFS_TRUSTED_PROXY_METRICS_ENABLED`	`true`	Enable Prometheus metrics collection
`RUSTFS_TRUSTED_PROXY_CLOUD_METADATA_ENABLED`	`false`	Enable auto-discovery of cloud IP ranges

Usage

Initialization

Initialize the global trusted proxy system at the start of your application (e.g., in main.rs):

rust

// Initialize trusted proxies system
rustfs_trusted_proxies::init();

As a Middleware

Integrate the trusted proxy validation into your Axum application or HTTP service stack:

rust

use rustfs_trusted_proxies;

let app = Router::new()
    .route("/", get(handler))
    // Add the trusted proxy layer if enabled
    .option_layer(if rustfs_trusted_proxies::is_enabled() {
        Some(rustfs_trusted_proxies::layer().clone())
    } else {
        None
    });

Simple default mode

The default mode only trusts forwarding headers from internal IPs.

bash

RUSTFS_TRUSTED_PROXY_IMPLEMENTATION=simple

Legacy mode

The original implementation is still available:

rust

rustfs_trusted_proxies::legacy_init();
let layer = rustfs_trusted_proxies::LegacyTrustedProxyLayer::enabled(config, None);

Or switch the global default path:

bash

RUSTFS_TRUSTED_PROXY_IMPLEMENTATION=legacy

Accessing Client Info

Retrieve the verified client information in your handlers or other middleware:

rust

use rustfs_trusted_proxies::ClientInfo;

async fn handler(req: Request) -> impl IntoResponse {
    if let Some(client_info) = req.extensions().get::<ClientInfo>() {
        println!("Real Client IP: {}", client_info.real_ip);
        println!("Is Trusted: {}", client_info.is_from_trusted_proxy);
    }
}

Development

Pre-Commit Checklist

Before committing, ensure all checks pass:

bash

make pre-commit

Testing

Run the test suite:

bash

cargo test --workspace --exclude e2e_test

License

Licensed under the Apache License, Version 2.0.