Java Agents 2024.11

URL handling

Java Agent has a secure-by-default approach to handling incoming request URLs. Learn more in Path traversal attempts.

Consider the following when configuring URL handling:

  • Not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed.

  • Encoded characters are case-insensitive. For example, %2E and %2e are handled in the same way.

Configure URL handling using the properties listed in Configure behaviour in the Properties reference. Configure the following URL handling rules:

Character handling strategy properties

The following properties control how certain characters are handled in incoming URL paths:

These properties are set to REJECT_OUTRIGHT by default, meaning the agent rejects any incoming URLs with an HTTP 400 response if they contain the specified character in the URL path or path parameters.

Other available settings are:

  • ACCEPT_BUT_NOT_INTERPRET: The agent doesn’t change the character and continues processing the request.

  • ACCEPT_AND_INTERPRET: The agent replaces the character with its equivalent before processing.

    For encoded characters, other than the encoded backslash, the replacement is the equivalent unencoded character. For the encoded and unencoded backslash, the replacement is a forward slash (/).

When the Control Handling of the URL Encoded Sequence %2f property is set to ACCEPT_AND_INTERPRET, the %2F character is not replaced within path parameters because this isn’t considered a path traversal attempt.

For example, /path/ignored;%2F../path wouldn’t be changed in this scenario.
Control Handling of Path Traversal Attempts

The Control Handling of Path Traversal Attempts property controls how path traversal attempts within the URL path are handled.

By default, this property is set to false.

Set this property to true to reject any embedded path traversal attempts with an HTTP 400 response. This includes the use of .. or combinations of . and %2E when they are used as a complete path segment.

Handle Invalid Escape Sequences

The Handle Invalid Escape Sequences property controls how encoded control characters and invalid encodings are handled.

By default, the agent rejects any encoded control characters and invalid encodings detected in the URL path with an HTTP 400 response. Encoded control characters are characters in the range %00 to %1F inclusive, and %7F. Invalid encodings are encodings such as %G1.

Set this property to false to allow these characters.

Strictly enforce the Java Servlet Specification

The Strictly enforce the Java Servlet Specification property controls whether the rules specified in the Jakarta Servlet Specification Request URI Path Processing section are enforced.

By default, the agent rejects any incoming URLs that don’t conform to these rules with an HTTP 400 response.

Set this property to false to ignore these rules.

Enable Ignore Path Info

The Enable Ignore Path Info property controls whether the path info and query are removed from the URL before it is compared with the list of not-enforced URLs when a wildcard character (*) is present.

By default, the agent doesn’t change the URL before comparing it with the list of not-enforced URLs if * is detected in the URL path.

Set this property to true if you want the agent to remove the path info and query first.