Skip to content

Commit 4a0a639

Browse files
authored
geoip: remove configured geolocation headers from the request before the lookup (#48363)
Commit Message: geoip: remove configured geolocation headers from the request before the lookup Additional Description: The HTTP geoip filter only wrote a geolocation header when the provider had a value for it, and never removed one. A header the client sent therefore reached the upstream unchanged whenever the lookup produced nothing for it: an address absent from the database, a lookup error, a field the database lacks for that address, or a request whose lookup was skipped because the downstream address was not an IP address (the skip path from #47481). The upstream, or an RBAC/ext_authz/Lua step later in the chain, cannot tell such a header from one the filter set, although `geoip_filter.rst` and the `geo_headers_to_add` comment say a configured header present in the incoming request is overridden. This change: - adds `Geolocation::Driver::geoHeaderNames()`, additive with an empty default, so providers that do not override it keep compiling and keep their behavior; - has the maxmind provider return its configured output keys (`GeoipProviderConfig::fieldKeyNames()`), for both `geo_field_keys` and the deprecated `geo_headers_to_add` form including the `is_anon` fallback; - removes those headers at the start of `GeoipFilter::decodeHeaders`, before the address is resolved and before any path that returns without a lookup, so a configured header is present after the filter only if the lookup populated it. Removal rather than overwrite, because the lookup sets no header it has no value for. Same shape as #46586 for jwt_authn. The filter and the maxmind provider carry `security_posture: unknown` (`requires_trusted_downstream_and_upstream` per EXTENSION_POLICY.md), so this is a hardening change filed publicly. Risk Level: Low. Behavior change for a deployment that relied on client-supplied geolocation headers passing through on the no-data paths; reversible with the runtime guard. Testing: Unit tests for the filter (client header removed when the lookup has no value for it, removed on the skipped-lookup path, kept with the guard off) and for the maxmind provider (configured keys reported for `geo_field_keys` and for the deprecated `geo_headers_to_add` with `is_anon`). Integration tests against the maxmind test databases: client headers removed for an address with no data, replaced rather than duplicated for an address with data (216.160.83.56 has city/ASN data and is absent from the anonymous-IP test database, so the client's `x-geo-anon-vpn` is removed while `x-geo-country` becomes `US`). Docs Changes: `docs/root/configuration/http/http_filters/geoip_filter.rst` describes the removal and the runtime guard. Release Notes: `changelogs/current/behavior_changes/geoip__sanitize-geo-headers.rst`. Platform Specific Features: n/a Runtime guard: `envoy.reloadable_features.geoip_sanitize_geo_headers` (default true). Fixes #48362 Generative AI: an AI assistant was used in preparing this change; I have reviewed it and will handle review comments myself. this closes #48362 --------- Signed-off-by: Layau Eulizier Jr <[email protected]>
1 parent 09f784d commit 4a0a639

15 files changed

Lines changed: 267 additions & 2 deletions

File tree

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
The :ref:`HTTP geoip filter <config_http_filters_geoip>` now removes every configured geolocation header
2+
from the incoming request before the lookup, so a header a client sent is never forwarded upstream as if the
3+
lookup had set it. Previously a client-supplied header was kept whenever the lookup had no value for it: an
4+
address absent from the database, a database error, a field the database lacks for that address, or a request
5+
whose lookup was skipped because the downstream address was not an IP address. Geolocation providers report the
6+
headers they are configured to write through the new ``Driver::geoHeaderNames()`` method, which defaults to
7+
empty for providers that do not implement it. This behavior can be reverted by setting the runtime guard
8+
``envoy.reloadable_features.geoip_sanitize_geo_headers`` to ``false``.

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,11 @@ IP Geolocation Filter
55
This filter decorates HTTP requests with the geolocation data.
66
Filter uses client address to lookup information (e.g., client's city, country) in the geolocation provider database.
77
Upon a successful lookup request will be enriched with the configured geolocation header and the value from the database.
8-
In case the configured geolocation headers are present in the incoming request, they will be overridden by the filter.
8+
The configured geolocation headers are removed from the incoming request before the lookup, so a value a client
9+
sent is never forwarded as if the lookup had produced it: after the filter, a geolocation header is present only
10+
if the lookup populated it. This removal can be disabled by setting the runtime guard
11+
``envoy.reloadable_features.geoip_sanitize_geo_headers`` to ``false``, in which case a client-supplied header is
12+
kept whenever the lookup has no value for it.
913
Geolocation filter emits stats for the number of the successful lookups and the number of total lookups.
1014
English language is used for the geolocation lookups, the result of the lookup will be UTF-8 encoded.
1115
Please note that Geolocation filter and providers are not yet supported on Windows.

‎envoy/geoip/BUILD‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ envoy_cc_library(
1919
tags = ["skip_on_windows"],
2020
deps = [
2121
"//envoy/config:typed_config_interface",
22+
"//envoy/http:header_map_interface",
2223
"//envoy/network:address_interface",
2324
"//envoy/protobuf:message_validator_interface",
2425
"//envoy/server:factory_context_interface",

‎envoy/geoip/geoip_provider_driver.h‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
#pragma once
22

33
#include "envoy/config/typed_config.h"
4+
#include "envoy/http/header_map.h"
45
#include "envoy/network/address.h"
56
#include "envoy/protobuf/message_validator.h"
67
#include "envoy/server/factory_context.h"
78

89
#include "absl/container/flat_hash_set.h"
10+
#include "absl/types/span.h"
911

1012
namespace Envoy {
1113
namespace Geolocation {
@@ -40,6 +42,17 @@ class Driver {
4042
* @param cb supplies the filter callbacks to notify when lookup is complete.
4143
*/
4244
virtual void lookup(LookupRequest&& request, LookupGeoHeadersCallback&& cb) const PURE;
45+
46+
/**
47+
* @return every key this driver is configured to populate in a ``LookupResult``, that is, every
48+
* request header the HTTP geoip filter may write, lower-cased once at configuration time so the
49+
* filter can remove them from each request without further conversions. The filter removes
50+
* these headers from the request before the lookup, so a value a client sent cannot stand in
51+
* for one the lookup did not produce. The default is empty, which keeps a provider that does
52+
* not override this method on the previous behavior of only writing the headers a lookup
53+
* returns.
54+
*/
55+
virtual absl::Span<const Http::LowerCaseString> geoHeaderNames() const { return {}; }
4356
};
4457

4558
using DriverSharedPtr = std::shared_ptr<Driver>;

‎source/common/runtime/runtime_features.cc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ RUNTIME_GUARD(envoy_reloadable_features_filter_chain_drain_uses_configured_strat
9696
// lost. See https://github.com/envoyproxy/envoy/issues/46841
9797
RUNTIME_GUARD(envoy_reloadable_features_filter_manager_forward_added_data_on_continue);
9898
RUNTIME_GUARD(envoy_reloadable_features_fix_http3_early_data_timing);
99+
RUNTIME_GUARD(envoy_reloadable_features_geoip_sanitize_geo_headers);
99100
RUNTIME_GUARD(envoy_reloadable_features_grpc_side_stream_flow_control);
100101
RUNTIME_GUARD(envoy_reloadable_features_happy_eyeballs_sort_non_ip_addresses);
101102
RUNTIME_GUARD(envoy_reloadable_features_header_mutation_url_encode_query_params);

‎source/extensions/filters/http/geoip/BUILD‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ envoy_cc_library(
2525
"//source/common/http:header_map_lib",
2626
"//source/common/http:headers_lib",
2727
"//source/common/http:utility_lib",
28+
"//source/common/runtime:runtime_features_lib",
2829
"//source/common/stats:symbol_table_lib",
2930
"@envoy_api//envoy/extensions/filters/http/geoip/v3:pkg_cc_proto",
3031
],

‎source/extensions/filters/http/geoip/geoip_filter.cc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
#include "source/common/http/utility.h"
66
#include "source/common/network/utility.h"
7+
#include "source/common/runtime/runtime_features.h"
78

89
#include "absl/memory/memory.h"
910

@@ -43,6 +44,17 @@ Http::FilterHeadersStatus GeoipFilter::decodeHeaders(Http::RequestHeaderMap& hea
4344
// Save request headers for later header manipulation once geolocation lookups are complete.
4445
request_headers_ = headers;
4546

47+
// The configured geolocation headers are this filter's to write: an upstream reads them as facts
48+
// about the client address, so a value the client sent must not reach it as one. They are
49+
// removed before the lookup rather than overwritten after it, because the lookup sets no header
50+
// it has no value for (an address the database does not contain, a lookup error, a field the
51+
// database lacks for that address) and does not run at all for the non-IP addresses below.
52+
if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.geoip_sanitize_geo_headers")) {
53+
for (const Http::LowerCaseString& geo_header : driver_->geoHeaderNames()) {
54+
headers.remove(geo_header);
55+
}
56+
}
57+
4658
Network::Address::InstanceConstSharedPtr remote_address;
4759
const auto& ip_address_header = config_->ipAddressHeader();
4860
if (ip_address_header.has_value()) {

‎source/extensions/geoip_providers/maxmind/BUILD‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ envoy_cc_library(
4646
deps = [
4747
"//bazel/deps:maxmind_linux_darwin",
4848
"//envoy/geoip:geoip_provider_driver_interface",
49+
"//envoy/http:header_map_interface",
4950
"//envoy/stats:stats_macros",
5051
"//source/common/common:enum_to_int",
5152
"//source/common/common:thread_synchronizer_lib",

‎source/extensions/geoip_providers/maxmind/geoip_provider.cc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,9 @@ void GeoipProviderConfig::registerGeoDbStats(const absl::string_view& db_type) {
189189

190190
void GeoipProviderConfig::setFieldKey(GeoField field, const std::string& value) {
191191
field_keys_[enumToInt(field)] = getOptionalString(value);
192+
if (!value.empty()) {
193+
field_key_names_.emplace_back(value);
194+
}
192195
}
193196

194197
void GeoipProviderConfig::incCounter(Stats::StatName name) {

‎source/extensions/geoip_providers/maxmind/geoip_provider.h‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
#pragma once
22

33
#include <array>
4+
#include <vector>
45

56
#include "envoy/common/platform.h"
67
#include "envoy/extensions/geoip_providers/maxmind/v3/maxmind.pb.h"
78
#include "envoy/geoip/geoip_provider_driver.h"
9+
#include "envoy/http/header_map.h"
810
#include "envoy/stats/stats_macros.h"
911

1012
#include "source/common/common/enum_to_int.h"
@@ -58,6 +60,10 @@ class GeoipProviderConfig {
5860
return field_keys_[enumToInt(field)];
5961
}
6062

63+
// Every configured output key, in the order the fields were configured, lower-cased once here
64+
// so the HTTP filter can remove them from a request without per-request conversions.
65+
absl::Span<const Http::LowerCaseString> fieldKeyNames() const { return field_key_names_; }
66+
6167
void incLookupError(absl::string_view maxmind_db_type) {
6268
incCounter(
6369
stat_name_set_->getBuiltin(absl::StrCat(maxmind_db_type, ".lookup_error"), unknown_hit_));
@@ -78,6 +84,8 @@ class GeoipProviderConfig {
7884
private:
7985
// Configured output key for each GeoField.
8086
std::array<std::optional<std::string>, enumToInt(GeoField::Count)> field_keys_;
87+
// The configured output keys as a list, for callers that need all of them at once.
88+
std::vector<Http::LowerCaseString> field_key_names_;
8189

8290
Stats::ScopeSharedPtr stats_scope_;
8391
Stats::StatNameSetPtr stat_name_set_;
@@ -172,6 +180,9 @@ class GeoipProvider : public Envoy::Geolocation::Driver,
172180

173181
// Envoy::Geolocation::Driver
174182
void lookup(Geolocation::LookupRequest&&, Geolocation::LookupGeoHeadersCallback&&) const override;
183+
absl::Span<const Http::LowerCaseString> geoHeaderNames() const override {
184+
return config_->fieldKeyNames();
185+
}
175186

176187
private:
177188
// Allow the unit test to have access to private members.

0 commit comments

Comments
 (0)