xff: add support for configuring a list of trusted CIDRs

api/envoy/extensions/http/original_ip_detection/xff/v3/BUILD

@@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
 licenses(["notice"])  # Apache 2
 
 api_proto_package(
-    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+    deps = [
+        "//envoy/config/core/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+    ],
 )

api/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto

@@ -2,6 +2,10 @@ syntax = "proto3";
 
 package envoy.extensions.http.original_ip_detection.xff.v3;
 
+import "envoy/config/core/v3/address.proto";
+
+import "google/protobuf/wrappers.proto";
+
 import "udpa/annotations/status.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.http.original_ip_detection.xff.v3";
@@ -22,5 +26,49 @@ message XffConfig {
   // determining the origin client's IP address. The default is zero if this option
   // is not specified. See the documentation for
   // :ref:`config_http_conn_man_headers_x-forwarded-for` for more information.
+  //
+  // Only one of ``xff_num_trusted_hops`` and ``xff_trusted_cidrs`` should be set.
+  // If ``xff_trusted_cidrs`` is set, this field is ignored.
   uint32 xff_num_trusted_hops = 1;
+
+  // The `CIDR <https://tools.ietf.org/html/rfc4632>`_ ranges to trust when
+  // evaluating the remote IP address to determine the original client's IP address.
+  // This is used instead of
+  // :ref:`use_remote_address <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`.
+  // When the remote IP address matches a trusted CIDR and the
+  // :ref:`config_http_conn_man_headers_x-forwarded-for` header was sent, each entry
+  // in the ``x-forwarded-for`` header is evaluated from right to left and the first
+  // public non-trusted address is used as the original client address. If all
+  // addresses in ``x-forwarded-for`` are within the trusted list, the first (leftmost)
+  // entry is used.
+  //
+  // This is typically used when requests are proxied by a
+  // `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_.
+  //
+  // Only one of ``xff_num_trusted_hops`` and ``xff_trusted_cidrs`` should be set.
+  // If set, takes precedence over ``xff_num_trusted_hops``.
+  XffTrustedCidrs xff_trusted_cidrs = 2;
+
+  // If set, Envoy will not append the remote address to the
+  // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header.
+  //
+  // .. attention::
+  //
+  //   For proper proxy behaviour it is not recommended to set this option.
+  //   For backwards compatibility, if this option is unset and
+  //   ``xff_num_trusted_hops`` is set, it defaults to true. When
+  //   ``xff_trusted_cidrs`` is set, it defaults to false.
+  //
+  // This only applies when :ref:`use_remote_address
+  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`
+  // is false, otherwise :ref:`skip_xff_append
+  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.skip_xff_append>`
+  // applies.
+  google.protobuf.BoolValue skip_xff_append = 3;
+}
+
+message XffTrustedCidrs {
+  // The list of `CIDRs <https://tools.ietf.org/html/rfc4632>`_ from which remote
+  // connections are considered trusted.
+  repeated config.core.v3.CidrRange cidrs = 1;
 }

changelogs/current.yaml

@@ -179,5 +179,9 @@ new_features:
   change: |
     Added :ref:`delay_deny <envoy_v3_api_msg_extensions.filters.network.rbac.v3.RBAC>` to support deny connection after
     the configured duration.
+- area: original_ip_detection extension
+  change: |
+    The :ref:`xff <envoy_v3_api_msg_extensions.http.original_ip_detection.xff.v3.XffConfig>`
+    original IP detection method now supports using a list of trusted CIDRs when parsing ``x-forwarded-for``.
 
 deprecated:

docs/root/configuration/http/http_conn_man/headers.rst

@@ -265,6 +265,18 @@ additional addresses from XFF:
   the XFF contains fewer than N addresses, Envoy falls back to using the immediate downstream
   connection's source address as trusted client address.)
 
+.. note::
+
+ If the trusted client address should be determined from a list of known CIDRs, use the
+ :ref:`xff <envoy_v3_api_msg_extensions.http.original_ip_detection.xff.v3.XffConfig>` original IP
+ detection option instead.
+
+ * If the remote address is contained by an entry in ``xff_trusted_cidrs``, and the *last*
+   (rightmost) entry is also contained by an entry in ``xff_trusted_cidrs``, the trusted client
+   address is *second-last* IP address in XFF.
+ * If all entries in XFF are contained by an entry in ``xff_trusted_cidrs``, the trusted client
+   address is the *first* (leftmost) IP address in XFF.
+
 Envoy uses the trusted client address contents to determine whether a request originated
 externally or internally. This influences whether the
 :ref:`config_http_conn_man_headers_x-envoy-internal` header is set.
@@ -355,6 +367,36 @@ Example 6: The internal Envoy from Example 5, receiving a request proxied by ano
       | X-Envoy-External-Address remains unset
       | X-Envoy-Internal is set to "true"
 
+Example 7: Envoy as edge proxy, with one trusted CIDR
+    Settings:
+      | use_remote_address = false
+      | xff_trusted_cidrs = 192.0.2.0/24
+
+    Request details:
+      | Downstream IP address = 192.0.2.5
+      | XFF = "203.0.113.128, 203.0.113.10, 192.0.2.1"
+
+    Result:
+      | Trusted client address = 192.0.2.1
+      | X-Envoy-External-Address is set to 192.0.2.1
+      | XFF is changed to "203.0.113.128, 203.0.113.10, 192.0.2.1, 192.0.2.5"
+      | X-Envoy-Internal is removed (if it was present in the incoming request)
+
+Example 8: Envoy as edge proxy, with two trusted CIDRs
+    Settings:
+      | use_remote_address = false
+      | xff_trusted_cidrs = 192.0.2.0/24, 198.51.100.0/24
+
+    Request details:
+      | Downstream IP address = 192.0.2.5
+      | XFF = "203.0.113.128, 203.0.113.10, 198.51.100.1"
+
+    Result:
+      | Trusted client address = 203.0.113.10
+      | X-Envoy-External-Address is set to 203.0.113.10
+      | XFF is changed to "203.0.113.128, 203.0.113.10, 198.51.100.1, 192.0.2.5"
+      | X-Envoy-Internal is removed (if it was present in the incoming request)
+
 A few very important notes about XFF:
 
 1. If ``use_remote_address`` is set to true, Envoy sets the

envoy/http/original_ip_detection.h

@@ -39,6 +39,8 @@ struct OriginalIPDetectionResult {
   // If set, these parameters will be used to signal that detection failed and the request should
   // be rejected.
   absl::optional<OriginalIPRejectRequestOptions> reject_options;
+  // Whether to skip appending the detected remote address to ``x-forwarded-for``.
+  bool skip_xff_append;
 };
 
 /**

source/common/http/BUILD

@@ -545,6 +545,7 @@ envoy_cc_library(
         "//source/common/common:enum_to_int",
         "//source/common/common:utility_lib",
         "//source/common/grpc:status_lib",
+        "//source/common/network:cidr_range_lib",
         "//source/common/network:utility_lib",
         "//source/common/protobuf:utility_lib",
         "//source/common/runtime:runtime_features_lib",

source/common/http/conn_manager_utility.cc

@@ -76,6 +76,16 @@ ServerConnectionPtr ConnectionManagerUtility::autoCreateCodec(
   }
 }
 
+void ConnectionManagerUtility::appendXff(RequestHeaderMap& request_headers,
+                                         Network::Connection& connection,
+                                         ConnectionManagerConfig& config) {
+  if (Network::Utility::isLoopbackAddress(*connection.connectionInfoProvider().remoteAddress())) {
+    Utility::appendXff(request_headers, config.localAddress());
+  } else {
+    Utility::appendXff(request_headers, *connection.connectionInfoProvider().remoteAddress());
+  }
+}
+
 ConnectionManagerUtility::MutateRequestHeadersResult ConnectionManagerUtility::mutateRequestHeaders(
     RequestHeaderMap& request_headers, Network::Connection& connection,
     ConnectionManagerConfig& config, const Router::Config& route_config,
@@ -134,12 +144,7 @@ ConnectionManagerUtility::MutateRequestHeadersResult ConnectionManagerUtility::m
       final_remote_address = connection.connectionInfoProvider().remoteAddress();
     }
     if (!config.skipXffAppend()) {
-      if (Network::Utility::isLoopbackAddress(
-              *connection.connectionInfoProvider().remoteAddress())) {
-        Utility::appendXff(request_headers, config.localAddress());
-      } else {
-        Utility::appendXff(request_headers, *connection.connectionInfoProvider().remoteAddress());
-      }
+      appendXff(request_headers, connection, config);
     }
     // If the prior hop is not a trusted proxy, overwrite any
     // x-forwarded-proto/x-forwarded-port value it set as untrusted. Alternately if no
@@ -171,6 +176,9 @@ ConnectionManagerUtility::MutateRequestHeadersResult ConnectionManagerUtility::m
       if (result.reject_options.has_value()) {
         return {nullptr, result.reject_options};
       }
+      if (!result.skip_xff_append) {
+        appendXff(request_headers, connection, config);
+      }
 
       if (result.detected_remote_address) {
         final_remote_address = result.detected_remote_address;

source/common/http/conn_manager_utility.h

@@ -138,6 +138,8 @@ class ConnectionManagerUtility {
                              ConnectionManagerConfig& config, const Router::Route* route);
 
 private:
+  static void appendXff(RequestHeaderMap& request_headers, Network::Connection& connection,
+                        ConnectionManagerConfig& config);
   static void mutateXfccRequestHeader(RequestHeaderMap& request_headers,
                                       Network::Connection& connection,
                                       ConnectionManagerConfig& config);

source/common/http/utility.cc

@@ -22,6 +22,7 @@
 #include "source/common/http/header_map_impl.h"
 #include "source/common/http/headers.h"
 #include "source/common/http/message_impl.h"
+#include "source/common/network/cidr_range.h"
 #include "source/common/network/utility.h"
 #include "source/common/protobuf/utility.h"
 #include "source/common/runtime/runtime_features.h"
@@ -756,6 +757,53 @@ void Utility::sendLocalReply(const bool& is_reset, const EncodeFunctions& encode
   encodeLocalReply(is_reset, std::move(prepared_local_reply));
 }
 
+bool Utility::remoteAddressIsTrustedProxy(
+    const Envoy::Network::Address::InstanceConstSharedPtr& remote,
+    const std::vector<Network::Address::CidrRange> trusted_cidrs) {
+  for (const auto& cidr : trusted_cidrs) {
+    if (cidr.isInRange(*remote.get())) {
+      return true;
+    }
+  }
+  return false;
+}
+
+Utility::GetLastAddressFromXffInfo Utility::getLastNonTrustedAddressFromXFF(
+    const Http::RequestHeaderMap& request_headers,
+    const std::vector<Network::Address::CidrRange> trusted_cidrs) {
+  const auto xff_header = request_headers.getForwardedForValue();
+  static constexpr absl::string_view separator(",");
+
+  const auto xff_entries = StringUtil::splitToken(xff_header, separator, false, true);
+  Network::Address::InstanceConstSharedPtr last_valid_addr;
+
+  for (auto it = xff_entries.rbegin(); it != xff_entries.rend(); it++) {
+    auto addr = Network::Utility::parseInternetAddressNoThrow(std::string(*it));
+    if (addr == nullptr) {
+      return {nullptr, false};
+    }
+    last_valid_addr = addr;
+
+    bool remoteAddressIsTrustedProxy = false;
+    for (const auto& cidr : trusted_cidrs) {
+      if (cidr.isInRange(*addr.get())) {
+        remoteAddressIsTrustedProxy = true;
+        break;
+      }
+    }
+
+    if (remoteAddressIsTrustedProxy) {
+      continue;
+    }
+
+    // If we reach here we found a non-trusted address
+    return {addr, xff_entries.size() == 1};
+  }
+  // If we reach this point all addresses in XFF were considered trusted, so return
+  // first IP in XFF (the last in the reverse-evaluated chain).
+  return {last_valid_addr, xff_entries.size() == 1};
+}
+
 Utility::GetLastAddressFromXffInfo
 Utility::getLastAddressFromXFF(const Http::RequestHeaderMap& request_headers,
                                uint32_t num_to_skip) {

source/common/http/utility.h

@@ -4,6 +4,7 @@
 #include <cstdint>
 #include <memory>
 #include <string>
+#include <vector>
 
 #include "envoy/common/regex.h"
 #include "envoy/config/core/v3/http_uri.pb.h"
@@ -389,6 +390,26 @@ struct GetLastAddressFromXffInfo {
   bool allow_trusted_address_checks_;
 };
 
+/**
+ * Checks if the remote address is contained by one of the trusted proxy CIDRs.
+ * @param remote the remote address
+ * @param trusted_cidrs the list of CIDRs which are considered trusted proxies
+ * @return whether the remote address is a trusted proxy
+ */
+bool remoteAddressIsTrustedProxy(const Envoy::Network::Address::InstanceConstSharedPtr& remote,
+                                 const std::vector<Network::Address::CidrRange> trusted_cidrs);
+
+/**
+ * Retrieves the last address in the x-forwarded-header after removing all trusted proxy addresses.
+ * @param request_headers supplies the request headers
+ * @param trusted_cidrs the list of CIDRs which are considered trusted proxies
+ * @return GetLastAddressFromXffInfo information about the last address in the XFF header.
+ *         @see GetLastAddressFromXffInfo for more information.
+ */
+GetLastAddressFromXffInfo
+getLastNonTrustedAddressFromXFF(const Http::RequestHeaderMap& request_headers,
+                                const std::vector<Network::Address::CidrRange> trusted_cidrs);
+
 /**
  * Retrieves the last IPv4/IPv6 address in the x-forwarded-for header.
  * @param request_headers supplies the request headers.

source/extensions/http/original_ip_detection/custom_header/custom_header.cc

@@ -28,16 +28,16 @@ Envoy::Http::OriginalIPDetectionResult
 CustomHeaderIPDetection::detect(Envoy::Http::OriginalIPDetectionParams& params) {
   auto hdr = params.request_headers.get(header_name_);
   if (hdr.empty()) {
-    return {nullptr, false, reject_options_};
+    return {nullptr, false, reject_options_, false};
   }
 
   auto header_value = hdr[0]->value().getStringView();
   auto addr = Network::Utility::parseInternetAddressNoThrow(std::string(header_value));
   if (addr) {
-    return {addr, allow_trusted_address_checks_, absl::nullopt};
+    return {addr, allow_trusted_address_checks_, absl::nullopt, false};
   }
 
-  return {nullptr, false, reject_options_};
+  return {nullptr, false, reject_options_, false};
 }
 
 } // namespace CustomHeader

source/extensions/http/original_ip_detection/xff/BUILD

@@ -18,6 +18,9 @@ envoy_cc_library(
     deps = [
         "//envoy/http:original_ip_detection_interface",
         "//source/common/http:utility_lib",
+        "//source/common/network:cidr_range_lib",
+        "//source/common/protobuf",
+        "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
         "@envoy_api//envoy/extensions/http/original_ip_detection/xff/v3:pkg_cc_proto",
     ],
 )
@@ -33,6 +36,7 @@ envoy_cc_extension(
         "//envoy/http:original_ip_detection_interface",
         "//envoy/registry",
         "//source/common/config:utility_lib",
+        "//source/common/network:cidr_range_lib",
         "@envoy_api//envoy/extensions/http/original_ip_detection/xff/v3:pkg_cc_proto",
     ],
 )