(logging-site) branch feat/security-faq-rfc5424 created (now 27e0ade7)

[pk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pkarwasz pushed a change to branch feat/security-faq-rfc5424
in repository https://gitbox.apache.org/repos/asf/logging-site.git


      at 27e0ade7 Add Security FAQ

This branch includes the following new commits:

     new 27e0ade7 Add Security FAQ

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

(logging-site) 01/01: Add Security FAQ

[pk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pkarwasz pushed a commit to branch feat/security-faq-rfc5424
in repository https://gitbox.apache.org/repos/asf/logging-site.git

commit 27e0ade794587b1a3842d16bc2c7d65440b90559
Author: Piotr P. Karwasz <pk...@apache.org>
AuthorDate: Wed Mar 25 13:08:42 2026 +0100

    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.
---
 src/site/antora/modules/ROOT/nav.adoc              |   1 +
 src/site/antora/modules/ROOT/pages/security.adoc   |   5 +
 .../antora/modules/ROOT/pages/security/faq.adoc    | 123 +++++++++++++++++++++
 3 files changed, 129 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..b7c22295
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/security/faq.adoc
@@ -0,0 +1,123 @@
+////
+//  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]
+
+A frequently reported issue is the presence of CR (`\r`) and LF (`\n`) characters in layout output.
+In most logging contexts this behavior is **intentional** and **not considered a vulnerability**.
+
+=== 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.
+
+==== 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 makes neither of those guarantees: that responsibility falls to the user.
+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
+* Ostensibly "safe" values such as logger names, thread names, and log levels, which may contain unexpected data depending on your application
+====
+
+=== 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.
+
+==== 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.
+====
\ No newline at end of file