This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/logging-site.git
The following commit(s) were added to refs/heads/main by this push:
new 5b84615b Add Security FAQ (#21)
5b84615b is described below
commit 5b84615bcd0b584ea4a9d1edc6c29017e968d970
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Wed Mar 25 20:39:29 2026 +0100
Add Security FAQ (#21)
* Add Security FAQ
Adds a Security FAQ documenting behaviors that are frequently reported as
vulnerabilities but fall outside our threat model.
This serves two purposes:
- **User guidance**: share clear recommendations on security considerations
when using certain formats and protocols.
- **Triage efficiency**: reduce duplicate reports and provide
well-reasoned, consistent responses to those that do come in.
* fix: add Path Traversal section
Adds a section on path traversal.
Co-authored-by: Jan Friedrich <[email protected]>
---
src/site/antora/modules/ROOT/nav.adoc | 1 +
src/site/antora/modules/ROOT/pages/security.adoc | 5 +
.../antora/modules/ROOT/pages/security/faq.adoc | 166 +++++++++++++++++++++
3 files changed, 172 insertions(+)
diff --git a/src/site/antora/modules/ROOT/nav.adoc
b/src/site/antora/modules/ROOT/nav.adoc
index 36e5afbe..598ddf20 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -26,6 +26,7 @@
* xref:download.adoc[]
* xref:support.adoc[]
* xref:security.adoc[]
+** xref:security/faq.adoc[FAQ]
* xref:xml/ns/index.adoc[XML Schema]
* xref:blog/index.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/security.adoc
b/src/site/antora/modules/ROOT/pages/security.adoc
index b7e631dc..662c3925 100644
--- a/src/site/antora/modules/ROOT/pages/security.adoc
+++ b/src/site/antora/modules/ROOT/pages/security.adoc
@@ -45,6 +45,11 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
====
We urge you to **carefully read the threat model** detailed in following
sections before submitting a report.
It guides users on certain safety instructions while using Logging Services
software and elaborates on what counts as an unexpected behaviour that has a
security impact.
+
+Before reporting a vulnerability, please make sure to check:
+
+- The xref:security/faq.adoc[FAQ] for frequently reported issues that are not
considered vulnerabilities.
+- The list of xref:security.adoc#vulnerabilities[known vulnerabilities] to
check if the issue has already been reported.
====
include::_threat-model-common.adoc[leveloffset=+1]
diff --git a/src/site/antora/modules/ROOT/pages/security/faq.adoc
b/src/site/antora/modules/ROOT/pages/security/faq.adoc
new file mode 100644
index 00000000..05f5e5a5
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/security/faq.adoc
@@ -0,0 +1,166 @@
+////
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+////
+
+= Frequently Reported Vulnerabilities
+
+This page documents issues that are **frequently reported** in Logging
Services software but are **not considered vulnerabilities** according to our
xref:security.adoc#threat-model[threat model].
+
+These reports often stem from valid concerns in specific contexts, but reflect
common misunderstandings about how logging systems are designed to operate and
what security guarantees they provide.
+
+The goal of this FAQ is to:
+
+* Clarify common misconceptions
+* Explain why these reports fall outside our threat model
+* Help you make informed decisions when configuring logging
+
+[NOTE]
+====
+This document is not intended to dismiss security concerns, but to provide
context and guidance.
+Depending on your environment, some of these topics may still warrant
**defensive configuration**.
+====
+
+[#crlf-injection]
+== https://cwe.mitre.org/data/definitions/93.html[CWE-93: CRLF Injection]
+
+Apache Logging Services libraries (Log4cxx, Log4j, and Log4net) allow users to
customize log output through a variety of layouts.
+A frequently reported issue is that CR (`\r`) and LF (`\n`) characters present
in a log event can appear in the output,
+making it difficult to reliably delimit individual events when parsing.
+
+In most configurations, this behavior is intentional and not considered a
vulnerability within the defined threat model.
+The sections below cover the layouts for which this has most commonly been
reported.
+
+[#crlf-injection-pattern-layout]
+=== Pattern layout
+
+**Claim**: Pattern layout is vulnerable to CRLF injection because it does not
escape CRLF characters.
+
+Pattern layout is an **unstructured** text format.
+It defines no fields, no delimiters, and no escaping rules, so it makes no
attempt to neutralize control characters, including CRLF sequences.
+This means:
+
+* Log output will contain CRLF characters if they are present in the input.
+* The layout itself provides **no output sanitization** guarantees.
+
+This behavior is by design and consistent with the layout's purpose.
+
+[#crlf-injection-pattern-layout-why-not]
+==== Why this is not a vulnerability
+
+CRLF injection is a concern only when both of the following conditions apply:
+
+* Log output is consumed as **structured data** (for example, by an ingestion
pipeline), _and_
+* Downstream consumers assume that the output has been sanitized.
+
+Pattern layout guarantees only formatting, not safety or parseability.
+Tools such as
https://www.elastic.co/docs/reference/enrich-processor/grok-processor[Grok] can
parse Pattern layout output automatically, but only when the output
consistently matches the expected pattern.
+Unescaped CRLF sequences can break that assumption.
+
+[IMPORTANT]
+====
+If your logs are consumed in any of these ways:
+
+* Parsed automatically by a downstream tool
+* Ingested into a structured storage or SIEM system
+* Used in security-sensitive workflows
+
+then **avoid Pattern layout** and use a **structured layout** instead, such as
JSON or RFC 5424.
+====
+
+[TIP]
+====
+If you must use Pattern layout, **sanitize all inputs explicitly**, not just
the log message.
+Common oversights include:
+
+* Sanitizing only `%m` (e.g. `%enc{%m}\{CRLF}` in Log4j Core) while leaving
other fields unescaped
+* The implicit `%ex` pattern specifier (exception stack traces), which are a
frequent and overlooked source of CRLF characters
+* Seemingly "safe" values such as logger names, thread names, and log levels,
which may contain unexpected data depending on your application
+====
+
+[#crlf-injection-rfc5424-layout]
+=== RFC 5424 layout
+
+**Claim**: RFC 5424 layout is vulnerable to CRLF injection because it does not
escape CRLF characters by default.
+
+RFC 5424 layout is a **structured format** with well-defined fields and
delimiters, enabling reliable and unambiguous parsing.
+However, per https://datatracker.ietf.org/doc/html/rfc5424#section-8.2[Section
8.2 of RFC 5424], the spec itself does **not** require escaping of control
characters (including CRLF) in the `PARAM-VALUE` or `MSG` fields.
+Instead, responsibility for handling those characters is delegated to the
**transport binding** in use.
+
+For this reason, Log4j Core does not escape CRLF characters by default, and
this is **not** considered a vulnerability.
+
+[#crlf-injection-rfc5424-layout-why-not]
+==== Why this is not a vulnerability
+
+The appropriate handling of CRLF characters depends on which transport
protocol carries the log messages.
+RFC 5424 is used with several protocol bindings, each with different framing
semantics:
+
+UDP (https://datatracker.ietf.org/doc/html/rfc5426[RFC 5426])::
+Each message is transmitted as a self-contained datagram, so CRLF characters
carry no special meaning and require no escaping.
+
+TLS-encrypted TCP (https://datatracker.ietf.org/doc/html/rfc5425[RFC 5425])::
+The recommended transport for new deployments.
+Uses length-prefixed framing, so message boundaries are established
independently of content.
+CRLF escaping is not required.
+
+Legacy TCP (https://datatracker.ietf.org/doc/html/rfc6587[RFC 6587])::
+Uses LF as a message delimiter, so LF characters within a message must be
escaped.
+This protocol is **discouraged** for new deployments due to known limitations.
+
+Applying CRLF escaping unconditionally at the layout level would silently
alter log content for transport bindings that do not need it.
+Defaulting to no escaping preserves the original log data while allowing each
transport binding to apply the appropriate treatment.
+
+[TIP]
+====
+RFC 5424 layout does support optional CRLF escaping, which you can enable
explicitly when using a transport that requires it (such as legacy TCP over RFC
6587).
+Refer to the layout configuration reference for details.
+
+If you are starting a new deployment, prefer TLS-encrypted TCP (RFC 5425),
which avoids this concern entirely through length-prefixed framing.
+====
+
+[#path-traversal]
+== https://cwe.mitre.org/data/definitions/35.html[CWE-35: Path Traversal]
+
+A frequently reported issue is the presence of unvalidated file paths in
configuration files, such as file appender file names.
+
+**Claim**: File appenders are vulnerable to path traversal because they accept
unvalidated file paths.
+
+[#path-traversal-why-not]
+=== Why this is not a vulnerability
+
+Configuration files are **trusted** resources according to our
xref:security.adoc#threat-model[threat model] and must be protected accordingly.
+Given that trust, constraining the file paths they may contain provides no
meaningful security benefit.
+
+Limiting file paths to a specific directory would also introduce a
**chicken-and-egg problem**: doing so would require an additional configuration
resource to define the allowed directory, which itself would need to be trusted
and protected.
+We do not establish a hierarchy of trust between configuration resources
(environment variables, system properties, configuration files, and so on):
they are all considered equally trusted.
+
+[#path-traversal-problematic-contexts]
+=== Problematic contexts
+
+While unvalidated file paths in configuration are not a vulnerability in
themselves, they can become one when **interpolation** features (arbiters,
lookups, etc.) are used to construct file paths dynamically.
+
+This risk is compounded when interpolation occurs at **runtime** rather than
at configuration time: for example, when appenders are created dynamically by
Log4j Core's
+{site-url}/log4j/2.x/manual/appenders/delegating.html#RoutingAppender[Routing
appender].
+In those cases, the interpolated values originate outside the configuration
file itself and may originate from untrusted or attacker-controlled sources.
+
+It is the user's responsibility to ensure that the sources of any interpolated
values used in file paths are trustworthy.
+
+[IMPORTANT]
+====
+The trustworthiness of an interpolation source cannot be determined a priori
by the Logging Services libraries, because it depends on the specific
application and how it uses that source.
+
+Consider `${ctx:...}` lookups as an example: some applications populate the
thread context map exclusively with internally generated values (such as
request IDs), while others may include user-provided data (such as HTTP
headers).
+In practice, trustworthiness often varies even at the per-key level: some
context map keys may be safe to use in file paths, while others may not.
+====
\ No newline at end of file
