diff --git a/src/changelog/.2.x.x/4181_routing_appender_security_docs.xml b/src/changelog/.2.x.x/4181_routing_appender_security_docs.xml new file mode 100644 index 00000000000..acd8bb3e3b1 --- /dev/null +++ b/src/changelog/.2.x.x/4181_routing_appender_security_docs.xml @@ -0,0 +1,8 @@ + + + + Document security considerations for high-cardinality keys with the `Routing` Appender + diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc index 6076fafa71d..a8a166e6966 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc @@ -945,6 +945,25 @@ If the `Route` element contains an appender definition, the appender will be ins * once for each value of the key, if the `Route` has the default key. ==== +[#RoutingAppender-security] +=== Security considerations + +When a default <> embeds an appender definition, the `Routing` Appender creates **one subordinate appender per distinct routing key value**. +If the key is derived from untrusted or high-cardinality data (for example `${ctx:userId}`, a client IP, or a free-form request header), an attacker or a busy system can force creation of an unbounded number of appenders. + +That growth commonly leads to: + +* exhaustion of file descriptors (when each route opens a `File` or rolling file appender) +* elevated memory use for appender state, buffers, and managers +* difficulty shutting down or reconfiguring the application cleanly + +Mitigations: + +* Prefer <> to a fixed, predeclared set of appenders when the set of destinations is known. +* When dynamic routes are required, always configure a <> (typically <>) so idle route appenders are stopped and released. +* Constrain routing keys to a low-cardinality, validated domain (allow-lists, enums, hashed buckets) instead of raw user input. +* Avoid routing on pure user-controlled identifiers when each value would create a new file-backed appender. + [#PurgePolicy] === Purge Policy