Overview
A robust defense against path traversal is to avoid free-form paths entirely and instead use an allowlist — letting users choose only from a fixed set of permitted files or identifiers. This lesson applies allowlisting to file access.
Learning objectives
- Apply allowlisting to file-access features.
- Explain indirection (mapping IDs to files) as a defense.
- Contrast allowlisting with filtering traversal sequences.
Core concept
Rather than accepting a user-supplied path and trying to sanitize it, an allowlist approach constrains the choice to known-good options:
- Indirect references — the user selects an identifier (e.g. a number or key) that the server maps to a specific file internally, so the user never supplies a path at all.
- Explicit allowlist — accept only filenames from a predefined permitted set.
This eliminates traversal by design, because the user input never becomes part of a filesystem path directly.
How it works
With indirection, the application maintains a mapping (e.g. 1 → reports/annual.pdf) and the user requests item 1; the server looks up the corresponding file. Since the user supplies only an identifier, no traversal sequence can influence the path. With an explicit allowlist, the requested filename is checked against a fixed list of permitted names and rejected if absent. Both approaches are more robust than trying to filter traversal sequences from a free-form path (a blocklist that attackers bypass via encodings), because they never let untrusted input form the path.
Practical example
A document-download feature offers a menu of documents. Instead of ?file=<path>, it uses ?doc=3, where the server maps 3 to a specific file in a fixed table. There is no way for a user to request an arbitrary path — only the predefined identifiers resolve, and anything else is rejected. Compared with accepting a filename and filtering .., this indirection removes the traversal risk entirely, because untrusted input never becomes a filesystem path.
Cybersecurity relevance
Allowlisting / indirection is the strongest, most reliable traversal defense because it removes the dangerous pattern (untrusted input → path) rather than trying to sanitize it. It reflects the broader allowlist-over-blocklist principle from the input-validation module. Where free-form paths are unavoidable, canonicalize-then-validate containment is used; but wherever feasible, mapping identifiers to files is preferred. Defenders favor indirection for file access; testers note whether file selection is constrained to an allowlist or accepts arbitrary paths.
Common mistakes
- Accepting free-form paths and filtering
..(blocklist) instead of allowlisting/indirection. - Exposing raw file paths to users when an identifier mapping would suffice.
- Making the allowlist too broad or matching it loosely, weakening the guarantee.
Key takeaways
- Prefer allowlisting/indirection for file access: map user-supplied identifiers to files, or accept only names from a fixed permitted set.
- This eliminates traversal by design because untrusted input never becomes a filesystem path.
- It is more robust than filtering traversal sequences (a bypassable blocklist) and reflects the allowlist-over-blocklist principle; use containment (canonicalize-then-validate) only where free-form paths are unavoidable.
Check your understanding
- How does mapping a user-supplied identifier to a file prevent path traversal?
- Why is allowlisting/indirection more robust than filtering
..from a user-supplied path?