Test an upload gate against filename tricks, and never use the user's name for storage
Test an upload gate against double extensions, null bytes, colons and paths. A Python fixture covers 3 allowed and 20 refused cases with generated storage names.
A profile page lets people upload a photo. The easy version checks that the filename ends in .png, saves the file under the name the user sent, and moves on. The harder question is what else that one string can do: carry a second extension, a null byte, a colon, a path, or a name that collides with an existing file.
The OWASP File Upload Cheat Sheet starts with a list of principles. Among them: allow only the extensions the business needs, validate the file type and do not trust the Content-Type header because it can be spoofed, replace the filename with one the application generates, limit filename length and file size, and allow only authorized users to upload. It also says there is no silver bullet and that no single technique is enough.
This guide tests the first group of those rules in a small Python function. It was prepared with AI assistance and reviewed on 18 November 2026. It is a unit test for a validator, not a complete upload system.
The gate
The function accepts a filename and bytes and either returns a stored name or raises an error. Only png and pdf are allowed, each with a known leading signature. The size limit is 1,024 bytes only so the test can hit it cheaply.
NAME_OK = re.compile(r'^[A-Za-z0-9][A-Za-z0-9 \-]*\.[A-Za-z0-9]+$')
def accept(filename, data, id_factory=uuid.uuid4):
if not isinstance(filename, str) or not isinstance(data, bytes):
raise ValueError('bad input type')
if len(filename) > MAX_NAME or len(data) > MAX_BYTES or not data:
raise ValueError('size or length limit')
if not NAME_OK.fullmatch(filename):
raise ValueError('filename characters')
stem, ext = filename.rsplit('.', 1)
ext = ext.lower()
if ext not in ALLOWED:
raise ValueError('extension not allowed')
if '.' in stem:
raise ValueError('multiple extensions')
if not data.startswith(ALLOWED[ext]):
raise ValueError('signature does not match extension')
return f'{id_factory()}.{ext}'
The rules map to the cheat sheet like this:
- Allowlist, not blocklist. The sheet calls blocking extensions a weak protection on its own. The gate names what is permitted and refuses everything else.
- Case. The extension is lowercased before the comparison, so
.PDFis handled and.pHpis not a bypass. - Special characters. The character pattern excludes colons, null bytes, percent signs, slashes and leading periods. The sheet lists null bytes, colon stream syntax on Windows and double extensions among known bypasses, and warns that character rules alone do not prevent traversal. Here, user text never becomes part of the storage path.
- Server-generated name. The returned name is an ID plus the validated extension. The test checks that the user's name is not in it.
- Signature. The leading bytes must match the extension. The sheet says to use this together with other checks and not alone, because bypassing it is common.
What the run covers
Three allowed uploads pass, including an uppercase .PDF and a name with a space. Twenty refusals are asserted, including:
shell.php,x.png.php,x.php.pngandx.phtmlx.pHp, and a name with no extension- a literal null byte and a percent-encoded one before
.png shell.asp:.pngandshell.php::$DATA.htaccess,../x.pnganda/b.png- a PNG name with PDF bytes, and the reverse
- empty data, data over the limit, a 70-character name, text instead of bytes and
Noneinstead of a name
All pass on Python 3.10.12. A final check injects a fixed ID and confirms the stored name is exactly that ID plus .png.
Where this stops
Percent-encoding deserves a note. The cheat sheet says validation should run after decoding the filename. This fixture refuses the literal % character instead of decoding it, which is simpler but is a design choice to review for your framework.
A matching signature shows that the first bytes look right, not that the file is harmless. The test does not check image content, run antivirus, rewrite images, or handle ZIP and XML bombs, which the sheet lists as threats. It does not test where files are stored, how they are served, who may upload, or CSRF protection. The sheet suggests storing files outside the webroot or on a different server, and serving them through a handler that maps an ID to the file. None of that is exercised here. The Windows 8.3 short-name issue the sheet describes is avoided only because stored names are generated, and that was not tested on Windows.
How to use it
Treat the fixture as a regression list. When a new bypass shows up, add the string and see the gate refuse it. Then review the surrounding layers against the full cheat sheet.
Sources
- OWASP File Upload Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html