When to use this upload hardening path

A Flask blog only needs a very small upload feature at first: the admin editor can attach a cover image, inline images render, and the saved path can be served back to readers. That is enough for a personal site in its first phase. It is not enough for a site that publishes continuously, runs behind Nginx and Gunicorn, and keeps months of uploaded files in production.

At that point, image upload becomes a production entry point. It can consume disk, pin CPU during image decoding, hide failed writes behind generic 400 responses, and create incidents that are hard to reconstruct later. The real question is no longer “can the site upload an image?” It becomes “what boundary stops a malformed file, a stale session, or a bad deployment before it hurts the system?”

This Stepnex project already has a solid baseline: MAX_CONTENT_LENGTH, an explicit image extension allowlist, secure_filename(), a UUID-based final filename, monthly upload directories under static/uploads/, and Pillow-based resizing and re-encoding for most formats. That is already stronger than saving the original file directly. The remaining work is production hardening: proxy limits, content validation, decompression-bomb protection, upload log signals, and a repeatable review path.

If you recently tightened admin access with the existing Flask admin RBAC and Nginx safety net article, this is the next step. Admin controls define who may enter the backend. Upload hardening defines what a backend session can do when it sends a file.

Design choices: tighten boundaries before adding heavy systems

It is easy to overbuild uploads too early. Object storage, async workers, malware scanning, and media pipelines all have their place, but they are not the first controls a small Flask blog needs. A more stable order is simpler: define payload limits, define file-type limits, randomize storage names, verify image contents, cap dimensions, add useful log output, and make the validation steps repeatable. Only after that should you decide whether the site really needs separate storage or asynchronous processing.

Four design choices matter most.

First, an extension allowlist is only an early filter. It rejects obviously irrelevant files, but it does not prove the content is a safe image. Second, filenames are never trusted input. Even after secure_filename(), the final stored filename should still be random. Third, Flask limits and Nginx limits should both exist. The application must know the expected maximum, but the proxy should reject obviously oversized requests before the app spends work on them. Fourth, logs should keep operational signals rather than full private content. You need enough data for review, not a second unsafe copy of user input.

Step 1: make the baseline explicit in configuration

Before changing code, make the upload boundaries readable. In this project the important settings already live together:

MAX_CONTENT_LENGTH = int(os.getenv("MAX_CONTENT_LENGTH", 8 * 1024 * 1024))
UPLOAD_FOLDER = str(BASE_DIR / "static" / "uploads")
ALLOWED_IMAGE_EXTENSIONS = {"jpg", "jpeg", "png", "gif", "webp"}
IMAGE_MAX_DIMENSION = int(os.getenv("IMAGE_MAX_DIMENSION", 1600))
IMAGE_JPEG_QUALITY = int(os.getenv("IMAGE_JPEG_QUALITY", 82))
IMAGE_WEBP_QUALITY = int(os.getenv("IMAGE_WEBP_QUALITY", 82))

That matters because maintainable upload behavior needs a clear configuration source. If size limits live partly in JavaScript, partly in Flask, and partly in Nginx, future changes become guesswork.

Mirror the same boundary at the proxy. The upload route should not share one generic request-body limit with every other page:

location /admin/upload {
    client_max_body_size 8m;
    proxy_pass http://127.0.0.1:5000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Then run a command-based check immediately:

sudo nginx -t
sudo systemctl reload nginx
curl -I https://stepnex.cn/admin/login

The first validate checkpoint is not upload success. It is configuration correctness. A broken location block is a more common production failure than a truly dangerous image.

Step 2: keep the allowlist and random filename as the minimum safe baseline

The first application-layer filter should still be simple and explicit:

def allowed_file(filename: str) -> bool:
    suffix = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
    return suffix in Config.ALLOWED_IMAGE_EXTENSIONS

This does not prove a file is safe. It rejects clearly irrelevant formats early and gives the operator a clear failure reason. That alone reduces accidental misuse and noisy probing.

The storage path still needs two more steps: sanitize the original name and then stop using it as the final public path:

original_name = secure_filename(file_storage.filename)
suffix = Path(original_name).suffix.lower()
month_dir = datetime.utcnow().strftime("%Y%m")
filename = f"{uuid.uuid4().hex}{suffix}"
save_path = upload_dir / filename

The distinction matters. secure_filename() is about filesystem-safe input. A UUID filename is about collision avoidance, guess resistance, and avoiding public URLs that leak editorial naming habits. Treat them as complementary controls, not substitutes.

A common pitfall is to believe a sanitized original filename is already safe enough. It is not. Even a sanitized name can collide with an existing file or create predictable URLs. If the original filename is useful for review, keep it in metadata instead of the final path.

Step 3: let Pillow validate content and normalize output

A .png suffix does not guarantee that the upload is a real PNG image. The more reliable path is to force the file through a real image parser before accepting it. This project already does that with Pillow:

with Image.open(file_storage.stream) as image:
    image.load()
    if suffix == ".gif":
        file_storage.stream.seek(0)
        file_storage.save(save_path)
    else:
        image = ImageOps.exif_transpose(image)
        image.thumbnail((Config.IMAGE_MAX_DIMENSION, Config.IMAGE_MAX_DIMENSION))
        if image.mode not in {"RGB", "RGBA"}:
            image = image.convert("RGB")
        image.save(save_path, **save_kwargs)

That already provides three useful controls. The file contents are actually parsed. Most formats are re-encoded into a normalized output path. Oversized images are reduced before they become large front-end assets.

For stronger production hardening, add a validation pass before the transformation pass:

import warnings
from PIL import Image

warnings.simplefilter("error", Image.DecompressionBombWarning)

with Image.open(file_storage.stream) as probe:
    probe.verify()

file_storage.stream.seek(0)
with Image.open(file_storage.stream) as image:
    image.load()

The design choice here is intentional. verify() is a good preflight check. load() is the right step once the file moves into resizing and output generation. IMAGE_MAX_DIMENSION should also be reviewed as a security boundary, not only a presentation setting. A relatively small compressed file can still expand into a very large pixel surface during decoding.

Step 4: connect upload handling to auth, CSRF, and log review

The upload route is /admin/upload, so it is inseparable from backend security. The current project already uses login checks and CSRF validation:

@app.route("/admin/upload", methods=["POST"])
@login_required
def admin_upload():
    if not validate_csrf(header=True):
        abort(400)
    file = request.files.get("image")

That is the correct baseline, but long-term maintenance needs more than a 400 response. You need to know whether a failure came from an extension check, invalid image content, a CSRF problem, or a write error. You also need enough signal to review who uploaded, when it happened, and whether failures suddenly increased.

A small log line is usually enough:

current_app.logger.info(
    "admin_upload result=%s user_id=%s content_length=%s path=%s",
    result,
    current_user.id,
    request.content_length,
    request.path,
)

If the backend later adds more roles, upload permission should be reviewed with article-editing permission rather than granted to every authenticated account by default. This is where operational log review becomes important: it ties failure patterns, user activity, and permission design together.

Performance and security: review commands and log signals together

Upload issues often appear first as performance instability. Nginx or Flask may return repeated 413 responses. Very large images may stall a Gunicorn worker during decoding. The editor may retry failed uploads and multiply concurrency. Even successful uploads can hurt page speed later if the stored assets remain too large.

That is why validation should pair command checks with logs:

curl -i -b cookie.txt -c cookie.txt -F "image=@test.webp" https://stepnex.cn/admin/upload
curl -i -b cookie.txt -F "image=@oversize.jpg" https://stepnex.cn/admin/upload
sudo tail -n 50 /var/log/nginx/access.log
sudo tail -n 50 /var/log/nginx/error.log
journalctl -u blog -n 100 --no-pager

The validate goal is not only “did the request return 200?” It is “does each failure branch tell a coherent story?” Oversized requests, invalid-image failures, and write failures should look different in the app log and the proxy log. If the log cannot distinguish those paths, future review becomes expensive and unreliable.

Automation, maintenance, and the weekly review loop

The most stable hardening work is the work that does not depend on memory. Put upload checks into the deployment routine. After release, upload one normal image, one file above the configured limit, and one renamed non-image file. Confirm the expected result for each case and review the corresponding log entry.

If the site already uses publishing automation, add a lightweight preflight checklist: verify that MAX_CONTENT_LENGTH exists, the upload directory is present, the Nginx site includes a dedicated /admin/upload body limit, and recent logs do not show a sudden spike in invalid-image failures. That level of automation is cheap and still very effective.

Do not forget storage review either. Keep the upload directory in the same operational review as database backups and deployment checks. Images are part of the content asset, not an optional extra.

The main pitfall list is short:

  • Do not confuse an extension allowlist with full content validation.
  • Do not keep the original filename as the final public path.
  • Do not rely only on Flask limits while leaving Nginx effectively unbounded.
  • Do not collapse every failure into the same generic response without a useful log signal.
  • Do not ignore GIF’s different handling path if other formats are re-encoded.
  • Do not review only app logs when static delivery depends on Nginx too.

For the weekly review, ask only a few questions: did the upload failure rate change, where are failures concentrated, is storage growth expected, did admin behavior change, and did the latest deployment touch upload settings or static paths? That is the long-term progression in practice: basic usability first, then production hardening, then performance and security review, then automation and maintenance, then a compact review checklist that keeps the system understandable over time.