1
0
Fork 0

Make encoded character options opt-in

This commit is contained in:
Gina A. 2026-01-14 10:16:04 +01:00 committed by GitHub
parent ee265a8509
commit adf47fba31
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 221 additions and 179 deletions

View file

@ -737,3 +737,30 @@ Note: This check is not done against query parameters,
but only against the request path as defined in [RFC3986 section-3](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
Please check out the entrypoint [encodedCharacters option](../routing/entrypoints.md#encoded-characters) documentation for more details.
## v2.11.35
### Encoded Characters Configuration Default Values
Since `v2.11.35`, the options for encoded characters now have a `true` default value.
This means that Traefik will not reject requests with a path containing a specific set of encoded characters by default.
It is now up to the users to configure the security hardening of encoded characters.
Here is the list of the encoded characters that can be configured to `false` to disallow them:
| Encoded Character | Character | Config options | Default value |
|-------------------|-------------------------|--------------------------------------------------------------------------------------|---------------|
| `%2f` or `%2F` | `/` (slash) | `entryPoints.<name>`<br/>`.http.encodedCharacters`<br/>`.allowEncodedSlash` | `true` |
| `%5c` or `%5C` | `\` (backslash) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedBackSlash` | `true` |
| `%00` | `NULL` (null character) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedNullCharacter` | `true` |
| `%3b` or `%3B` | `;` (semicolon) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedSemicolon` | `true` |
| `%25` | `%` (percent) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedPercent` | `true` |
| `%3f` or `%3F` | `?` (question mark) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedQuestionMark` | `true` |
| `%23` | `#` (hash) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedHash` | `true` |
Note: This check is not done against query parameters,
but only against the request path as defined
in [RFC3986 section-3](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
Please check out the entrypoint [encodedCharacters option](../routing/entrypoints.md#encoded-characters) documentation
for more details.

View file

@ -124,25 +124,25 @@ Trust only forwarded headers from selected IPs.
HTTP configuration.
`--entrypoints.<name>.http.encodedcharacters.allowencodedbackslash`:
Defines whether requests with encoded back slash characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded back slash characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodedcharacters.allowencodedhash`:
Defines whether requests with encoded hash characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded hash characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodedcharacters.allowencodednullcharacter`:
Defines whether requests with encoded null characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded null characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodedcharacters.allowencodedpercent`:
Defines whether requests with encoded percent characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded percent characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodedcharacters.allowencodedquestionmark`:
Defines whether requests with encoded question mark characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded question mark characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodedcharacters.allowencodedsemicolon`:
Defines whether requests with encoded semicolon characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded semicolon characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodedcharacters.allowencodedslash`:
Defines whether requests with encoded slash characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded slash characters in the path are allowed. (Default: ```true```)
`--entrypoints.<name>.http.encodequerysemicolons`:
Defines whether request query semicolons should be URLEncoded. (Default: ```false```)

View file

@ -133,25 +133,25 @@ HTTP/3 configuration. (Default: ```false```)
UDP port to advertise, on which HTTP/3 is available. (Default: ```0```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDBACKSLASH`:
Defines whether requests with encoded back slash characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded back slash characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDHASH`:
Defines whether requests with encoded hash characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded hash characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDNULLCHARACTER`:
Defines whether requests with encoded null characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded null characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDPERCENT`:
Defines whether requests with encoded percent characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded percent characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDQUESTIONMARK`:
Defines whether requests with encoded question mark characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded question mark characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDSEMICOLON`:
Defines whether requests with encoded semicolon characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded semicolon characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDSLASH`:
Defines whether requests with encoded slash characters in the path are allowed. (Default: ```false```)
Defines whether requests with encoded slash characters in the path are allowed. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>_HTTP_ENCODEQUERYSEMICOLONS`:
Defines whether request query semicolons should be URLEncoded. (Default: ```false```)

View file

@ -129,13 +129,13 @@ They can be defined by using a file (YAML or TOML) or CLI arguments.
- "192.168.0.1"
http:
encodedCharacters:
allowEncodedSlash: true
allowEncodedBackSlash: true
allowEncodedNullCharacter: true
allowEncodedSemicolon: true
allowEncodedPercent: true
allowEncodedQuestionMark: true
allowEncodedHash: true
allowEncodedSlash: false
allowEncodedBackSlash: false
allowEncodedNullCharacter: false
allowEncodedSemicolon: false
allowEncodedPercent: false
allowEncodedQuestionMark: false
allowEncodedHash: false
```
```toml tab="File (TOML)"
@ -162,13 +162,13 @@ They can be defined by using a file (YAML or TOML) or CLI arguments.
insecure = true
trustedIPs = ["127.0.0.1", "192.168.0.1"]
[entryPoints.name.http.encodedCharacters]
allowEncodedSlash = true
allowEncodedBackSlash = true
allowEncodedNullCharacter = true
allowEncodedSemicolon = true
allowEncodedPercent = true
allowEncodedQuestionMark = true
allowEncodedHash = true
allowEncodedSlash = false
allowEncodedBackSlash = false
allowEncodedNullCharacter = false
allowEncodedSemicolon = false
allowEncodedPercent = false
allowEncodedQuestionMark = false
allowEncodedHash = false
```
```bash tab="CLI"
@ -185,13 +185,13 @@ They can be defined by using a file (YAML or TOML) or CLI arguments.
--entryPoints.name.proxyProtocol.trustedIPs=127.0.0.1,192.168.0.1
--entryPoints.name.forwardedHeaders.insecure=true
--entryPoints.name.forwardedHeaders.trustedIPs=127.0.0.1,192.168.0.1
--entryPoints.name.http.encodedCharacters.allowEncodedSlash=true
--entryPoints.name.http.encodedCharacters.allowEncodedBackSlash=true
--entryPoints.name.http.encodedCharacters.allowEncodedNullCharacter=true
--entryPoints.name.http.encodedCharacters.allowEncodedSemicolon=true
--entryPoints.name.http.encodedCharacters.allowEncodedPercent=true
--entryPoints.name.http.encodedCharacters.allowEncodedQuestionMark=true
--entryPoints.name.http.encodedCharacters.allowEncodedHash=true
--entryPoints.name.http.encodedCharacters.allowEncodedSlash=false
--entryPoints.name.http.encodedCharacters.allowEncodedBackSlash=false
--entryPoints.name.http.encodedCharacters.allowEncodedNullCharacter=false
--entryPoints.name.http.encodedCharacters.allowEncodedSemicolon=false
--entryPoints.name.http.encodedCharacters.allowEncodedPercent=false
--entryPoints.name.http.encodedCharacters.allowEncodedQuestionMark=false
--entryPoints.name.http.encodedCharacters.allowEncodedHash=false
```
### Address
@ -1021,20 +1021,21 @@ entryPoints:
### Encoded Characters
You can configure Traefik to control the handling of encoded characters in request paths for security purposes.
By default, Traefik rejects requests with path containing certain encoded characters that could be used in path traversal or other security attacks.
By default, Traefik do not reject requests with path containing certain encoded characters that could be used in path traversal or other security attacks.
!!! info
This check is not done against the request query parameters,
but only against the request path as defined in [RFC3986 section-3](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
!!! warning "Security Considerations"
!!! info "Security Considerations"
Allowing certain encoded characters may expose your application to security vulnerabilities.
When your backend is not fully compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) and notably decode encoded reserved characters in the requets path,
it is recommended to set these options to `false` to avoid split-view situation and helps prevent path traversal attacks or other malicious attempts to bypass security controls.
??? info "`encodedCharacters.allowEncodedSlash`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded slash characters (`%2F` or `%2f`) in the path are allowed.
@ -1045,7 +1046,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedSlash: true
allowEncodedSlash: false
```
```toml tab="File (TOML)"
@ -1055,18 +1056,18 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedSlash = true
allowEncodedSlash = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedSlash=true
--entryPoints.web.http.encodedCharacters.allowEncodedSlash=false
```
??? info "`encodedCharacters.allowEncodedBackSlash`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded back slash characters (`%5C` or `%5c`) in the path are allowed.
@ -1077,7 +1078,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedBackSlash: true
allowEncodedBackSlash: false
```
```toml tab="File (TOML)"
@ -1087,18 +1088,18 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedBackSlash = true
allowEncodedBackSlash = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedBackSlash=true
--entryPoints.web.http.encodedCharacters.allowEncodedBackSlash=false
```
??? info "`encodedCharacters.allowEncodedNullCharacter`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded null characters (`%00`) in the path are allowed.
@ -1109,7 +1110,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedNullCharacter: true
allowEncodedNullCharacter: false
```
```toml tab="File (TOML)"
@ -1119,18 +1120,18 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedNullCharacter = true
allowEncodedNullCharacter = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedNullCharacter=true
--entryPoints.web.http.encodedCharacters.allowEncodedNullCharacter=false
```
??? info "`encodedCharacters.allowEncodedSemicolon`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded semicolon characters (`%3B` or `%3b`) in the path are allowed.
@ -1141,7 +1142,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedSemicolon: true
allowEncodedSemicolon: false
```
```toml tab="File (TOML)"
@ -1151,18 +1152,18 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedSemicolon = true
allowEncodedSemicolon = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedSemicolon=true
--entryPoints.web.http.encodedCharacters.allowEncodedSemicolon=false
```
??? info "`encodedCharacters.allowEncodedPercent`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded percent characters (`%25`) in the path are allowed.
@ -1173,7 +1174,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedPercent: true
allowEncodedPercent: false
```
```toml tab="File (TOML)"
@ -1183,18 +1184,18 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedPercent = true
allowEncodedPercent = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedPercent=true
--entryPoints.web.http.encodedCharacters.allowEncodedPercent=false
```
??? info "`encodedCharacters.allowEncodedQuestionMark`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded question mark characters (`%3F` or `%3f`) in the path are allowed.
@ -1205,7 +1206,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedQuestionMark: true
allowEncodedQuestionMark: false
```
```toml tab="File (TOML)"
@ -1215,18 +1216,18 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedQuestionMark = true
allowEncodedQuestionMark = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedQuestionMark=true
--entryPoints.web.http.encodedCharacters.allowEncodedQuestionMark=false
```
??? info "`encodedCharacters.allowEncodedHash`"
_Optional, Default=false_
_Optional, Default=true_
Controls whether requests with encoded hash characters (`%23`) in the path are allowed.
@ -1237,7 +1238,7 @@ By default, Traefik rejects requests with path containing certain encoded charac
address: ":80"
http:
encodedCharacters:
allowEncodedHash: true
allowEncodedHash: false
```
```toml tab="File (TOML)"
@ -1247,13 +1248,13 @@ By default, Traefik rejects requests with path containing certain encoded charac
address = ":80"
[entryPoints.web.http.encodedCharacters]
allowEncodedHash = true
allowEncodedHash = false
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.http.encodedCharacters.allowEncodedHash=true
--entryPoints.web.http.encodedCharacters.allowEncodedHash=false
```
### SanitizePath

View file

@ -20,7 +20,7 @@ When Traefik receives an HTTP request, it processes the request path through sev
Traefik inspects the path for potentially dangerous encoded characters and rejects requests containing them unless explicitly allowed.
Here is the list of the encoded characters that are rejected by default:
Here is the list of the encoded characters that are allowed by default:
| Encoded Character | Character |
|-------------------|-------------------------|
@ -87,7 +87,12 @@ Configure it in the [EntryPoints](../routing/entrypoints.md#encoded-characters)
This filtering occurs before path sanitization and catches attack attempts that use encoding to bypass other security controls.
All encoded character filtering is enabled by default (`false` means encoded characters are rejected), providing maximum security:
All encoded character filtering is disabled by default (`true` means encoded characters are allowed).
!!! info "Security Considerations"
When your backend is not fully compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) and notably decode encoded reserved characters in the requets path,
it is recommended to set these options to `false` to avoid split-view situation and helps prevent path traversal attacks or other malicious attempts to bypass security controls.
```yaml tab="File (YAML)"
entryPoints:
@ -95,13 +100,13 @@ entryPoints:
address: ":443"
http:
encodedCharacters:
allowEncodedSlash: false # %2F - Default: false (RECOMMENDED)
allowEncodedBackSlash: false # %5C - Default: false (RECOMMENDED)
allowEncodedNullCharacter: false # %00 - Default: false (RECOMMENDED)
allowEncodedSemicolon: false # %3B - Default: false (RECOMMENDED)
allowEncodedPercent: false # %25 - Default: false (RECOMMENDED)
allowEncodedQuestionMark: false # %3F - Default: false (RECOMMENDED)
allowEncodedHash: false # %23 - Default: false (RECOMMENDED)
allowEncodedSlash: false # %2F - Default: true
allowEncodedBackSlash: false # %5C - Default: true
allowEncodedNullCharacter: false # %00 - Default: true
allowEncodedSemicolon: false # %3B - Default: true
allowEncodedPercent: false # %25 - Default: true
allowEncodedQuestionMark: false # %3F - Default: true
allowEncodedHash: false # %23 - Default: true
```
```toml tab="File (TOML)"