Overview
Canonicalization — resolving a path to its true, standard form — is central to preventing path traversal, because attackers use alternate representations to slip past naive checks. This lesson applies canonicalization specifically to file paths.
Learning objectives
- Explain canonicalization in the path context.
- Show how alternate encodings/forms bypass naive path checks.
- Establish the canonicalize-then-validate rule for paths.
Core concept
Path canonicalization resolves a path to its single, real, absolute form — collapsing .. and . segments, decoding any encodings, and normalizing separators. This matters because the same location can be expressed many ways: with different traversal sequences, percent-encoded characters, mixed separators, or Unicode variants. A check performed on the raw (non-canonical) input can be fooled, while the underlying filesystem resolves the value to a dangerous real path.
The rule: canonicalize the path first, then validate that the canonical result stays within the allowed base directory.
How it works
If an application checks the raw input for .. and rejects it, an attacker can encode the traversal (e.g. percent-encoded forms) so the naive string check misses it — but once the platform decodes and resolves the path, it becomes real traversal. The defense is to resolve the path to its canonical absolute form first (decoding and collapsing traversal), then verify that this canonical path is still within the intended base directory. Because validation happens on the same form the filesystem will use, alternate encodings no longer help the attacker.
Practical example
A file-serving endpoint tries to block traversal by rejecting inputs containing ../. An attacker supplies a percent-encoded traversal sequence, which the raw-string check does not match; when decoded and resolved, it escapes the base directory — a canonicalization failure. The correct approach: canonicalize the requested path to its real absolute form, then confirm it begins with (is contained by) the allowed base directory; reject otherwise. Now encoded traversal is resolved before the check and caught.
Cybersecurity relevance
Canonicalization failures are the classic reason path-traversal filters get bypassed: the security check and the filesystem disagree about what the path means. This mirrors the general canonicalization lesson but is especially critical for file access, where a bypass can expose sensitive system files. Defenders must canonicalize before validating and confirm containment within the base directory; testers try encoded and alternate traversal forms precisely to defeat naive checks. Canonicalization is a cornerstone of traversal defense, working with allowlists and safe APIs.
Common mistakes
- Validating the raw path (e.g. string-matching
../) before canonicalizing, enabling encoded bypasses. - Handling only one traversal representation and missing encoded/alternate forms.
- Checking for
..presence instead of verifying the canonical path is contained in the base directory.
Key takeaways
- Path canonicalization resolves a path to its true absolute form (collapsing
../., decoding, normalizing separators). - Alternate representations (encoded traversal, mixed separators) bypass raw-string checks but resolve to real paths — so canonicalize first, then validate.
- Validate by confirming the canonical path stays within the allowed base directory; canonicalization is a cornerstone of traversal defense.
Check your understanding
- Why can a filter that rejects the literal string
../still be bypassed? - After canonicalizing a requested path, what must you verify to prevent traversal?