homelab/traefik
1
0
Fork 0
Code Activity

Reject suspicious encoded characters

Browse source 
Co-authored-by: Kevin Pollet <pollet.kevin@gmail.com>
This commit is contained in:
Romain 2025-12-04 15:10:05 +01:00 • committed by GitHub
parent 0b6438b7c0
commit 4d7d627319
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 804 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/content/migration/v2.md
View file

@ -714,3 +714,23 @@ It appears that enabling MPTCP on some platforms can cause Traefik to stop with
- `set tcp X.X.X.X:X->X.X.X.X:X: setsockopt: operation not supported`
However, it can be re-enabled by setting the `multipathtcp` variable in the GODEBUG environment variable, see the related [go documentation](https://go.dev/doc/godebug#go-124).
## v2.11.32
## Encoded Characters in Request Path
Since `v2.11.32`, for security reasons Traefik now rejects requests with a path containing a specific set of encoded characters by default.
When such a request is received, Traefik responds with a `400 Bad Request` status code.
Here is the list of the encoded characters that are rejected by default, along with the corresponding configuration option to allow them:
| Encoded Character | Character | Config option to allow the encoded character |
|-------------------|-------------------------|--------------------------------------------------------------------------------------|
| `%2f` or `%2F` | `/` (slash) | `entryPoints.<name>`<br/>`.http.encodedCharacters`<br/>`.allowEncodedSlash` |
| `%5c` or `%5C` | `\` (backslash) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedBackSlash` |
| `%00` | `NULL` (null character) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedNullCharacter` |
| `%3b` or `%3B` | `;` (semicolon) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedSemicolon` |
| `%25` | `%` (percent) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedPercent` |
| `%3f` or `%3F` | `?` (question mark) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedQuestionMark` |
| `%23` | `#` (hash) | `entryPoints.<name>.`<br/>`.http.encodedCharacters`<br/>`.allowEncodedHash` |
Please check out the entrypoint [encodedCharacters option](../routing/entrypoints.md#encoded-characters) documentation for more details.

24
docs/content/reference/static-configuration/cli-ref.md
View file

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

24
docs/content/reference/static-configuration/env-ref.md
View file

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

8
docs/content/reference/static-configuration/file.toml
View file

@ -55,6 +55,14 @@
[[entryPoints.EntryPoint0.http.tls.domains]]
main = "foobar"
sans = ["foobar", "foobar"]
[entryPoints.EntryPoint0.http.encodedCharacters]
allowEncodedSlash = true
allowEncodedBackSlash = true
allowEncodedNullCharacter = true
allowEncodedSemicolon = true
allowEncodedPercent = true
allowEncodedQuestionMark = true
allowEncodedHash = true
[entryPoints.EntryPoint0.http2]
maxConcurrentStreams = 42
[entryPoints.EntryPoint0.http3]

8
docs/content/reference/static-configuration/file.yaml
View file

@ -62,6 +62,14 @@ entryPoints:
sans:
- foobar
- foobar
encodedCharacters:
allowEncodedSlash: true
allowEncodedBackSlash: true
allowEncodedNullCharacter: true
allowEncodedSemicolon: true
allowEncodedPercent: true
allowEncodedQuestionMark: true
allowEncodedHash: true
encodeQuerySemicolons: true
sanitizePath: true
http2:

249
docs/content/routing/entrypoints.md
View file

@ -127,6 +127,14 @@ They can be defined by using a file (YAML or TOML) or CLI arguments.
trustedIPs:
- "127.0.0.1"
- "192.168.0.1"
encodedCharacters:
allowEncodedSlash: true
allowEncodedBackSlash: true
allowEncodedNullCharacter: true
allowEncodedSemicolon: true
allowEncodedPercent: true
allowEncodedQuestionMark: true
allowEncodedHash: true
```
```toml tab="File (TOML)"
@ -152,6 +160,14 @@ They can be defined by using a file (YAML or TOML) or CLI arguments.
[entryPoints.name.forwardedHeaders]
insecure = true
trustedIPs = ["127.0.0.1", "192.168.0.1"]
[entryPoints.name.encodedCharacters]
allowEncodedSlash = true
allowEncodedBackSlash = true
allowEncodedNullCharacter = true
allowEncodedSemicolon = true
allowEncodedPercent = true
allowEncodedQuestionMark = true
allowEncodedHash = true
```
```bash tab="CLI"
@ -168,6 +184,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.encodedCharacters.allowEncodedSlash=true
--entryPoints.name.encodedCharacters.allowEncodedBackSlash=true
--entryPoints.name.encodedCharacters.allowEncodedNullCharacter=true
--entryPoints.name.encodedCharacters.allowEncodedSemicolon=true
--entryPoints.name.encodedCharacters.allowEncodedPercent=true
--entryPoints.name.encodedCharacters.allowEncodedQuestionMark=true
--entryPoints.name.encodedCharacters.allowEncodedHash=true
```
### Address
@ -455,6 +478,232 @@ You can configure Traefik to trust the forwarded headers information (`X-Forward
--entryPoints.web.forwardedHeaders.connection=foobar
```
### Encoded Characters
You can configure Traefik to control the handling of encoded characters in request paths for security purposes.
By default, Traefik rejects requests containing certain encoded characters that could be used in path traversal or other security attacks.
!!! warning "Security Considerations"
Allowing certain encoded characters may expose your application to security vulnerabilities.
??? info "`encodedCharacters.allowEncodedSlash`"
_Optional, Default=false_
Controls whether requests with encoded slash characters (`%2F` or `%2f`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedSlash: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedSlash = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedSlash=true
```
??? info "`encodedCharacters.allowEncodedBackSlash`"
_Optional, Default=false_
Controls whether requests with encoded back slash characters (`%5C` or `%5c`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedBackSlash: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedBackSlash = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedBackSlash=true
```
??? info "`encodedCharacters.allowEncodedNullCharacter`"
_Optional, Default=false_
Controls whether requests with encoded null characters (`%00`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedNullCharacter: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedNullCharacter = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedNullCharacter=true
```
??? info "`encodedCharacters.allowEncodedSemicolon`"
_Optional, Default=false_
Controls whether requests with encoded semicolon characters (`%3B` or `%3b`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedSemicolon: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedSemicolon = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedSemicolon=true
```
??? info "`encodedCharacters.allowEncodedPercent`"
_Optional, Default=false_
Controls whether requests with encoded percent characters (`%25`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedPercent: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedPercent = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedPercent=true
```
??? info "`encodedCharacters.allowEncodedQuestionMark`"
_Optional, Default=false_
Controls whether requests with encoded question mark characters (`%3F` or `%3f`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedQuestionMark: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedQuestionMark = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedQuestionMark=true
```
??? info "`encodedCharacters.allowEncodedHash`"
_Optional, Default=false_
Controls whether requests with encoded hash characters (`%23`) in the path are allowed.
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
encodedCharacters:
allowEncodedHash: true
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.encodedCharacters]
allowEncodedHash = true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.encodedCharacters.allowEncodedHash=true
```
### Transport
#### `respondingTimeouts`

9
docs/content/security/content-length.md
View file

@ -3,7 +3,8 @@ title: "Content-Length"
description: "Enforce strict Content‑Length validation in Traefik by streaming or full buffering to prevent truncated or over‑long requests and responses. Read the technical documentation."
---
Traefik acts as a streaming proxy. By default, it checks each chunk of data against the `Content-Length` header as it passes it on to the backend or client. This live check blocks truncated or over‑long streams without holding the entire message.
Traefik acts as a streaming proxy. By default, it checks each chunk of data against the `Content-Length` header as it passes it on to the backend or client.
This live check blocks truncated or over‑long streams without holding the entire message.
If you need Traefik to read and verify the full body before any data moves on, add the [buffering middleware](../middlewares/http/buffering.md):
@ -20,5 +21,7 @@ With buffering enabled, Traefik will:
- Compare the actual byte count to the `Content-Length` header.
- Reject the message if the counts do not match.
!!!warning
Buffering adds overhead. Every request and response is held in full before forwarding, which can increase memory use and latency. Use it when strict content validation is critical to your security posture.
!!! warning
Buffering adds overhead. Every request and response is held in full before forwarding, which can increase memory use and latency.
Use it when strict content validation is critical to your security posture.

129
docs/content/security/request-path.md Normal file
View file

@ -0,0 +1,129 @@
---
title: "Request Path Security"
description: "Learn how Traefik processes and secures request paths through sanitization and encoded character filtering to protect against path traversal and injection attacks."
---
# Request Path
Protecting Against Path-Based Attacks Through Sanitization and Filtering
{: .subtitle }
Traefik implements multiple layers of security when processing incoming request paths.
This includes path sanitization to normalize potentially dangerous sequences and encoded character filtering to prevent attack vectors that use URL encoding.
Understanding how Traefik handles request paths is crucial for maintaining a secure routing infrastructure.
## How Traefik Processes Request Paths
When Traefik receives an HTTP request, it processes the request path through several security-focused stages:
### 1. Encoded Character Filtering
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:
| Encoded Character | Character |
|-------------------|-------------------------|
| `%2f` or `%2F` | `/` (slash) |
| `%5c` or `%5C` | `\` (backslash) |
| `%00` | `NULL` (null character) |
| `%3b` or `%3B` | `;` (semicolon) |
| `%25` | `%` (percent) |
| `%3f` or `%3F` | `?` (question mark) |
| `%23` | `#` (hash) |
### 2. Path Normalization
Traefik normalizes the request path by decoding the unreserved percent-encoded characters,
as they are equivalent to their non-encoded form (according to [rfc3986#section-2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3)),
and capitalizing the percent-encoded characters (according to [rfc3986#section-6.2.2.1](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1)).
### 3. Path Sanitization
Traefik sanitizes request paths to prevent common attack vectors,
by removing the `..`, `.` and duplicate slash segments from the URL (according to [rfc3986#section-6.2.2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.3)).
## Path Security Configuration
Traefik provides two main mechanisms for path security that work together to protect your applications.
### Path Sanitization
Path sanitization is enabled by default and helps prevent directory traversal attacks by normalizing request paths.
Configure it in the [EntryPoints](../routing/entrypoints.md#sanitizepath) HTTP section:
```yaml tab="File (YAML)"
entryPoints:
websecure:
address: ":443"
http:
sanitizePath: true # Default: true (recommended)
```
```toml tab="File (TOML)"
[entryPoints.websecure]
address = ":443"
[entryPoints.websecure.http]
sanitizePath = true
```
```bash tab="CLI"
--entryPoints.websecure.address=:443
--entryPoints.websecure.http.sanitizePath=true
```
**Sanitization behavior:**
- `./foo/bar` → `/foo/bar` (removes relative current directory)
- `/foo/../bar` → `/bar` (resolves parent directory traversal)
- `/foo/bar//` → `/foo/bar/` (removes duplicate slashes)
- `/./foo/../bar//` → `/bar/` (combines all normalizations)
### Encoded Character Filtering
Encoded character filtering provides an additional security layer by rejecting potentially dangerous URL-encoded characters.
Configure it in the [EntryPoints](../routing/entrypoints.md#encoded-characters) HTTP section.
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:
```yaml tab="File (YAML)"
entryPoints:
websecure:
address: ":443"
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)
```
```toml tab="File (TOML)"
[entryPoints.websecure]
address = ":443"
[entryPoints.websecure.encodedCharacters]
allowEncodedSlash = false
allowEncodedBackSlash = false
allowEncodedNullCharacter = false
allowEncodedSemicolon = false
allowEncodedPercent = false
allowEncodedQuestionMark = false
allowEncodedHash = false
```
```bash tab="CLI"
--entryPoints.websecure.address=:443
--entryPoints.websecure.encodedCharacters.allowEncodedSlash=false
--entryPoints.websecure.encodedCharacters.allowEncodedBackSlash=false
--entryPoints.websecure.encodedCharacters.allowEncodedNullCharacter=false
--entryPoints.websecure.encodedCharacters.allowEncodedSemicolon=false
--entryPoints.websecure.encodedCharacters.allowEncodedPercent=false
--entryPoints.websecure.encodedCharacters.allowEncodedQuestionMark=false
--entryPoints.websecure.encodedCharacters.allowEncodedHash=false
```