docs: mark matching API and related features as alpha

api/STYLE.md

@@ -34,6 +34,10 @@ In addition, the following conventions should be followed:
   implementation. These indicate that the entity is not implemented in Envoy and the entity
   should be hidden from the Envoy documentation.
 
+* Use a `[#experimental:]` annotation in comments for messages that are considered experimental
+  and are not subject to the threat model. This differs from the work-in-progress/alpha tagging
+  of extensions in that in can be applied to configuration within the core API.
+
 * Always use plural field names for `repeated` fields, such as `filters`.
 
 * Due to the fact that we consider JSON/YAML to be first class inputs, we cannot easily change a

api/envoy/config/common/matcher/v3/matcher.proto

@@ -22,7 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // As an on_no_match might result in another matching tree being evaluated, this process
 // might repeat several times until the final OnMatch (or no match) is decided.
 //
-// This API is a work in progress.
+// [#experimental:]
 message Matcher {
   // What to do if a match is successful.
   message OnMatch {

api/envoy/extensions/common/matching/v3/extension_matcher.proto

@@ -18,6 +18,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // Wrapper around an existing extension that provides an associated matcher. This allows
 // decorating an existing extension with a matcher, which can be used to match against
 // relevant protocol data.
+//
+// [#experimental:]
 message ExtensionWithMatcher {
   // The associated matcher.
   config.common.matcher.v3.Matcher matcher = 1 [(validate.rules).message = {required: true}];

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

@@ -26,6 +26,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // :ref:`ExecuteFilterAction <envoy_api_msg_extensions.filters.http.composite.v3.ExecuteFilterAction>`)
 // which filter configuration to create and delegate to.
 //
+// [#experimental:]
 message Composite {
 }
 

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

@@ -3,6 +3,11 @@
 Composite Filter
 ================
 
+.. attention::
+
+   The composite filter is experimental and is currently under active development.
+   Capabilities will be expanded over time and the configuration structures are likely to change.
+
 The composite filter allows delegating filter actions to a filter specified by a
 :ref:`match result <arch_overview_matching_api>`. The purpose of this is to allow different filters
 or filter configurations to be selected based on the incoming request, allowing for more dynamic

docs/root/intro/arch_overview/advanced/matching/matching_api.rst

@@ -3,6 +3,11 @@
 Matching API
 ============
 
+.. attention::
+
+   The matching API is experimental and is currently under active development.
+   Capabilities will be expanded over time and the configuration structures are likely to change.
+
 Envoy makes use of a :ref:`matching API <envoy_v3_api_msg_config.common.matcher.v3.Matcher>`
 to allow the various subsystems to express actions that should be performed based on incoming data.
 

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

@@ -77,9 +77,11 @@ case, an extension will explicitly state this in its documentation.
 Core and extensions
 -------------------
 
-Anything in the Envoy core may be used in both untrusted and trusted deployments. As a consequence,
-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.
+Anything in the Envoy core may be used in both untrusted and trusted deployments, with the exception
+of features explicitly marked as experimental; experimental features are only supported in trusted deployments
+and do not qualify for treatment under the threat model below. As a consequence, the stable core 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 intended to be hardened against untrusted downstream and upstreams:
 

source/extensions/filters/http/composite/BUILD

@@ -46,7 +46,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     category = "envoy.filters.http",
-    security_posture = "robust_to_untrusted_downstream",
+    security_posture = "unknown",
     deps = [
         "//include/envoy/registry",
         "//include/envoy/server:filter_config_interface",

tools/api_proto_plugin/annotations.py

@@ -16,6 +16,9 @@
 # envoy.filters.network.http_connection_manager.
 EXTENSION_ANNOTATION = 'extension'
 
+# Used to mark something as experimental, excluding it from the security posture.
+EXPERIMENTAL_ANNOTATION = 'experimental'
+
 # Not implemented yet annotation on leading comments, leading to hiding of
 # field.
 NOT_IMPLEMENTED_HIDE_ANNOTATION = 'not-implemented-hide'
@@ -33,6 +36,7 @@
 VALID_ANNOTATIONS = set([
     DOC_TITLE_ANNOTATION,
     EXTENSION_ANNOTATION,
+    EXPERIMENTAL_ANNOTATION,
     EXTENSION_CATEGORY_ANNOTATION,
     NOT_IMPLEMENTED_HIDE_ANNOTATION,
     NEXT_FREE_FIELD_ANNOTATION,

tools/protodoc/protodoc.py

@@ -160,6 +160,12 @@ def format_comment_with_annotations(comment, type_name=''):
     Returns:
         A string with additional RST from annotations.
     """
+    experimental_warning = ''
+    if annotations.EXPERIMENTAL_ANNOTATION in comment.annotations:
+        experimental_warning = (
+            '.. warning::\n   This API is experimental and is not covered by the :ref:`threat model <arch_overview_threat_model>`.\n\n'
+        )
+
     formatted_extension = ''
     if annotations.EXTENSION_ANNOTATION in comment.annotations:
         extension = comment.annotations[annotations.EXTENSION_ANNOTATION]
@@ -169,7 +175,7 @@ def format_comment_with_annotations(comment, type_name=''):
         for category in comment.annotations[annotations.EXTENSION_CATEGORY_ANNOTATION].split(","):
             formatted_extension_category += format_extension_category(category)
     comment = annotations.without_annotations(strip_leading_space(comment.raw) + '\n')
-    return comment + formatted_extension + formatted_extension_category
+    return experimental_warning + comment + formatted_extension + formatted_extension_category
 
 
 def map_lines(f, s):