This is an automated email from the ASF dual-hosted git repository.
vy 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 8a137566 Add threat model sections
8a137566 is described below
commit 8a137566051fc30d695f70a2794ff841721ac3ff
Author: Volkan Yazıcı <[email protected]>
AuthorDate: Fri Apr 19 09:57:42 2024 +0200
Add threat model sections
---
_threat-model-common.adoc | 38 +++++++++++++++++++++++++
_threat-model-log4j.adoc | 70 +++++++++++++++++++++++++++++++++++++++++++++++
security.adoc | 6 +++-
3 files changed, 113 insertions(+), 1 deletion(-)
diff --git a/_threat-model-common.adoc b/_threat-model-common.adoc
new file mode 100644
index 00000000..f7bf1c8a
--- /dev/null
+++ b/_threat-model-common.adoc
@@ -0,0 +1,38 @@
+////
+ 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.
+////
+
+.Common threat model
+[%collapsible]
+====
+Code signing::
+All Logging Services software release distributions are signed using GPG using
a key from the Logging Services PMC
https://downloads.apache.org/logging/KEYS[KEYS file].
+Information on how to verify releases signatures are explained further in
xref:download.adoc[the Download page].
+Thus, GPG signatures should be validated in your build process.
+
+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 Java EE or Jakarta EE 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.
+
+Java Object Serialization Stream Protocol::
+https://docs.oracle.com/javase/8/docs/platform/serialization/spec/protocol.html[Java
Object Serialization Stream Protocol] should not be used to deserialize data
from untrusted sources.
+See
https://owasp.org/www-community/vulnerabilities/Deserialization_of_untrusted_data[the
related OWASP guide] for details.
+====
diff --git a/_threat-model-log4j.adoc b/_threat-model-log4j.adoc
new file mode 100644
index 00000000..376b292a
--- /dev/null
+++ b/_threat-model-log4j.adoc
@@ -0,0 +1,70 @@
+////
+ 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.
+////
+
+.Log4j threat model
+[%collapsible]
+====
+Configuration inputs and the classpath are expected to be controlled by the
programmer.
+Configurations have the ability to execute arbitrary code.
+While specific 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 combined with a
structured layout (e.g., `JsonTemplateLayout`).
+Format strings should be compile-time constants, and under no circumstances
should format strings be built using user-controlled input 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.
+Note that `%xEx` is appended to the pattern unless already present.
+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 (e.g.,
`JsonTemplateLayout`) 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 layouts.
+
+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 `JsonTemplateLayout` 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.
+
+Java Security Manager::
+Log4j 3 no longer supports running in or using a custom `SecurityManager`.
+This Java feature has been deprecated for removal in Java 21.
+Log4j 2 includes 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 an application can also result in
out of memory errors.
+
+Compressing logs::
+If log compression is used along with custom encryption where logs contain
user-controlled input, then this can lead to a
https://en.wikipedia.org/wiki/CRIME[CRIME attack] style vulnerability where a
chosen-plaintext attack is combined with information leakage caused by how the
compression algorithm handles different inputs.
+The simplest way to avoid this problem is to never combine compression with
encryption when encoding user-controlled input.
+====
diff --git a/security.adoc b/security.adoc
index 32294374..6cd3dbab 100644
--- a/security.adoc
+++ b/security.adoc
@@ -43,9 +43,13 @@ If you have encountered an unlisted security vulnerability
or other unexpected b
[WARNING]
====
-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.
+The threat model that Logging Services 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.
====
+include::_threat-model-common.adoc[]
+
+include::_threat-model-log4j.adoc[]
+
[#policy]
== Vulnerability handling policy
