Geoip filter

CODEOWNERS

@@ -303,6 +303,9 @@ extensions/filters/http/oauth2 @derekargueta @snowp
 /*/extensions/health_checkers/grpc @snowp @zuercher
 /*/extensions/health_checkers/http @snowp @zuercher
 /*/extensions/health_checkers/tcp @snowp @zuercher
+# IP Geolocation
+/*/extensions/filters/http/geoip @nezdolik @ravenblackx
+
 /*/extensions/health_checkers/common @snowp @zuercher
 
 # Intentionally exempt (treated as core code)

api/BUILD

@@ -175,6 +175,7 @@ proto_library(
         "//envoy/extensions/filters/http/fault/v3:pkg",
         "//envoy/extensions/filters/http/file_system_buffer/v3:pkg",
         "//envoy/extensions/filters/http/gcp_authn/v3:pkg",
+        "//envoy/extensions/filters/http/geoip/v3:pkg",
         "//envoy/extensions/filters/http/grpc_http1_bridge/v3:pkg",
         "//envoy/extensions/filters/http/grpc_http1_reverse_bridge/v3:pkg",
         "//envoy/extensions/filters/http/grpc_json_transcoder/v3:pkg",

api/envoy/extensions/filters/http/geoip/v3/BUILD

@@ -0,0 +1,13 @@
+# 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/config/core/v3:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
+    ],
+)

api/envoy/extensions/filters/http/geoip/v3/geoip.proto

@@ -0,0 +1,90 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.geoip.v3;
+
+import "envoy/config/core/v3/extension.proto";
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.geoip.v3";
+option java_outer_classname = "GeoipProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/geoip/v3;geoipv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: Geoip]
+// Geoip :ref:`configuration overview <config_http_filters_geoip>`.
+// [#extension: envoy.filters.http.geoip]
+
+message Geoip {
+  // The set of geolocation headers to add to request. If any of the configured headers is present
+  // in the incoming request, it will be overridden by Geoip filter.
+  // [#next-free-field: 10]
+  message GeolocationHeadersToAdd {
+    // If set, the header will be used to populate the country ISO code associated with the IP address.
+    string country = 1
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the header will be used to populate the city associated with the IP address.
+    string city = 2
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the header will be used to populate the region ISO code associated with the IP address.
+    string region = 3
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the header will be used to populate the ASN associated with the IP address.
+    string asn = 4
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the IP address will be checked if it belongs to any type of anonymization network (e.g. VPN, public proxy etc)
+    // and header will be populated with the check result. Header value will be set to either "true" or "false" depending on the check result.
+    string is_anon = 5
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the IP address will be checked if it belongs to a VPN and header will be populated with the check result.
+    // Header value will be set to either "true" or "false" depending on the check result.
+    string anon_vpn = 6
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the IP address will be checked if it belongs to a hosting provider and header will be populated with the check result.
+    // Header value will be set to either "true" or "false" depending on the check result.
+    string anon_hosting = 7
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the IP address will be checked if it belongs to a TOR exit node and header will be populated with the check result.
+    // Header value will be set to either "true" or "false" depending on the check result.
+    string anon_tor = 8
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // If set, the IP address will be checked if it belongs to a public proxy and header will be populated with the check result.
+    // Header value will be set to either "true" or "false" depending on the check result.
+    string anon_proxy = 9
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+  }
+
+  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;
+  }
+
+  // If set, the :ref:`xff_num_trusted_hops <envoy_v3_api_field_extensions.filters.http.geoip.v3.Geoip.XffConfig.xff_num_trusted_hops>` field will be used to determine
+  // trusted client address from `x-forwarded-for` header.
+  // Otherwise, the immediate downstream connection source address will be used.
+  // [#next-free-field: 2]
+  XffConfig xff_config = 1;
+
+  // Configuration for geolocation headers to add to request.
+  GeolocationHeadersToAdd geo_headers_to_add = 2 [(validate.rules).message = {required: true}];
+
+  // Geolocation provider specific configuration.
+  config.core.v3.TypedExtensionConfig provider = 3 [(validate.rules).message = {required: true}];
+}

api/versioning/BUILD

@@ -113,6 +113,7 @@ proto_library(
         "//envoy/extensions/filters/http/fault/v3:pkg",
         "//envoy/extensions/filters/http/file_system_buffer/v3:pkg",
         "//envoy/extensions/filters/http/gcp_authn/v3:pkg",
+        "//envoy/extensions/filters/http/geoip/v3:pkg",
         "//envoy/extensions/filters/http/grpc_http1_bridge/v3:pkg",
         "//envoy/extensions/filters/http/grpc_http1_reverse_bridge/v3:pkg",
         "//envoy/extensions/filters/http/grpc_json_transcoder/v3:pkg",

docs/root/configuration/http/http_filters/geoip_filter.rst

@@ -0,0 +1,46 @@
+.. _config_http_filters_geoip:
+
+IP Geolocation Filter
+=========================
+This filter decorates HTTP requests with the geolocation data.
+Filter uses client address to lookup information (eg client's city, country) in the geolocation provider database.
+Upon a successful lookup request will be enriched with the configured geolocation header and value from the database.
+In case the configured geolocation headers are present in the incoming request, they will be overriden by the filter.
+Geolocation filter emits stats for the number of successful lookups and the number of total lookups.
+
+Configuration
+-------------
+* This filter should be configured with the type URL ``type.googleapis.com/envoy.extensions.filters.http.geoip.v3.Geoip``.
+* :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.geoip.v3.Geoip>`
+
+Statistics
+----------
+Geolocation filter outputs statistics in the
+*http.<stat_prefix>.geoip.<geo-header-name>.* namespace. The :ref:`stat prefix
+<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stat_prefix>`
+comes from the owning HTTP connection manager.
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: auto
+
+  .hit, Counter, Number of successful lookups within geolocation database for a configured geolocation header.
+  .total, Counter, Number of total lookups within geolocation database for a configured geolocation header.
+
+
+Configuration example
+---------------------
+
+.. code-block:: yaml
+
+  name: envoy.filters.http.geoip
+  typed_config:
+    "@type": type.googleapis.com/envoy.extensions.filters.http.geoip.v3.Geoip
+    use_xff: true
+    xff_num_trusted_hops: 1
+    geo_headers_to_add:
+      country: "x-geo-country"
+      region: "x-geo-region"
+    provider:
+        name: "envoy.geoip_providers.maxmind"
+

docs/root/configuration/http/http_filters/http_filters.rst

@@ -28,6 +28,7 @@ HTTP filters
   fault_filter
   file_system_buffer_filter
   gcp_authn_filter
+  geoip_filter
   golang_filter
   grpc_http1_bridge_filter
   grpc_http1_reverse_bridge_filter

source/extensions/extensions_build_config.bzl

@@ -127,6 +127,7 @@ EXTENSIONS = {
     "envoy.filters.http.fault":                         "//source/extensions/filters/http/fault:config",
     "envoy.filters.http.file_system_buffer":            "//source/extensions/filters/http/file_system_buffer:config",
     "envoy.filters.http.gcp_authn":                     "//source/extensions/filters/http/gcp_authn:config",
+    "envoy.filters.http.geoip":                     "//source/extensions/filters/http/geoip:config",
     "envoy.filters.http.grpc_http1_bridge":             "//source/extensions/filters/http/grpc_http1_bridge:config",
     "envoy.filters.http.grpc_http1_reverse_bridge":     "//source/extensions/filters/http/grpc_http1_reverse_bridge:config",
     "envoy.filters.http.grpc_json_transcoder":          "//source/extensions/filters/http/grpc_json_transcoder:config",

source/extensions/extensions_metadata.yaml

@@ -238,6 +238,13 @@ envoy.filters.http.cdn_loop:
   status: alpha
   type_urls:
   - envoy.extensions.filters.http.cdn_loop.v3.CdnLoopConfig
+envoy.filters.http.geoip:
+  categories:
+  - envoy.filters.http
+  security_posture: unknown
+  status: wip
+  type_urls:
+  - envoy.extensions.filters.http.geoip.v3.Geoip
 envoy.filters.http.upstream_codec:
   categories:
   - envoy.filters.http.upstream

source/extensions/filters/http/geoip/BUILD

@@ -0,0 +1,60 @@
+load(
+    "//bazel:envoy_build_system.bzl",
+    "envoy_cc_extension",
+    "envoy_cc_library",
+    "envoy_extension_package",
+)
+
+licenses(["notice"])  # Apache 2
+
+# HTTP L7 filter that decorates request with geolocation data
+# Public docs: https://envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/geoip_filter
+
+envoy_extension_package()
+
+envoy_cc_library(
+    name = "geoip_filter_lib",
+    srcs = ["geoip_filter.cc"],
+    hdrs = ["geoip_filter.h"],
+    deps = [
+        ":provider_config",
+        "//envoy/http:filter_interface",
+        "//envoy/runtime:runtime_interface",
+        "//source/common/common:assert_lib",
+        "//source/common/http:header_map_lib",
+        "//source/common/http:headers_lib",
+        "//source/common/http:utility_lib",
+        "//source/common/stats:symbol_table_lib",
+        "@envoy_api//envoy/extensions/filters/http/geoip/v3:pkg_cc_proto",
+    ],
+)
+
+#todo(nezdolik) may need to split into interface and impl
+envoy_cc_extension(
+    name = "provider_config",
+    hdrs = [
+        "geoip_provider_config.h",
+        "geoip_provider_config_impl.h",
+    ],
+    deps = [
+        "//envoy/config:typed_config_interface",
+        "//envoy/network:address_interface",
+        "//envoy/protobuf:message_validator_interface",
+        "//source/common/common:hash_lib",
+        "@envoy_api//envoy/extensions/filters/http/geoip/v3:pkg_cc_proto",
+    ],
+)
+
+envoy_cc_extension(
+    name = "config",
+    srcs = ["config.cc"],
+    hdrs = ["config.h"],
+    deps = [
+        ":provider_config",
+        "//source/common/config:utility_lib",
+        "//source/common/protobuf:utility_lib",
+        "//source/extensions/filters/http/common:factory_base_lib",
+        "//source/extensions/filters/http/geoip:geoip_filter_lib",
+        "@envoy_api//envoy/extensions/filters/http/geoip/v3:pkg_cc_proto",
+    ],
+)

source/extensions/filters/http/geoip/config.cc

@@ -0,0 +1,45 @@
+#include "source/extensions/filters/http/geoip/config.h"
+
+#include "envoy/registry/registry.h"
+
+#include "source/common/config/utility.h"
+#include "source/common/protobuf/utility.h"
+#include "source/extensions/filters/http/geoip/geoip_filter.h"
+#include "source/extensions/filters/http/geoip/geoip_provider_config_impl.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace HttpFilters {
+namespace Geoip {
+
+Http::FilterFactoryCb GeoipFilterFactory::createFilterFactoryFromProtoTyped(
+    const envoy::extensions::filters::http::geoip::v3::Geoip& proto_config,
+    const std::string& stat_prefix, Server::Configuration::FactoryContext& context) {
+  if (!provider_context_) {
+    provider_context_ =
+        std::make_unique<GeoipProviderFactoryContextImpl>(context.messageValidationVisitor());
+  }
+  GeoipFilterConfigSharedPtr filter_config(
+      std::make_shared<GeoipFilterConfig>(proto_config, stat_prefix, context.scope()));
+
+  const auto& provider_config = proto_config.provider();
+  auto& geo_provider_factory =
+      Envoy::Config::Utility::getAndCheckFactory<GeoipProviderFactory>(provider_config);
+  ProtobufTypes::MessagePtr message = Envoy::Config::Utility::translateToFactoryConfig(
+      provider_config, provider_context_->messageValidationVisitor(), geo_provider_factory);
+  auto driver = geo_provider_factory.createGeoipProviderDriver(*message, provider_context_);
+  return [filter_config, driver](Http::FilterChainFactoryCallbacks& callbacks) -> void {
+    callbacks.addStreamDecoderFilter(std::make_shared<GeoipFilter>(filter_config, driver));
+  };
+}
+
+/**
+ * Static registration for geoip filter. @see RegisterFactory.
+ */
+REGISTER_FACTORY(GeoipFilterFactory,
+                 Server::Configuration::NamedHttpFilterConfigFactory){"envoy.geoip"};
+
+} // namespace Geoip
+} // namespace HttpFilters
+} // namespace Extensions
+} // namespace Envoy

source/extensions/filters/http/geoip/config.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "envoy/extensions/filters/http/geoip/v3/geoip.pb.h"
+#include "envoy/extensions/filters/http/geoip/v3/geoip.pb.validate.h"
+
+#include "source/extensions/filters/http/common/factory_base.h"
+#include "source/extensions/filters/http/geoip/geoip_provider_config.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace HttpFilters {
+namespace Geoip {
+
+/**
+ * Config registration for the geoip filter. @see NamedHttpFilterConfigFactory.
+ */
+class GeoipFilterFactory
+    : public Common::FactoryBase<envoy::extensions::filters::http::geoip::v3::Geoip> {
+public:
+  GeoipFilterFactory() : FactoryBase("envoy.filters.http.geoip") {}
+
+  Http::FilterFactoryCb createFilterFactoryFromProtoTyped(
+      const envoy::extensions::filters::http::geoip::v3::Geoip& proto_config,
+      const std::string& stats_prefix, Server::Configuration::FactoryContext& context) override;
+
+private:
+  GeoipProviderFactoryContextPtr provider_context_;
+};
+
+} // namespace Geoip
+} // namespace HttpFilters
+} // namespace Extensions
+} // namespace Envoy