Secure Filenames

Never trust a user-provided filename.

Attackers can try things like:

• ../../etc/passwd
• special characters that break file systems

Flask/Werkzeug provides secure_filename().

diagram what a user-supplied filename can do, and what secure_filename leaves mermaid

  flowchart TD
  A["file.filename from the request"] --> B{"used as-is?"}
  B -->|yes| C["os.path.join(UPLOAD_DIR, '../../../etc/passwd')"]
  C --> D["the write escapes the upload directory"]
  B -->|no| E["secure_filename(name)"]
  E --> F["path separators and .. removed"]
  F --> G["'etc_passwd' -- a flat, safe name"]
  G --> H{"is the result empty?"}
  H -->|yes| I["reject the upload -- there is no filename left"]
  H -->|no| J["still check the extension and the size"]
  J --> K["save under a name YOU control, e.g. a uuid"]

A filename arrives as a string the attacker chose. If it is joined onto an upload directory unchecked, path segments in it escape that directory and the write lands somewhere else. secure_filename strips the path, normalises the characters and leaves a flat name -- which is necessary, and on its own not sufficient.

What secure_filename actually returns — and the empty-string trap

Run against Werkzeug 3.1.8:

Input	Result
../../../etc/passwd	etc_passwd
..\..\windows\system32\config\sam	windows_system32_config_sam
....//....//evil.sh	evil.sh
my report.pdf	my_report.pdf
résumé.pdf	resume.pdf
.hidden	hidden
CON.txt	_CON.txt
""	""

Two of these are worth pausing on.

CON.txt becomes _CON.txt. CON is a reserved device name on Windows, and a file with that name cannot be created normally — Werkzeug prefixes an underscore so the write succeeds.

An empty input gives an empty string, and so does a name made entirely of characters it strips. os.path.join(UPLOAD_DIR, "") is just the directory, so an unchecked save can fail in a confusing way or overwrite something unexpected. Always check the result is non-empty before using it.

And secure_filename is about the path, not the contents. It does not check the extension, the size, or whether the bytes are really an image. A file called avatar.png can hold anything at all.

Example

python

import os
from werkzeug.utils import secure_filename
from flask import Flask, request
 
app = Flask(__name__)
 
UPLOAD_FOLDER = "uploads"
 
 
@app.route("/upload", methods=["POST"])
def upload():
    file = request.files.get("photo")
    if not file:
        return "No file", 400
 
    filename = secure_filename(file.filename)
    os.makedirs(UPLOAD_FOLDER, exist_ok=True)
    save_path = os.path.join(UPLOAD_FOLDER, filename)
    file.save(save_path)
 
    return {"saved_as": filename}, 201

Best practices for production

• Rename uploaded files (UUID) instead of using original name
• Store metadata in DB (who uploaded, when, original name)
• Set an upload size limit (MAX_CONTENT_LENGTH)
• Validate extensions and MIME type
• Consider storing files in object storage (S3) rather than the app server