apache / apache/logging-log4j2

Document `StructuredDataMessage` argument constraints

Open
#4,051 2 comments 0 reactions 1 assignee Claimed by @DrDrunkenstien-10 View on GitHub
documentation
Dominant language
Java
Stars
3.6k
Forks
1.7k
Avg merge
21h 30m
Merged PRs (30d)
27

Description

This issue originates from a report submitted through our YesWeHack bug bounty program (#YWH-PGM10209-37). The report was ultimately classified as **not a security vulnerability**, but it highlighted opportunities to improve documentation and developer guidance.

## Problem

The `id` and `type` parameters of the `StructuredDataMessage` constructors are currently undocumented with respect to their expected syntax and constraints. These parameters are assumed to be defined by the application developer (trusted input) and are typically compile-time constants. However, this assumption is not made explicit, and incorrect values may lead to non–RFC-compliant syslog output when used with `Rfc5424Layout`.

## Proposed improvements

1. **Clarify Javadoc**

Update the `StructuredDataMessage` Javadoc to state explicitly that:

* `id` must conform to the [RFC 5424 *SD-ID*](https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2) syntax.
Recommend using `StructuredDataId` instead of a raw `String` where possible.
* `type` must conform to the [RFC 5424 *MSGID*](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7) syntax.
* Both parameters are considered trusted and must be validated/sanitized by the caller if derived from external input.

2. **Optional validation**

Consider adding argument validation in `StructuredDataMessage` constructors and throwing `IllegalArgumentException` when `id` or `type` do not meet the documented constraints.

## Rationale

While developers can choose to populate these fields from untrusted sources, doing so is an application-level responsibility. Making the expected formats and trust assumptions explicit, and optionally enforcing them, improves usability, prevents accidental misuse, and helps ensure RFC 5424–compliant output.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.