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,37 @@ 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.
+  //
+  // If ``xff_trusted_cidrs`` is configured, this field is not used.
   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 origin 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, the last
+  // IP address from ``x-forwarded-for`` is used as the original client address.
+  // If no ``x-forwarded-for`` header was sent, the remote IP is considered the real IP.
+  //
+  // If ``recurse`` is set the :ref:`config_http_conn_man_headers_x-forwarded-for`
+  // header is also evaluated against the trusted CIDR list, and the last non-trusted
+  // address is used as the original client address.
+  //
+  // This is typically used when requests are proxied by a
+  // `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_.
+  //
+  // If this field is configured, ``xff_num_trusted_hops`` is not used.
+  XffTrustedCidrs xff_trusted_cidrs = 2;
+}
+
+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;
+
+  // If ``true``, recurse through the :ref:`config_http_conn_man_headers_x-forwarded-for`
+  // HTTP header to find the first (from the right) non-trusted IP address; otherwise
+  // the last address in ``x-forwarded-for`` is used.
+  google.protobuf.BoolValue recurse = 2;
 }

changelogs/current.yaml

@@ -13,5 +13,9 @@ removed_config_or_runtime:
 # *Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
 
 new_features:
+- 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,12 @@ 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 extension instead.
+
 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.

source/common/http/BUILD

@@ -507,6 +507,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/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"
@@ -781,6 +782,61 @@ 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.ForwardedFor();
+  if (xff_header == nullptr) {
+    return {nullptr, false};
+  }
+
+  absl::string_view xff_string(xff_header->value().getStringView());
+  static constexpr absl::string_view separator(",");
+
+  const auto xff_entries = StringUtil::splitToken(xff_string, separator, false, true);
+
+  for (auto it = xff_entries.rbegin(); it != xff_entries.rend(); it++) {
+    auto addr = Network::Utility::parseInternetAddressNoThrow(std::string(*it));
+    if (addr == nullptr) {
+      continue;
+    }
+
+    bool trusted = false;
+    for (const auto& cidr : trusted_cidrs) {
+      if (cidr.isInRange(*addr.get())) {
+        trusted = true;
+        break;
+      }
+    }
+
+    if (trusted) {
+      continue;
+    }
+
+    // If we reach here we found a non-trusted address
+    if (Network::Utility::isInternalAddress(*addr.get()) ||
+        Network::Utility::isLoopbackAddress(*addr.get())) {
+      // If the next IP after skipping all trusted IPs is internal or loopback
+      // we cannot determine the true remote IP: Either a proxy didn't add its IP,
+      // or XFF is malformed.
+      return {nullptr, false};
+    }
+    return {addr, true};
+  }
+  return {nullptr, false};
+}
+
 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"
@@ -437,6 +438,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/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",
     ],
 )

source/extensions/http/original_ip_detection/xff/xff.cc

@@ -1,6 +1,7 @@
 #include "source/extensions/http/original_ip_detection/xff/xff.h"
 
 #include "source/common/http/utility.h"
+#include "source/common/network/cidr_range.h"
 
 namespace Envoy {
 namespace Extensions {
@@ -10,13 +11,33 @@ namespace Xff {
 
 XffIPDetection::XffIPDetection(
     const envoy::extensions::http::original_ip_detection::xff::v3::XffConfig& config)
-    : xff_num_trusted_hops_(config.xff_num_trusted_hops()) {}
+    : xff_num_trusted_hops_(!config.has_xff_trusted_cidrs() ? config.xff_num_trusted_hops() : 0),
+      recurse_(config.xff_trusted_cidrs().recurse().value()) {
+  xff_trusted_cidrs_.reserve(config.xff_trusted_cidrs().cidrs().size());
+  for (const envoy::config::core::v3::CidrRange& entry : config.xff_trusted_cidrs().cidrs()) {
+    Network::Address::CidrRange cidr = Network::Address::CidrRange::create(entry);
+    xff_trusted_cidrs_.push_back(cidr);
+  }
+}
 
 XffIPDetection::XffIPDetection(uint32_t xff_num_trusted_hops)
-    : xff_num_trusted_hops_(xff_num_trusted_hops) {}
+    : xff_num_trusted_hops_(xff_num_trusted_hops), recurse_(false) {}
 
 Envoy::Http::OriginalIPDetectionResult
 XffIPDetection::detect(Envoy::Http::OriginalIPDetectionParams& params) {
+  if (!xff_trusted_cidrs_.empty()) {
+    if (!Envoy::Http::Utility::remoteAddressIsTrustedProxy(params.downstream_remote_address,
+                                                           xff_trusted_cidrs_)) {
+      return {nullptr, false, absl::nullopt};
+    }
+    if (recurse_) {
+      // Check XFF for last IP that isn't in `xff_trusted_cidrs`
+      auto ret = Envoy::Http::Utility::getLastNonTrustedAddressFromXFF(params.request_headers,
+                                                                       xff_trusted_cidrs_);
+      return {ret.address_, ret.allow_trusted_address_checks_, absl::nullopt};
+    }
+  }
+
   auto ret =
       Envoy::Http::Utility::getLastAddressFromXFF(params.request_headers, xff_num_trusted_hops_);
   return {ret.address_, ret.allow_trusted_address_checks_, absl::nullopt};

source/extensions/http/original_ip_detection/xff/xff.h

@@ -1,8 +1,12 @@
 #pragma once
 
+#include "envoy/config/core/v3/address.pb.h"
 #include "envoy/extensions/http/original_ip_detection/xff/v3/xff.pb.h"
 #include "envoy/http/original_ip_detection.h"
 
+#include "source/common/network/cidr_range.h"
+#include "source/common/protobuf/protobuf.h"
+
 namespace Envoy {
 namespace Extensions {
 namespace Http {
@@ -22,6 +26,8 @@ class XffIPDetection : public Envoy::Http::OriginalIPDetection {
 
 private:
   const uint32_t xff_num_trusted_hops_;
+  std::vector<Network::Address::CidrRange> xff_trusted_cidrs_;
+  const bool recurse_;
 };
 
 } // namespace Xff

test/extensions/http/original_ip_detection/xff/BUILD

@@ -17,6 +17,8 @@ envoy_extension_cc_test(
     extension_names = ["envoy.http.original_ip_detection.xff"],
     deps = [
         "//source/common/http:utility_lib",
+        "//source/common/network:address_lib",
+        "//source/common/protobuf:utility_lib",
         "//source/extensions/http/original_ip_detection/xff:xff_lib",
         "//test/test_common:utility_lib",
         "@envoy_api//envoy/extensions/http/original_ip_detection/xff/v3:pkg_cc_proto",
@@ -29,6 +31,8 @@ envoy_extension_cc_test(
     extension_names = ["envoy.http.original_ip_detection.xff"],
     deps = [
         "//envoy/registry",
+        "//source/common/network:address_lib",
+        "//source/common/protobuf:utility_lib",
         "//source/extensions/http/original_ip_detection/xff:config",
         "//source/extensions/http/original_ip_detection/xff:xff_lib",
         "//test/mocks/server:factory_context_mocks",