Summary
NiceGUI's FileUpload.name property exposes client-supplied filenames without sanitization, which can lead to path traversal when application code directly concatenates this value into filesystem paths.
If a NiceGUI application follows the common pattern UPLOAD_DIR / file.name without validation, an attacker can craft filenames with ../ sequences to write files outside the intended upload directory, potentially overwriting application files and enabling remote code execution in certain deployment setups.
Affected context
The vulnerability affects NiceGUI-based applications that:
- Use the
FileUpload.nameattribute directly when constructing filesystem paths, e.g.,UPLOAD_DIR / file.name - Do not sanitize or normalize the filename before writing to disk
- Run in environments where the application process has write permissions beyond the intended upload directory
Applications that ignore client-supplied filenames, generate their own safe names, or apply strict sanitization of filenames are generally not affected by this issue.
Exploit preconditions
- Attack surface: HTTP(S) endpoints or UI routes that accept file uploads via NiceGUI's
FileUploadcomponent. - Required access: Ability to submit file uploads to the affected endpoint (often unauthenticated in public-facing applications).
- Trigger point: Application file write operations that use expressions like
UPLOAD_DIR / file.nameor equivalent direct concatenation ofFileUpload.nameinto paths. - Why exploitation is possible: The framework exposes
FileUpload.namedirectly from client input without normalization or restriction, and many example/community patterns encourage its direct use when forming filesystem paths. When combined with permissive filesystem permissions,../segments in filenames can traverse out of the intended directory and land in arbitrary locations.
Why this happens
This is a design-level path traversal issue aligned with CWE-22: Improper Limitation of a Pathname to a Restricted Directory.
The framework exposes a filename property that is entirely controlled by the client and does not enforce:
- Removal of directory traversal sequences (e.g.,
../,..\) - Restriction to a specific directory or path prefix
- Normalization and validation against an allowed set of characters or patterns
Because the common and documented usage pattern is to construct paths as UPLOAD_DIR / file.name, developers may inadvertently trust this metadata as safe. In this pattern, the application implicitly treats user-controlled filenames as trustworthy components of filesystem paths, allowing crafted values to escape the intended directory boundary.
Potential impact
- Writing files outside the intended upload directory
- Overwriting existing application files, static assets, or configuration files
- Planting executable scripts or code artifacts in web-accessible or runtime-loaded locations
- Elevating impact to remote code execution in deployments where overwritten files are executed or interpreted by the application stack
- Tampering with logs, data files, or other sensitive resources the application user can write to
General mitigation guidance
Effective mitigation focuses on decoupling filesystem paths from untrusted filenames and strictly constraining where uploaded files can be written. Common defensive patterns include:
- Generating server-side filenames:
- Use randomly generated identifiers, UUIDs, or monotonically increasing counters instead of client-supplied names.
- Store the original client filename only as metadata in a database or separate mapping, not as part of the filesystem path.
- Enforcing strict path constraints:
- Resolve the target path and verify that it remains within the designated upload directory after normalization.
- Reject or rewrite filenames that contain directory separators, traversal sequences, or non-printable characters.
- Applying robust input validation:
- Allow only a restricted character set (e.g., alphanumerics plus a small whitelist of safe symbols).
- Limit filename length and strip or replace suspicious patterns such as
../,..\,~/, or absolute path prefixes.
- Hardening filesystem permissions:
- Run the application with a dedicated OS user restricted to a narrow directory tree.
- Ensure the upload directory is isolated and does not overlap with code, configuration, or template directories.
These measures reduce the risk even when client-supplied filenames are exposed by the framework.
How teams detect issues like this
Detection typically combines code-level inspection with configuration review:
- Static analysis and linting:
- Search for direct uses of
file.name,FileUpload.name, or equivalent properties in path-building expressions. - Flag patterns where user-controlled filename data is concatenated or interpolated into filesystem paths.
- Use custom rules in SAST tools to detect
../-prone path construction and missing normalization/validation steps.
- Code review practices:
- Review all file upload handlers to verify that filenames are generated server-side or sanitized.
- Examine helper utilities and shared modules that create upload paths for misuse of user-supplied metadata.
- Runtime and policy enforcement:
- Monitor application logs for suspicious filenames containing traversal characters or patterns.
- Use filesystem monitoring to detect writes outside intended upload directories by the application process.
Automated code review tools can be configured to flag insecure path-building patterns around file uploads in NiceGUI projects.

