envoyproxy · htuch · May 16, 2021 · Jan 28, 2021 · Jan 28, 2021 · Jan 29, 2021
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -183,3 +183,6 @@ extensions/filters/http/oauth2 @rgs1 @derekargueta @snowp
 /*/extensions/filters/common/ext_authz @esmet @gsagula @dio
 /*/extensions/filters/http/ext_authz @esmet @gsagula @dio
 /*/extensions/filters/network/ext_authz @esmet @gsagula @dio
+# Original IP detection
+/*/extensions/http/original_ip_detection/custom_header @rgs1 @alyssawilk @antoniovicente
+/*/extensions/http/original_ip_detection/xff @rgs1 @alyssawilk @antoniovicente
diff --git a/api/BUILD b/api/BUILD
@@ -245,6 +245,8 @@ proto_library(
         "//envoy/extensions/filters/udp/udp_proxy/v3:pkg",
         "//envoy/extensions/health_checkers/redis/v3:pkg",
         "//envoy/extensions/http/header_formatters/preserve_case/v3:pkg",
+        "//envoy/extensions/http/original_ip_detection/custom_header/v3:pkg",
+        "//envoy/extensions/http/original_ip_detection/xff/v3:pkg",
         "//envoy/extensions/internal_redirect/allow_listed_routes/v3:pkg",
         "//envoy/extensions/internal_redirect/previous_routes/v3:pkg",
         "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg",

diff --git a/api/envoy/extensions/filters/network/http_connection_manager/v3/BUILD b/api/envoy/extensions/filters/network/http_connection_manager/v3/BUILD
@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/config/accesslog/v3:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/config/filter/network/http_connection_manager/v2:pkg",

diff --git a/...envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/...envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto
@@ -19,6 +19,7 @@ import "google/protobuf/any.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
@@ -34,7 +35,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
 // [#extension: envoy.filters.network.http_connection_manager]
 
-// [#next-free-field: 46]
+// [#next-free-field: 47]
 message HttpConnectionManager {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager";
@@ -495,7 +496,36 @@ message HttpConnectionManager {
   // 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.
-  uint32 xff_num_trusted_hops = 19;
+  //
+  // .. note::
+  //    This field is deprecated and instead :ref:`original_ip_detection_extensions
+  //    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`
+  //    should be used to configure the :ref:`xff extension <envoy_v3_api_msg_extensions.http.original_ip_detection.xff.v3.XffConfig>`
+  //    to configure IP detection using the :ref:`config_http_conn_man_headers_x-forwarded-for` header. To replace
+  //    this field use a config like the following:
+  //
+  // .. code-block:: yaml
+  //
+  //    original_ip_detection_extensions:
+  //      typed_config:
+  //        "@type": type.googleapis.com/envoy.extensions.http.original_ip_detection.xff.v3.XffConfig
+  //        xff_num_trusted_hops: 1
+  //
+  uint32 xff_num_trusted_hops = 19
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
+
+  // The configuration for the original IP detection extensions.
+  //
+  // When configured the extensions will be called along with the request headers
+  // and information about the downstream connection, such as the directly connected address.
+  // Each extension will then use these parameters to decide the request's effective remote address.
+  // If an extension fails to detect the original IP address and isn't configured to reject
+  // the request, the HCM will try the remaining extensions until one succeeds or rejects
+  // the request. If the request isn't rejected nor any extension succeeds, the HCM will
+  // fallback to using the remote address.
+  //
+  // [#extension-category: envoy.http.original_ip_detection]
+  repeated config.core.v3.TypedExtensionConfig original_ip_detection_extensions = 46;
 
   // Configures what network addresses are considered internal for stats and header sanitation
   // purposes. If unspecified, only RFC1918 IP addresses will be considered internal.

diff --git a/.../extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto b/.../extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto
diff --git a/api/envoy/extensions/http/original_ip_detection/custom_header/v3/BUILD b/api/envoy/extensions/http/original_ip_detection/custom_header/v3/BUILD
@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/type/v3:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)
diff --git a/api/envoy/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto b/api/envoy/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto
@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package envoy.extensions.http.original_ip_detection.custom_header.v3;
+
+import "envoy/type/v3/http_status.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.http.original_ip_detection.custom_header.v3";
+option java_outer_classname = "CustomHeaderProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Custom header original IP detection extension]
+
+// This extension allows for the original downstream remote IP to be detected
+// by reading the value from a configured header name. If the value is successfully parsed
+// as an IP, it'll be treated as the effective downstream remote address and seen as such
+// by all filters. See :ref:`original_ip_detection_extensions
+// <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`
+// for an overview of how extensions operate and what happens when an extension fails
+// to detect the remote IP.
+//
+// [#extension: envoy.http.original_ip_detection.custom_header]
+message CustomHeaderConfig {
+  // The header name containing the original downstream remote address, if present.
+  //
+  // Note: in the case of a multi-valued header, only the first value is tried and the rest are ignored.
+  string header_name = 1
+      [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: true}];
+
+  // If set to true, the extension could decide that the detected address should be treated as
+  // trusted by the HCM. If the address is considered :ref:`trusted<config_http_conn_man_headers_x-forwarded-for_trusted_client_address>`,
+  // it might be used as input to determine if the request is internal (among other things).
+  bool allow_extension_to_set_address_as_trusted = 2;
+
+  // If this is set, the request will be rejected when detection fails using it as the HTTP response status.
+  //
+  // .. note::
+  //   If this is set to < 400 or > 511, the default status 403 will be used instead.
+  type.v3.HttpStatus reject_with_status = 3;
+}
diff --git a/api/envoy/extensions/http/original_ip_detection/xff/v3/BUILD b/api/envoy/extensions/http/original_ip_detection/xff/v3/BUILD
@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)
diff --git a/api/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto b/api/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto
@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package envoy.extensions.http.original_ip_detection.xff.v3;
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.http.original_ip_detection.xff.v3";
+option java_outer_classname = "XffProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: XFF original IP detection extension]
+
+// This extension allows for the original downstream remote IP to be detected
+// by reading the :ref:`config_http_conn_man_headers_x-forwarded-for` header.
+//
+// [#extension: envoy.http.original_ip_detection.xff]
+message XffConfig {
+  // The number of additional ingress proxy hops from the right side of the
+  // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header to trust when
+  // 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.
+  uint32 xff_num_trusted_hops = 1;
+}
diff --git a/api/versioning/BUILD b/api/versioning/BUILD
@@ -128,6 +128,8 @@ proto_library(
         "//envoy/extensions/filters/udp/udp_proxy/v3:pkg",
         "//envoy/extensions/health_checkers/redis/v3:pkg",
         "//envoy/extensions/http/header_formatters/preserve_case/v3:pkg",
+        "//envoy/extensions/http/original_ip_detection/custom_header/v3:pkg",
+        "//envoy/extensions/http/original_ip_detection/xff/v3:pkg",
         "//envoy/extensions/internal_redirect/allow_listed_routes/v3:pkg",
         "//envoy/extensions/internal_redirect/previous_routes/v3:pkg",
         "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg",

diff --git a/bazel/envoy_library.bzl b/bazel/envoy_library.bzl
@@ -84,6 +84,7 @@ EXTENSION_CATEGORIES = [
     "envoy.http.stateful_header_formatters",
     "envoy.internal_redirect_predicates",
     "envoy.io_socket",
+    "envoy.http.original_ip_detection",
     "envoy.matching.common_inputs",
     "envoy.matching.input_matchers",
     "envoy.rate_limit_descriptors",

diff --git a/docs/root/api-v3/config/config.rst b/docs/root/api-v3/config/config.rst
@@ -27,3 +27,4 @@ Extensions
   descriptors/descriptors
   request_id/request_id
   http/header_formatters
+  http/original_ip_detection
diff --git a/docs/root/api-v3/config/http/original_ip_detection.rst b/docs/root/api-v3/config/http/original_ip_detection.rst
@@ -0,0 +1,8 @@
+Original IP Detection
+=====================
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../../extensions/http/original_ip_detection/*/v3/*
diff --git a/docs/root/configuration/http/http_conn_man/headers.rst b/docs/root/configuration/http/http_conn_man/headers.rst
@@ -189,7 +189,9 @@ Given an HTTP request that has traveled through a series of zero or more proxies
 Envoy, the trusted client address is the earliest source IP address that is known to be
 accurate. The source IP address of the immediate downstream node's connection to Envoy is
 trusted. XFF *sometimes* can be trusted. Malicious clients can forge XFF, but the last
-address in XFF can be trusted if it was put there by a trusted proxy.
+address in XFF can be trusted if it was put there by a trusted proxy. Alternatively, Envoy
+supports :ref:`extensions <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`
+for determining the *trusted client address* or original IP address.
 
 Envoy's default rules for determining the trusted client address (*before* appending anything
 to XFF) are:
@@ -200,8 +202,11 @@ to XFF) are:
   node's connection to Envoy.
 
 In an environment where there are one or more trusted proxies in front of an edge
-Envoy instance, the *xff_num_trusted_hops* configuration option can be used to trust
-additional addresses from XFF:
+Envoy instance, the :ref:`XFF extension <envoy_v3_api_msg_extensions.http.original_ip_detection.xff.v3.XffConfig>`
+can be configured via the :ref:`original_ip_detection_extensions field
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`
+to set the *xff_num_trusted_hops* option which controls the number of additional
+addresses that are to be trusted:
 
 * If *use_remote_address* is false and *xff_num_trusted_hops* is set to a value *N* that is
   greater than zero, the trusted client address is the (N+1)th address from the right end

diff --git a/docs/root/configuration/http/http_conn_man/response_code_details.rst b/docs/root/configuration/http/http_conn_man/response_code_details.rst
@@ -35,6 +35,7 @@ Below are the list of reasons the HttpConnectionManager or Router filter may sen
    missing_path_rejected, The request was rejected due to a missing Path or :path header field.
    no_healthy_upstream, The request was rejected by the router filter because there was no healthy upstream found.
    overload, The request was rejected due to the Overload Manager reaching configured resource limits.
+   original_ip_detection_failed, The request was rejected because the original IP couldn't be detected.
    path_normalization_failed, "The request was rejected because path normalization was configured on and failed, probably due to an invalid path."
    request_headers_failed_strict_check, The request was rejected due to x-envoy-* headers failing strict header validation.
    request_overall_timeout, The per-stream total request timeout was exceeded.

diff --git a/docs/root/configuration/http/http_conn_man/stats.rst b/docs/root/configuration/http/http_conn_man/stats.rst
@@ -45,6 +45,7 @@ statistics:
    downstream_rq_http2_total, Counter, Total HTTP/2 requests
    downstream_rq_http3_total, Counter, Total HTTP/3 requests
    downstream_rq_active, Gauge, Total active requests
+   downstream_rq_rejected_via_ip_detection, Counter, Total requests rejected because the original IP detection failed
    downstream_rq_response_before_rq_complete, Counter, Total responses sent before the request was complete
    downstream_rq_rx_reset, Counter, Total request resets received
    downstream_rq_tx_reset, Counter, Total request resets sent

diff --git a/docs/root/intro/arch_overview/other_features/ip_transparency.rst b/docs/root/intro/arch_overview/other_features/ip_transparency.rst
@@ -20,6 +20,14 @@ called the *downstream remote address*, for many reasons. Some examples include:
 Envoy supports multiple methods for providing the downstream remote address to the upstream host.
 These techniques vary in complexity and applicability.
 
+Envoy also supports
+:ref:`extensions <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`
+for detecting the original IP address. This might be useful if none of the techniques below is
+applicable to your setup. Two available extensions are the :ref:`custom header
+<envoy_v3_api_msg_extensions.http.original_ip_detection.custom_header.v3.CustomHeaderConfig>`
+extension and the :ref:`xff <envoy_v3_api_msg_extensions.http.original_ip_detection.xff.v3.XffConfig>`
+extension.
+
 HTTP Headers
 ------------
 

diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst
@@ -61,6 +61,9 @@ Removed Config or Runtime
 New Features
 ------------
 
+* http: added support for :ref:`original IP detection extensions<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`.
+  Two initial extensions were added, the :ref:`custom header <envoy_v3_api_msg_extensions.http.original_ip_detection.custom_header.v3.CustomHeaderConfig>` extension and the
+  :ref:`xff <envoy_v3_api_msg_extensions.http.original_ip_detection.xff.v3.XffConfig>` extension.
 * http: added the ability to :ref:`unescape slash sequences<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.path_with_escaped_slashes_action>` in the path. Requests with unescaped slashes can be proxied, rejected or redirected to the new unescaped path. By default this feature is disabled. The default behavior can be overridden through :ref:`http_connection_manager.path_with_escaped_slashes_action<config_http_conn_man_runtime_path_with_escaped_slashes_action>` runtime variable. This action can be selectively enabled for a portion of requests by setting the :ref:`http_connection_manager.path_with_escaped_slashes_action_sampling<config_http_conn_man_runtime_path_with_escaped_slashes_action_enabled>` runtime variable.
 * http: added upstream and downstream alpha HTTP/3 support! See :ref:`quic_options <envoy_v3_api_field_config.listener.v3.UdpListenerConfig.quic_options>` for downstream and the new http3_protocol_options in :ref:`http_protocol_options <envoy_v3_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` for upstream HTTP/3.
 * listener: added ability to change an existing listener's address.
@@ -69,3 +72,5 @@ New Features
 
 Deprecated
 ----------
+
+* http: :ref:`xff_num_trusted_hops <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.xff_num_trusted_hops>` is deprecated in favor of :ref:`original IP detection extensions<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.original_ip_detection_extensions>`.
diff --git a/generated_api_shadow/BUILD b/generated_api_shadow/BUILD
@@ -245,6 +245,8 @@ proto_library(
         "//envoy/extensions/filters/udp/udp_proxy/v3:pkg",
         "//envoy/extensions/health_checkers/redis/v3:pkg",
         "//envoy/extensions/http/header_formatters/preserve_case/v3:pkg",
+        "//envoy/extensions/http/original_ip_detection/custom_header/v3:pkg",
+        "//envoy/extensions/http/original_ip_detection/xff/v3:pkg",
         "//envoy/extensions/internal_redirect/allow_listed_routes/v3:pkg",
         "//envoy/extensions/internal_redirect/previous_routes/v3:pkg",
         "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg",