From 9259e58dee894a04211b1a43a137a24e4050471b Mon Sep 17 00:00:00 2001
From: Sebastien Tardif <sebtardif@ncf.ca>
Date: Sat, 25 Jul 2026 07:32:23 -0400
Subject: [PATCH] docs: add Routing Appender security considerations for
 high-cardinality keys

Document that default Route appender definitions create one appender per
routing key value, which can exhaust file descriptors when the key is
untrusted or high-cardinality. Recommend purge policies and low-cardinality
keys.

Fixes #4181

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>
---
 .../4181_routing_appender_security_docs.xml   |  8 ++++++++
 .../pages/manual/appenders/delegating.adoc    | 19 +++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 src/changelog/.2.x.x/4181_routing_appender_security_docs.xml

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 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns="https://logging.apache.org/xml/ns"
+       xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
+       type="fixed">
+  <issue id="4181" link="https://github.com/apache/logging-log4j2/issues/4181"/>
+  <description format="asciidoc">Document security considerations for high-cardinality keys with the `Routing` Appender</description>
+</entry>
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 <<Route,`Route`>> 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 <<Route-element-AppenderRef,appender references>> to a fixed, predeclared set of appenders when the set of destinations is known.
+* When dynamic routes are required, always configure a <<PurgePolicy,`PurgePolicy`>> (typically <<IdlePurgePolicy,`IdlePurgePolicy`>>) 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