vy commented on code in PR #2219:
URL: https://github.com/apache/logging-log4j2/pull/2219#discussion_r1461103299
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
+While specific Log4j plugins (such as a JNDI lookup) may use constraint
validators or conditionals to require additional settings to opt in to
functionality, this is not universally required by custom plugins.
+Specific security considerations involved in our threat model are detailed
below.
+
+=== Parameterized Logging
+
+When using a log message containing template parameters like `{}`, only the
format string is evaluated for parameters to be substituted.
+The message parameters themselves are not evaluated for parameters; they are
only included in the format string corresponding to their template position.
+The conversion of message parameters into a string is done on-demand depending
on the layout being used.
+When structure-preserving transformations of log message data are required,
the `Message` API should be used for logging structured data.
Review Comment:
Shouldn't we rather have said the following instead?
```suggestion
When structure-preserving transformations of log message data are required,
layouts supporting this functionality (e.g., `JsonTemplateLayout`) should be
used.
```
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
+While specific Log4j plugins (such as a JNDI lookup) may use constraint
validators or conditionals to require additional settings to opt in to
functionality, this is not universally required by custom plugins.
+Specific security considerations involved in our threat model are detailed
below.
+
+=== Parameterized Logging
+
+When using a log message containing template parameters like `{}`, only the
format string is evaluated for parameters to be substituted.
+The message parameters themselves are not evaluated for parameters; they are
only included in the format string corresponding to their template position.
+The conversion of message parameters into a string is done on-demand depending
on the layout being used.
+When structure-preserving transformations of log message data are required,
the `Message` API should be used for logging structured data.
+
+=== Unstructured Logging
+
+When using an unstructured layout such as `PatternLayout`, no guarantees can
be made about the output format.
+This layout is mainly useful for development purposes and should not be relied
on in production applications.
+For example, if a log message contains new lines, these are not escaped or
encoded specially unless the configured pattern uses the
`%encode{pattern}{CRLF}` wrapper pattern converter (which will encode a
carriage return as the string `\r` and a line feed as the string `\n`) or some
other `%encode` option.
+Similarly, other encoding options are available for other formats, but pattern
layouts cannot make assumptions about the entire output.
+As such, when using unstructured layouts, no user-controlled input should be
included in logs.
+It is strongly recommended that a structured layout is used instead for these
situations.
Review Comment:
```suggestion
It is strongly recommended that a structured layout (e.g.,
`JsonTemplateLayout`) is used instead for these situations.
```
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
+While specific Log4j plugins (such as a JNDI lookup) may use constraint
validators or conditionals to require additional settings to opt in to
functionality, this is not universally required by custom plugins.
+Specific security considerations involved in our threat model are detailed
below.
+
+=== Parameterized Logging
+
+When using a log message containing template parameters like `{}`, only the
format string is evaluated for parameters to be substituted.
+The message parameters themselves are not evaluated for parameters; they are
only included in the format string corresponding to their template position.
+The conversion of message parameters into a string is done on-demand depending
on the layout being used.
+When structure-preserving transformations of log message data are required,
the `Message` API should be used for logging structured data.
+
+=== Unstructured Logging
+
+When using an unstructured layout such as `PatternLayout`, no guarantees can
be made about the output format.
+This layout is mainly useful for development purposes and should not be relied
on in production applications.
+For example, if a log message contains new lines, these are not escaped or
encoded specially unless the configured pattern uses the
`%encode{pattern}{CRLF}` wrapper pattern converter (which will encode a
carriage return as the string `\r` and a line feed as the string `\n`) or some
other `%encode` option.
+Similarly, other encoding options are available for other formats, but pattern
layouts cannot make assumptions about the entire output.
+As such, when using unstructured layouts, no user-controlled input should be
included in logs.
+It is strongly recommended that a structured layout is used instead for these
situations.
+Note that `StrLookup` plugins (those referenced by `${...}` templates in
configuration files) that contain user-provided input should not be referenced
by a pattern layout.
+
+=== Structured Logging
+
+When using a structured layout (most layouts besides pattern layout), log
messages are encoded according to various output formats.
+These safely encode the various fields included in a log message.
+For example, the JSON template layout can be configured to output log messages
in various JSON structures where all log data is properly encoded into safely
parseable JSON.
Review Comment:
To comply with the naming convention used in previously shared layout
names...
```suggestion
For example, the `JsonTemplateLayout` can be configured to output log
messages in various JSON structures where all log data is properly encoded into
safely parseable JSON.
```
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
+While specific Log4j plugins (such as a JNDI lookup) may use constraint
validators or conditionals to require additional settings to opt in to
functionality, this is not universally required by custom plugins.
+Specific security considerations involved in our threat model are detailed
below.
+
+=== Parameterized Logging
+
+When using a log message containing template parameters like `{}`, only the
format string is evaluated for parameters to be substituted.
+The message parameters themselves are not evaluated for parameters; they are
only included in the format string corresponding to their template position.
+The conversion of message parameters into a string is done on-demand depending
on the layout being used.
+When structure-preserving transformations of log message data are required,
the `Message` API should be used for logging structured data.
+
+=== Unstructured Logging
+
+When using an unstructured layout such as `PatternLayout`, no guarantees can
be made about the output format.
+This layout is mainly useful for development purposes and should not be relied
on in production applications.
+For example, if a log message contains new lines, these are not escaped or
encoded specially unless the configured pattern uses the
`%encode{pattern}{CRLF}` wrapper pattern converter (which will encode a
carriage return as the string `\r` and a line feed as the string `\n`) or some
other `%encode` option.
+Similarly, other encoding options are available for other formats, but pattern
layouts cannot make assumptions about the entire output.
+As such, when using unstructured layouts, no user-controlled input should be
included in logs.
+It is strongly recommended that a structured layout is used instead for these
situations.
+Note that `StrLookup` plugins (those referenced by `${...}` templates in
configuration files) that contain user-provided input should not be referenced
by a pattern layout.
+
+=== Structured Logging
+
+When using a structured layout (most layouts besides pattern layout), log
messages are encoded according to various output formats.
+These safely encode the various fields included in a log message.
+For example, the JSON template layout can be configured to output log messages
in various JSON structures where all log data is properly encoded into safely
parseable JSON.
+This is the recommended mode of operation for use with log parsing and log
collection tools that rely on log files or arbitrary output streams.
+
+=== Code Signing
+
+Log4j artifacts are all signed using PGP using a key from the Logging Services
PMC https://downloads.apache.org/logging/KEYS[KEYS file].
+Information on how to verify releases signed with PGP is
https://httpd.apache.org/dev/verification.html[documented here].
+Individual jar files are not signed using `jarsigner` (only PGP), and the
Log4j plugin system does not rely on signed jars for validation (unlike the
Java cryptography APIs for example).
+Thus, PGP signatures should be validated in your build process.
+
+=== Java Security Manager
+
+Log4j no longer supports running in or using a custom `SecurityManager`.
+This Java feature has been deprecated for removal in Java 21.
+Previous versions of Log4j 2.x include partial support for running with a
security manager.
+
+=== Log Masking
+
+Log4j, like any other generic logging library, cannot generically support log
masking of sensitive data.
+While custom plugins may be developed to attempt to mask various regular
expressions (such as a string that looks like a credit card number), the
general problem of log masking is equivalent to the halting problem in computer
science where sensitive data can always be obfuscated in such a way as to avoid
detection by log masking.
+As such, it is the responsibility of the developer to properly demarcate
sensitive data such that it can be consistently masked by log masking plugins.
+This sort of use case should make use of the `Message` API for better control
over the output of such data.
+
+=== Availability
+
+Log4j goes to great lengths to minimize performance overhead along with
options for minimizing latency or maximizing throughput.
+However, we cannot guarantee availability of the application if the appenders
cannot keep up with the logs being written.
+Synchronous logging can cause applications to block and wait for a log message
to be written.
+Asynchronous logging can also cause applications to block and wait depending
on the wait strategy and queue full policy configured.
+Configuring too large or too many buffers in Log4j can also result in out of
memory errors.
+
+=== Configuration Sources
+
+All configuration sources to an application must be trusted by the programmer.
+When loading a configuration file from disk (especially when a monitor
interval is configured to reload the file periodically), the location of the
configuration file must be kept safe from unauthorized modifications.
+Similarly, when loading a configuration file over the network such as through
HTTP, this should be configured to use TLS or a secure connection in general
with strong authentication guarantees.
+This remote location must be kept safe from unauthorized modifications.
+When configurations are modified through JMX, the JMX server should be safely
configured to require authentication and a secure connection if being accessed
over the network.
+When configurations are provided through JNDI, these should only use the
`java` scheme for sharing configurations in a JavaEE or JakartaEE application
service.
+JNDI-sourced configurations should not use other JNDI providers such as LDAP,
DNS, or RMI, as all these providers are difficult to properly secure.
+
+=== Cryptographic Logs
+
+When using custom plugins to calculate message authentication codes,
signatures, or encrypted logs, proper key management must be considered.
+Cryptography is a tricky subject, and key management lies at the heart of most
design problems to solve when using it.
+If a custom plugin relies on a pre-shared key or password of some sort, it is
likely broken beyond repair if being used for cryptographic purposes.
+Proper key management typically uses public key infrastructure (PKI) such as
X.509 certificates, though this is not the only option.
+It is beyond the scope of Log4j to implement key management as this would
depend on other infrastructure in use for validating or decrypting logs
combined with the deployment and runtime environment of the logging application.
Review Comment:
Cryptographic logs are neither a feature we slightly offer, nor something we
even briefly mention. This is not a place we educate users on cryptographic
logs either. Hence... I think we can do without this section.
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
Review Comment:
Arbitrary code can very well be executed in a mere configuration, say, using
`ScriptFilter`; using plugins is not a necessity.
```suggestion
Configurations have the ability to execute arbitrary code.
```
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
+While specific Log4j plugins (such as a JNDI lookup) may use constraint
validators or conditionals to require additional settings to opt in to
functionality, this is not universally required by custom plugins.
+Specific security considerations involved in our threat model are detailed
below.
+
+=== Parameterized Logging
+
+When using a log message containing template parameters like `{}`, only the
format string is evaluated for parameters to be substituted.
+The message parameters themselves are not evaluated for parameters; they are
only included in the format string corresponding to their template position.
+The conversion of message parameters into a string is done on-demand depending
on the layout being used.
+When structure-preserving transformations of log message data are required,
the `Message` API should be used for logging structured data.
+
+=== Unstructured Logging
+
+When using an unstructured layout such as `PatternLayout`, no guarantees can
be made about the output format.
+This layout is mainly useful for development purposes and should not be relied
on in production applications.
+For example, if a log message contains new lines, these are not escaped or
encoded specially unless the configured pattern uses the
`%encode{pattern}{CRLF}` wrapper pattern converter (which will encode a
carriage return as the string `\r` and a line feed as the string `\n`) or some
other `%encode` option.
+Similarly, other encoding options are available for other formats, but pattern
layouts cannot make assumptions about the entire output.
+As such, when using unstructured layouts, no user-controlled input should be
included in logs.
+It is strongly recommended that a structured layout is used instead for these
situations.
+Note that `StrLookup` plugins (those referenced by `${...}` templates in
configuration files) that contain user-provided input should not be referenced
by a pattern layout.
Review Comment:
JTL also uses lookups too. Hence, they should not be used anywhere anyway.
```suggestion
Note that `StrLookup` plugins (those referenced by `${...}` templates in
configuration files) that contain user-provided input should not be referenced
by layouts.
```
##########
src/site/asciidoc/security.adoc:
##########
@@ -46,6 +46,89 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
The threat model that Log4j uses considers configuration files as safe input
controlled by the programmer; **potential vulnerabilities that require the
ability to modify a configuration are not considered vulnerabilities** as the
required access to do so implies the attacker can execute arbitrary code.
====
+[#model]
+== Threat Model
+
+Log4j is a low level library where configuration inputs and the classpath are
expected to be controlled by the programmer.
+Configurations have the ability to execute arbitrary code through custom
plugins.
+While specific Log4j plugins (such as a JNDI lookup) may use constraint
validators or conditionals to require additional settings to opt in to
functionality, this is not universally required by custom plugins.
+Specific security considerations involved in our threat model are detailed
below.
+
+=== Parameterized Logging
+
+When using a log message containing template parameters like `{}`, only the
format string is evaluated for parameters to be substituted.
+The message parameters themselves are not evaluated for parameters; they are
only included in the format string corresponding to their template position.
+The conversion of message parameters into a string is done on-demand depending
on the layout being used.
+When structure-preserving transformations of log message data are required,
the `Message` API should be used for logging structured data.
+
+=== Unstructured Logging
+
+When using an unstructured layout such as `PatternLayout`, no guarantees can
be made about the output format.
+This layout is mainly useful for development purposes and should not be relied
on in production applications.
+For example, if a log message contains new lines, these are not escaped or
encoded specially unless the configured pattern uses the
`%encode{pattern}{CRLF}` wrapper pattern converter (which will encode a
carriage return as the string `\r` and a line feed as the string `\n`) or some
other `%encode` option.
+Similarly, other encoding options are available for other formats, but pattern
layouts cannot make assumptions about the entire output.
+As such, when using unstructured layouts, no user-controlled input should be
included in logs.
+It is strongly recommended that a structured layout is used instead for these
situations.
+Note that `StrLookup` plugins (those referenced by `${...}` templates in
configuration files) that contain user-provided input should not be referenced
by a pattern layout.
+
+=== Structured Logging
+
+When using a structured layout (most layouts besides pattern layout), log
messages are encoded according to various output formats.
+These safely encode the various fields included in a log message.
+For example, the JSON template layout can be configured to output log messages
in various JSON structures where all log data is properly encoded into safely
parseable JSON.
+This is the recommended mode of operation for use with log parsing and log
collection tools that rely on log files or arbitrary output streams.
+
+=== Code Signing
+
+Log4j artifacts are all signed using PGP using a key from the Logging Services
PMC https://downloads.apache.org/logging/KEYS[KEYS file].
+Information on how to verify releases signed with PGP is
https://httpd.apache.org/dev/verification.html[documented here].
+Individual jar files are not signed using `jarsigner` (only PGP), and the
Log4j plugin system does not rely on signed jars for validation (unlike the
Java cryptography APIs for example).
Review Comment:
We can do without mentioning every single option we do not do.
```suggestion
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@logging.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
