security: document threat model.

bazel/envoy_library.bzl

@@ -43,22 +43,37 @@ EXTENSION_SECURITY_POSTURES = [
     # This extension is not hardened and should only be used in deployments
     # where both the downstream and upstream are trusted.
     "requires_trusted_downstream_and_upstream",
-    # This is functionally equivaelnt to
+    # This is functionally equivalent to
     # requires_trusted_downstream_and_upstream, but acts as a placeholder to
     # allow us to identify extensions that need classifying.
     "unknown",
+    # Not relevant to data plane threats, e.g. stats sinks.
+    "data_plane_agnostic",
+]
+
+EXTENSION_STATUS_VALUES = [
+    # This extension is stable and is expected to be production usable.
+    "stable",
+    # This extension is functional but has not had substantial production burn
+    # time, use only with this caveat.
+    "alpha",
+    # This extension is work-in-progress. Functionality is incomplete and it is
+    # not intended for production use.
+    "wip",
 ]
 
 def envoy_cc_extension(
         name,
         security_posture,
         # Only set this for internal, undocumented extensions.
         undocumented = False,
+        status = "stable",
         tags = [],
         **kwargs):
     if security_posture not in EXTENSION_SECURITY_POSTURES:
         fail("Unknown extension security posture: " + security_posture)
-    tags = tags + ["secpos:" + security_posture]
+    if status not in EXTENSION_STATUS_VALUES:
+        fail("Unknown extension status: " + status)
     envoy_cc_library(name, tags = tags, **kwargs)
 
 # Envoy C++ library targets should be specified with this function.

docs/build.sh

@@ -46,8 +46,6 @@ mkdir -p "${GENERATED_RST_DIR}"
 source_venv "$BUILD_DIR"
 pip3 install -r "${SCRIPT_DIR}"/requirements.txt
 
-# Generate extension trust profile
-
 # Clean up any stale files in the API tree output. Bazel remembers valid cached
 # files still.
 rm -rf bazel-bin/external/envoy_api

docs/generate_extension_db.py

@@ -29,16 +29,22 @@ class ExtensionDbError(Exception):
   pass
 
 
+def IsMissing(value):
+  return value == '(missing)'
+
+
 def GetExtensionMetadata(target):
-  r = subprocess.run([BUILDOZER_PATH, '-stdout', 'print security_posture undocumented', target],
-                     stdout=subprocess.PIPE,
-                     stderr=subprocess.PIPE)
-  security_posture, undocumented = r.stdout.decode('utf-8').strip().split(' ')
-  if security_posture == '(missing)':
+  r = subprocess.run(
+      [BUILDOZER_PATH, '-stdout', 'print security_posture status undocumented', target],
+      stdout=subprocess.PIPE,
+      stderr=subprocess.PIPE)
+  security_posture, status, undocumented = r.stdout.decode('utf-8').strip().split(' ')
+  if IsMissing(security_posture):
     raise ExtensionDbError('Missing security posture for %s' % target)
   return {
       'security_posture': security_posture,
-      'undocumented': bool(undocumented) if undocumented != '(missing)' else False
+      'undocumented': False if IsMissing(undocumented) else bool(undocumented),
+      'status': 'stable' if IsMissing(status) else status,
   }
 
 

docs/generate_extension_rst.py

@@ -9,7 +9,7 @@
 
 
 def FormatItem(extension, metadata):
-  if metadata['undocumented']:
+  if metadata['undocumented'] or metadata['status'] == 'wip':
     return '* %s' % extension
   return '* :ref:`%s <extension_%s>`' % (extension, extension)
 
@@ -25,5 +25,6 @@ def FormatItem(extension, metadata):
 
   for sp, extensions in security_postures.items():
     output_path = pathlib.Path(security_rst_root, 'secpos_%s.rst' % sp)
-    content = '\n'.join(FormatItem(extension, extension_db[extension]) for extension in extensions)
+    content = '\n'.join(
+        FormatItem(extension, extension_db[extension]) for extension in sorted(extensions))
     output_path.write_text(content)

docs/root/intro/arch_overview/security/threat_model.rst

@@ -7,7 +7,6 @@ Below we articulate the Envoy threat model, which is of relevance to Envoy opera
 security researchers. We detail our security release process at
 https://github.com/envoyproxy/envoy/security/policy.
 
-
 Confidentiality, integrity and availability
 -------------------------------------------
 
@@ -28,12 +27,12 @@ hardening status quo. Examples of disclosures that would elicit this response:
   e.g. that delivered by a single client.
 
 Note that we do not currently consider the default settings for Envoy to be safe from an availability
-perspective. It is necessary for operators to explicitly configure watermarks, the overload manager,
-circuit breakers and other resource related features in Envoy to provide a robust availability
-story. We will not act on any security disclosure that relates to a lack of safe defaults. Over
-time, we will work towards improved safe-by-default configuration, but due to backwards
-compatibility and performance concerns, this will require following the breaking change deprecation
-policy.
+perspective. It is necessary for operators to explicitly :ref:`configure <best_practices_edge>`
+watermarks, the overload manager, circuit breakers and other resource related features in Envoy to
+provide a robust availability story. We will not act on any security disclosure that relates to a
+lack of safe defaults. Over time, we will work towards improved safe-by-default configuration, but
+due to backwards compatibility and performance concerns, this will require following the breaking
+change deprecation policy.
 
 Data and control plane
 ----------------------
@@ -69,11 +68,16 @@ Anything in the Envoy core may be used in both untrusted and trusted deployments
 it should be hardened with this model in mind. Security issues related to core code will usually
 trigger the security release process as described in this document.
 
-The following extensions are considered hardened against untrusted downstream and upstreams:
+The following extensions are intended to be hardened against untrusted downstream and upstreams:
 
 .. include:: secpos_robust_to_untrusted_downstream_and_upstream.rst
 
-The following extensions are considered hardened against untrusted downstreams but assume trusted
+The following extensions should not be exposed to data plane attack vectors and hence are intended
+to be robust to untrusted downstreams and upstreams:
+
+.. include:: secpos_data_plane_agnostic.rst
+
+The following extensions are intended to be hardened against untrusted downstreams but assume trusted
 upstreams:
 
 .. include:: secpos_robust_to_untrusted_downstream.rst
@@ -82,6 +86,7 @@ The following extensions should only be used when both the downstream and upstre
 
 .. include:: secpos_requires_trusted_downstream_and_upstream.rst
 
+
 The following extensions have an unknown security posture:
 
 .. include:: secpos_unknown.rst

source/extensions/clusters/redis/BUILD

@@ -43,7 +43,7 @@ envoy_cc_extension(
         "redis_cluster.cc",
         "redis_cluster.h",
     ],
-    security_posture = "robust_to_untrusted_downstream",
+    security_posture = "requires_trusted_downstream_and_upstream",
     deps = [
         "redis_cluster_lb",
         "//include/envoy/api:api_interface",

source/extensions/extensions_build_config.bzl

@@ -80,8 +80,8 @@ EXTENSIONS = {
     "envoy.filters.network.echo":                       "//source/extensions/filters/network/echo:config",
     "envoy.filters.network.ext_authz":                  "//source/extensions/filters/network/ext_authz:config",
     "envoy.filters.network.http_connection_manager":    "//source/extensions/filters/network/http_connection_manager:config",
-    # Not implemented yet
-    #"envoy.filters.network.kafka":                      "//source/extensions/filters/network/kafka:kafka_request_codec_lib",
+    # WiP
+    "envoy.filters.network.kafka":                      "//source/extensions/filters/network/kafka:kafka_request_codec_lib",
     "envoy.filters.network.mongo_proxy":                "//source/extensions/filters/network/mongo_proxy:config",
     "envoy.filters.network.mysql_proxy":                "//source/extensions/filters/network/mysql_proxy:config",
     "envoy.filters.network.ratelimit":                  "//source/extensions/filters/network/ratelimit:config",
@@ -124,8 +124,8 @@ EXTENSIONS = {
     "envoy.tracers.datadog":                            "//source/extensions/tracers/datadog:config",
     "envoy.tracers.zipkin":                             "//source/extensions/tracers/zipkin:config",
     "envoy.tracers.opencensus":                         "//source/extensions/tracers/opencensus:config",
-    # Not implemented yet
-    #"envoy.tracers.xray":                               "//source/extensions/tracers/xray:config",
+    # WiP
+    "envoy.tracers.xray":                               "//source/extensions/tracers/xray:config",
 
     #
     # Transport sockets

source/extensions/filters/http/adaptive_concurrency/BUILD

@@ -31,6 +31,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "unknown",
+    status = "alpha",
     deps = [
         "//include/envoy/registry",
         "//source/extensions/filters/http:well_known_names",

source/extensions/filters/http/dynamic_forward_proxy/BUILD

@@ -27,6 +27,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "robust_to_untrusted_downstream",
+    status = "alpha",
     deps = [
         "//include/envoy/registry",
         "//include/envoy/server:filter_config_interface",

source/extensions/filters/http/ext_authz/BUILD

@@ -39,7 +39,7 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "unknown",
+    security_posture = "robust_to_untrusted_downstream",
     deps = [
         ":ext_authz",
         "//include/envoy/registry",

source/extensions/filters/http/fault/BUILD

@@ -44,7 +44,7 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "unknown",
+    security_posture = "robust_to_untrusted_downstream",
     deps = [
         "//include/envoy/registry",
         "//source/extensions/filters/http:well_known_names",

source/extensions/filters/http/grpc_http1_reverse_bridge/BUILD

@@ -32,6 +32,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "unknown",
+    status = "alpha",
     deps = [
         ":filter_lib",
         "//include/envoy/http:filter_interface",

source/extensions/filters/http/grpc_stats/BUILD

@@ -15,6 +15,7 @@ envoy_cc_extension(
     srcs = ["grpc_stats_filter.cc"],
     hdrs = ["grpc_stats_filter.h"],
     security_posture = "unknown",
+    status = "alpha",
     deps = [
         "//include/envoy/registry",
         "//include/envoy/server:filter_config_interface",

source/extensions/filters/http/jwt_authn/BUILD

@@ -69,6 +69,7 @@ envoy_cc_extension(
     srcs = ["filter_factory.cc"],
     hdrs = ["filter_factory.h"],
     security_posture = "robust_to_untrusted_downstream",
+    status = "alpha",
     deps = [
         ":filter_lib",
         "//include/envoy/registry",

source/extensions/filters/http/original_src/BUILD

@@ -38,6 +38,7 @@ envoy_cc_extension(
     srcs = ["original_src_config_factory.cc"],
     hdrs = ["original_src_config_factory.h"],
     security_posture = "robust_to_untrusted_downstream",
+    status = "alpha",
     deps = [
         ":config_lib",
         ":original_src_lib",

source/extensions/filters/http/router/BUILD

@@ -15,7 +15,7 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "unknown",
+    security_posture = "robust_to_untrusted_downstream",
     deps = [
         "//include/envoy/registry",
         "//source/common/router:router_lib",

source/extensions/filters/http/squash/BUILD

@@ -36,7 +36,7 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "robust_to_untrusted_downstream",
+    security_posture = "requires_trusted_downstream_and_upstream",
     deps = [
         "//include/envoy/registry",
         "//source/common/protobuf:utility_lib",

source/extensions/filters/http/tap/BUILD

@@ -52,6 +52,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":tap_config_impl",
         ":tap_filter_lib",

source/extensions/filters/listener/original_src/BUILD

@@ -41,6 +41,7 @@ envoy_cc_extension(
     srcs = ["original_src_config_factory.cc"],
     hdrs = ["original_src_config_factory.h"],
     security_posture = "robust_to_untrusted_downstream",
+    status = "alpha",
     deps = [
         ":config_lib",
         ":original_src_lib",

source/extensions/filters/listener/proxy_protocol/BUILD

@@ -35,7 +35,7 @@ envoy_cc_library(
 envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
-    security_posture = "unknown",
+    security_posture = "robust_to_untrusted_downstream",
     deps = [
         "//include/envoy/registry",
         "//include/envoy/server:filter_config_interface",

source/extensions/filters/network/client_ssl_auth/BUILD

@@ -40,7 +40,7 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "unknown",
+    security_posture = "robust_to_untrusted_downstream",
     deps = [
         ":client_ssl_auth",
         "//include/envoy/registry",

source/extensions/filters/network/dubbo_proxy/BUILD

@@ -105,6 +105,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":conn_manager_lib",
         "//include/envoy/registry",

source/extensions/filters/network/kafka/BUILD

@@ -30,6 +30,7 @@ envoy_cc_extension(
         "request_codec.h",
     ],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "wip",
     deps = [
         ":abstract_codec_lib",
         ":kafka_request_parser_lib",

source/extensions/filters/network/mysql_proxy/BUILD

@@ -53,6 +53,7 @@ envoy_cc_extension(
     srcs = ["mysql_config.cc"],
     hdrs = ["mysql_config.h"],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":proxy_lib",
         "//source/extensions/filters/network:well_known_names",

source/extensions/filters/network/ratelimit/BUILD

@@ -32,7 +32,7 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "unknown",
+    security_posture = "robust_to_untrusted_downstream",
     deps = [
         "//include/envoy/registry",
         "//source/common/protobuf:utility_lib",

source/extensions/filters/network/thrift_proxy/BUILD

@@ -36,6 +36,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":app_exception_lib",
         ":auto_protocol_lib",

source/extensions/filters/network/thrift_proxy/filters/ratelimit/BUILD

@@ -31,7 +31,8 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "unknown",
+    security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":ratelimit_lib",
         "//include/envoy/registry",

source/extensions/filters/network/thrift_proxy/router/BUILD

@@ -14,6 +14,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":router_lib",
         "//include/envoy/registry",

source/extensions/filters/network/zookeeper_proxy/BUILD

@@ -43,6 +43,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     security_posture = "requires_trusted_downstream_and_upstream",
+    status = "alpha",
     deps = [
         ":proxy_lib",
         "//source/extensions/filters/network:well_known_names",

source/extensions/grpc_credentials/aws_iam/BUILD

@@ -15,7 +15,8 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     external_deps = ["grpc"],
-    security_posture = "unknown",
+    security_posture = "data_plane_agnostic",
+    status = "alpha",
     deps = [
         "//include/envoy/grpc:google_grpc_creds_interface",
         "//include/envoy/registry",

source/extensions/grpc_credentials/file_based_metadata/BUILD

@@ -15,7 +15,8 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     external_deps = ["grpc"],
-    security_posture = "robust_to_untrusted_downstream",
+    security_posture = "data_plane_agnostic",
+    status = "alpha",
     deps = [
         "//include/envoy/grpc:google_grpc_creds_interface",
         "//include/envoy/registry",

source/extensions/resource_monitors/fixed_heap/BUILD

@@ -25,7 +25,8 @@ envoy_cc_extension(
     name = "config",
     srcs = ["config.cc"],
     hdrs = ["config.h"],
-    security_posture = "robust_to_untrusted_downstream",
+    security_posture = "data_plane_agnostic",
+    status = "alpha",
     deps = [
         ":fixed_heap_monitor",
         "//include/envoy/registry",