proxy_protocol_filter: Add configuration to match only specific proxy protocol versions, new stats

api/envoy/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto

@@ -70,4 +70,19 @@ message ProxyProtocol {
  // :ref:`core.v3.ProxyProtocolConfig.pass_through_tlvs <envoy_v3_api_field_config.core.v3.ProxyProtocolConfig.pass_through_tlvs>`,
  // which controls pass-through for the upstream.
  config.core.v3.ProxyProtocolPassThroughTLVs pass_through_tlvs = 3;
+
+ // The PROXY protocol versions that won't be matched. Useful to limit the scope and attack surface of the filter.
+ //
+ // When the filter receives PROXY protocol data that is disallowed, it will reject the connection.
+ // By default, the filter will match all PROXY protocol versions.
+ // See https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt for details.
+ //
+ // .. attention::
+ //
+ // When used in conjunction with the :ref:`allow_requests_without_proxy_protocol <envoy_v3_api_field_extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.allow_requests_without_proxy_protocol>`,
+ // the filter will not attempt to match signatures for the disallowed versions.
+ // For example, when ``disallowed_versions=V2``, ``allow_requests_without_proxy_protocol=true``,
+ // and an incoming request matches the V2 signature, the filter will allow the request through without any modification.
+ // The filter treats this request as if it did not have any PROXY protocol information.
+ repeated config.core.v3.ProxyProtocolConfig.Version disallowed_versions = 4;
 }

changelogs/current.yaml

@@ -373,6 +373,13 @@ new_features:
  change: |
  Added :ref:`formatters <envoy_v3_api_field_extensions.access_loggers.fluentd.v3.FluentdAccessLogConfig.formatters>`
  to Fluentd access logger to allow adding extension commands when formatter access logs.
+- area: proxy_protocol
+ change: |
+ Added :ref:`disallowed_versions <envoy_v3_api_field_extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.disallowed_versions>`
+ to enforce the filter only matches specific PROXY protocol versions.
+- area: proxy_protocol
+ change: |
+ Added new statistics to the proxy protocol filter to track connections found/disallowed/errored by PROXY protocol version.
 - area: rbac
  change: |
  Added :ref:`rules_stat_prefix <envoy_v3_api_field_extensions.filters.http.rbac.v3.RBAC.rules_stat_prefix>`

docs/root/configuration/listeners/listener_filters/proxy_protocol.rst

@@ -16,9 +16,13 @@ the TLV will be emitted as dynamic metadata with user-specified key.
 
 This implementation supports both version 1 and version 2, it
 automatically determines on a per-connection basis which of the two
-versions is present. Note: if the filter is enabled, the Proxy Protocol
-must be present on the connection (either version 1 or version 2),
-the standard does not allow parsing to determine if it is present or not.
+versions is present.
+
+.. note::
+ If the filter is enabled, the Proxy Protocol must be present on the connection (either version 1 or version 2).
+ The standard does not allow parsing to determine if it is present or not. However, the filter can be configured
+ to allow the connection to be accepted without the Proxy Protocol header (against the standard).
+ See :ref:`allow_requests_without_proxy_protocol <envoy_v3_api_field_extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.allow_requests_without_proxy_protocol>`.
 
 If there is a protocol error or an unsupported address family
 (e.g. AF_UNIX) the connection will be closed and an error thrown.
@@ -29,10 +33,33 @@ If there is a protocol error or an unsupported address family
 Statistics
 ----------
 
-This filter emits the following statistics:
+This filter emits the following general statistics, rooted at *downstream_proxy_proto*
+
+.. csv-table::
+ :header: Name, Type, Description
+ :widths: 4, 1, 8
+
+ not_found_disallowed, Counter, "Total number of connections that don't contain the PROXY protocol header and are rejected."
+ not_found_allowed, Counter, "Total number of connections that don't contain the PROXY protocol header, but are allowed due to :ref:`allow_requests_without_proxy_protocol <envoy_v3_api_field_extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.allow_requests_without_proxy_protocol>`."
+
+The filter also emits the statistics rooted at *downstream_proxy_proto.versions.<version>*
+for each matched PROXY protocol version. Proxy protocol versions include ``v1`` and ``v2``.
 
 .. csv-table::
  :header: Name, Type, Description
- :widths: 1, 1, 2
+ :widths: 4, 1, 8
+
+ found, Counter, "Total number of connections where the PROXY protocol header was found and parsed correctly."
+ disallowed, Counter, "Total number of ``found`` connections that are rejected due to :ref:`disallowed_versions <envoy_v3_api_field_extensions.filters.listener.proxy_protocol.v3.ProxyProtocol.disallowed_versions>`."
+ error, Counter, "Total number of connections where the PROXY protocol header was malformed (and the connection was rejected)."
+
+The filter also emits the following legacy statistics, rooted at its own scope:
+
+.. csv-table::
+ :header: Name, Type, Description
+ :widths: 4, 1, 8
+
+ downstream_cx_proxy_proto_error, Counter, "Total number of connections with proxy protocol errors, i.e. ``v1.error``, ``v2.error``, and ``not_found_disallowed``."
 
- downstream_cx_proxy_proto_error, Counter, Total proxy protocol errors
+.. attention::
+ Prefer using the more-detailed non-legacy statistics above.

source/common/config/well_known_names.cc

@@ -211,6 +211,9 @@ TagNameValues::TagNameValues() {
 
  // http.<stat_prefix>.rbac.(<rules_stat_prefix>.)*
  addTokenized(RBAC_HTTP_PREFIX, "http.*.rbac.$.**");
+
+ // downstream_proxy_proto.versions.(<version>).**
+ addTokenized(PROXY_PROTOCOL_VERSION, "downstream_proxy_proto.versions.$.**");
 }
 
 void TagNameValues::addRe2(const std::string& name, const std::string& regex,

source/common/config/well_known_names.h

@@ -161,6 +161,8 @@ class TagNameValues {
  const std::string THRIFT_PREFIX = "envoy.thrift_prefix";
  // Stats prefix for the Redis Proxy network filter
  const std::string REDIS_PREFIX = "envoy.redis_prefix";
+ // Proxy Protocol version for a connection (Proxy Protocol listener filter).
+ const std::string PROXY_PROTOCOL_VERSION = "envoy.proxy_protocol_version";
 
  // Mapping from the names above to their respective regex strings.
  const std::vector<std::pair<std::string, std::string>> name_regex_pairs_;

source/extensions/filters/listener/proxy_protocol/proxy_protocol.cc

@@ -13,6 +13,7 @@
 #include "envoy/event/dispatcher.h"
 #include "envoy/network/listen_socket.h"
 #include "envoy/stats/scope.h"
+#include "envoy/stats/stats_macros.h"
 
 #include "source/common/api/os_sys_calls_impl.h"
 #include "source/common/common/assert.h"
@@ -27,6 +28,7 @@
 #include "source/common/protobuf/utility.h"
 #include "source/extensions/common/proxy_protocol/proxy_protocol_header.h"
 
+using envoy::config::core::v3::ProxyProtocolConfig;
 using envoy::config::core::v3::ProxyProtocolPassThroughTLVs;
 using Envoy::Extensions::Common::ProxyProtocol::PROXY_PROTO_V1_SIGNATURE;
 using Envoy::Extensions::Common::ProxyProtocol::PROXY_PROTO_V1_SIGNATURE_LEN;
@@ -48,10 +50,60 @@ namespace Extensions {
 namespace ListenerFilters {
 namespace ProxyProtocol {
 
+constexpr absl::string_view kProxyProtoStatsPrefix = "downstream_proxy_proto.";
+constexpr absl::string_view kVersionStatsPrefix = "versions.";
+
+ProxyProtocolStats ProxyProtocolStats::create(Stats::Scope& scope) {
+ return {
+ /*legacy_=*/{LEGACY_PROXY_PROTOCOL_STATS(POOL_COUNTER(scope))},
+ /*general_=*/
+ {GENERAL_PROXY_PROTOCOL_STATS(POOL_COUNTER_PREFIX(scope, kProxyProtoStatsPrefix))},
+ /*v1_=*/
+ {VERSIONED_PROXY_PROTOCOL_STATS(POOL_COUNTER_PREFIX(
+ scope, absl::StrCat(kProxyProtoStatsPrefix, kVersionStatsPrefix, "v1.")))},
+ /*v2_=*/
+ {VERSIONED_PROXY_PROTOCOL_STATS(POOL_COUNTER_PREFIX(
+ scope, absl::StrCat(kProxyProtoStatsPrefix, kVersionStatsPrefix, "v2.")))},
+ };
+}
+
+void GeneralProxyProtocolStats::increment(ReadOrParseState decision) {
+ switch (decision) {
+ case ReadOrParseState::Done:
+ not_found_allowed_.inc();
+ break;
+ case ReadOrParseState::TryAgainLater:
+ break; // Do nothing.
+ case ReadOrParseState::Error:
+ not_found_disallowed_.inc();
+ break;
+ case ReadOrParseState::Denied:
+ IS_ENVOY_BUG("ReadOrParseState can never be Denied when proxy protocol is not found");
+ break;
+ }
+}
+
+void VersionedProxyProtocolStats::increment(ReadOrParseState decision) {
+ switch (decision) {
+ case ReadOrParseState::Done:
+ found_.inc();
+ break;
+ case ReadOrParseState::TryAgainLater:
+ break; // Do nothing.
+ case ReadOrParseState::Error:
+ error_.inc();
+ break;
+ case ReadOrParseState::Denied:
+ found_.inc();
+ disallowed_.inc();
+ break;
+ }
+}
+
 Config::Config(
  Stats::Scope& scope,
  const envoy::extensions::filters::listener::proxy_protocol::v3::ProxyProtocol& proto_config)
- : stats_{ALL_PROXY_PROTOCOL_STATS(POOL_COUNTER(scope))},
+ : stats_(ProxyProtocolStats::create(scope)),
  allow_requests_without_proxy_protocol_(proto_config.allow_requests_without_proxy_protocol()),
  pass_all_tlvs_(proto_config.has_pass_through_tlvs()
  ? proto_config.pass_through_tlvs().match_type() ==
@@ -67,6 +119,24 @@ Config::Config(
  pass_through_tlvs_.insert(0xFF & tlv_type);
  }
  }
+
+ for (const auto& version : proto_config.disallowed_versions()) {
+ switch (version) {
+ PANIC_ON_PROTO_ENUM_SENTINEL_VALUES;
+ case ProxyProtocolConfig::V1:
+ allow_v1_ = false;
+ break;
+ case ProxyProtocolConfig::V2:
+ allow_v2_ = false;
+ break;
+ }
+ }
+
+ // Remove this check if PROXY protocol v3 is ever introduced.
+ if (!allow_v1_ && !allow_v2_) {
+ throw ProtoValidationException(
+ "Proxy Protocol filter is misconfigured: all proxy protocol versions are disallowed.");
+ }
 }
 
 const KeyValuePair* Config::isTlvTypeNeeded(uint8_t type) const {
@@ -91,6 +161,10 @@ bool Config::allowRequestsWithoutProxyProtocol() const {
  return allow_requests_without_proxy_protocol_;
 }
 
+bool Config::isVersionV1Allowed() const { return allow_v1_; }
+
+bool Config::isVersionV2Allowed() const { return allow_v2_; }
+
 Network::FilterStatus Filter::onAccept(Network::ListenerFilterCallbacks& cb) {
  ENVOY_LOG(debug, "proxy_protocol: New connection accepted");
  cb_ = &cb;
@@ -99,16 +173,31 @@ Network::FilterStatus Filter::onAccept(Network::ListenerFilterCallbacks& cb) {
 }
 
 Network::FilterStatus Filter::onData(Network::ListenerFilterBuffer& buffer) {
- const ReadOrParseState read_state = parseBuffer(buffer);
+ const ReadOrParseState read_state = parseBuffer(buffer); // Implicitly updates header_version_
+
+ switch (header_version_) {
+ case ProxyProtocolVersion::V1:
+ config_->stats_.v1_.increment(read_state);
+ break;
+ case ProxyProtocolVersion::V2:
+ config_->stats_.v2_.increment(read_state);
+ break;
+ case ProxyProtocolVersion::NotFound:
+ config_->stats_.general_.increment(read_state);
+ break;
+ }
+
  switch (read_state) {
+ case ReadOrParseState::Denied:
+ cb_->socket().ioHandle().close();
+ return Network::FilterStatus::StopIteration;
  case ReadOrParseState::Error:
- config_->stats_.downstream_cx_proxy_proto_error_.inc();
+ config_->stats_.legacy_.downstream_cx_proxy_proto_error_
+ .inc(); // Keep for backwards-compatibility
  cb_->socket().ioHandle().close();
  return Network::FilterStatus::StopIteration;
  case ReadOrParseState::TryAgainLater:
  return Network::FilterStatus::StopIteration;
- case ReadOrParseState::SkipFilter:
- return Network::FilterStatus::Continue;
  case ReadOrParseState::Done:
  return Network::FilterStatus::Continue;
  }
@@ -125,6 +214,10 @@ ReadOrParseState Filter::parseBuffer(Network::ListenerFilterBuffer& buffer) {
  if (read_header_state != ReadOrParseState::Done) {
  return read_header_state;
  }
+ if (header_version_ == ProxyProtocolVersion::NotFound) {
+ // Filter is skipped and request is allowed through.
+ return ReadOrParseState::Done;
+ }
  }
 
  // After parse the header, the extensions size is discovered. Then extend the buffer
@@ -497,31 +590,37 @@ ReadOrParseState Filter::readProxyHeader(Network::ListenerFilterBuffer& buffer)
  auto raw_slice = buffer.rawSlice();
  const char* buf = static_cast<const char*>(raw_slice.mem_);
 
- if (config_.get()->allowRequestsWithoutProxyProtocol()) {
- auto matchv2 = !memcmp(buf, PROXY_PROTO_V2_SIGNATURE,
+ if (config_->allowRequestsWithoutProxyProtocol()) {
+ auto matchv2 = config_->isVersionV2Allowed() &&
+ !memcmp(buf, PROXY_PROTO_V2_SIGNATURE,
  std::min<size_t>(PROXY_PROTO_V2_SIGNATURE_LEN, raw_slice.len_));
- auto matchv1 = !memcmp(buf, PROXY_PROTO_V1_SIGNATURE,
+ auto matchv1 = config_->isVersionV1Allowed() &&
+ !memcmp(buf, PROXY_PROTO_V1_SIGNATURE,
  std::min<size_t>(PROXY_PROTO_V1_SIGNATURE_LEN, raw_slice.len_));
  if (!matchv2 && !matchv1) {
  // The bytes we have seen so far do not match v1 or v2 proxy protocol, so we can safely
  // short-circuit
  ENVOY_LOG(trace, "request does not use v1 or v2 proxy protocol, forwarding as is");
- return ReadOrParseState::SkipFilter;
+ return ReadOrParseState::Done;
  }
  }
 
  if (raw_slice.len_ >= PROXY_PROTO_V2_HEADER_LEN) {
  const char* sig = PROXY_PROTO_V2_SIGNATURE;
  if (!memcmp(buf, sig, PROXY_PROTO_V2_SIGNATURE_LEN)) {
- header_version_ = V2;
+ header_version_ = ProxyProtocolVersion::V2;
  } else if (memcmp(buf, PROXY_PROTO_V1_SIGNATURE, PROXY_PROTO_V1_SIGNATURE_LEN)) {
  // It is not v2, and can't be v1, so no sense hanging around: it is invalid
  ENVOY_LOG(debug, "failed to read proxy protocol (exceed max v1 header len)");
  return ReadOrParseState::Error;
  }
  }
 
- if (header_version_ == V2) {
+ if (header_version_ == ProxyProtocolVersion::V2) {
+ if (!config_->isVersionV2Allowed()) {
+ ENVOY_LOG(trace, "Filter is not configured to allow v2 proxy protocol requests");
+ return ReadOrParseState::Denied;
+ }
  const int ver_cmd = buf[PROXY_PROTO_V2_SIGNATURE_LEN];
  if (((ver_cmd & 0xf0) >> 4) != PROXY_PROTO_V2_VERSION) {
  ENVOY_LOG(debug, "Unsupported V2 proxy protocol version");
@@ -560,7 +659,7 @@ ReadOrParseState Filter::readProxyHeader(Network::ListenerFilterBuffer& buffer)
  // for more data.
  break;
  } else {
- header_version_ = V1;
+ header_version_ = ProxyProtocolVersion::V1;
  search_index_++;
  }
  break;
@@ -571,7 +670,11 @@ ReadOrParseState Filter::readProxyHeader(Network::ListenerFilterBuffer& buffer)
  return ReadOrParseState::Error;
  }
 
- if (header_version_ == V1) {
+ if (header_version_ == ProxyProtocolVersion::V1) {
+ if (!config_->isVersionV1Allowed()) {
+ ENVOY_LOG(trace, "Filter is not configured to allow v1 proxy protocol requests");
+ return ReadOrParseState::Denied;
+ }
  if (parseV1Header(buf, search_index_)) {
  return ReadOrParseState::Done;
  } else {