Merge pull request #376 from epage/color

docs: Address Weaponizing ANSI Escape Sequences

Author: epage

src/lib.rs

@@ -195,17 +195,35 @@
 //! Enabling test capturing comes at the expense of color and other style support
 //! and may have performance implications.
 //!
-//! ## Disabling colors
+//! ## Colors
 //!
-//! Colors and other styles can be configured with the `RUST_LOG_STYLE`
-//! environment variable. It accepts the following values:
+//! Outputting of colors and other styles can be controlled by the `RUST_LOG_STYLE`
+//! environment variable. It accepts the following [values][fmt::WriteStyle]:
 //!
 //! * `auto` (default) will attempt to print style characters, but don't force the issue.
 //!   If the console isn't available on Windows, or if TERM=dumb, for example, then don't print colors.
 //! * `always` will always print style characters even if they aren't supported by the terminal.
 //!   This includes emitting ANSI colors on Windows if the console API is unavailable.
 //! * `never` will never print style characters.
 //!
+//! Color may be applied in the logged message or a [custom formatter][fmt].
+//!
+//! <div class="warning">
+//!
+//! Logging of untrusted inputs can cause unexpected behavior as they may include ANSI escape codes which
+//! will be forwarded to the users terminal as part of "Weaponizing ANSI Escape Sequences".
+//!
+//! Mitigations include:
+//! - Setting `RUST_LOG_STYLE=never` to have all ANSI escape codes stripped
+//! - In the application, calling [`Builder::write_style(Never)`] to have all ANSI escape codes stripped
+//! - In the application, [stripping ANSI escape codes](https://docs.rs/anstream/latest/anstream/adapter/fn.strip_str.html)
+//!   from user inputs
+//!
+//! Note: deactivating the build-time feature `color` is not a mitigation as that removes all ANSI escape code
+//! stripping from `env_logger`.
+//!
+//! </div>
+//!
 //! ## Tweaking the default format
 //!
 //! Parts of the default format can be excluded from the log output using the [`Builder`].