Heuristic:Onnx Onnx External Data Path Security
| Knowledge Sources | |
|---|---|
| Domains | Security, External_Data |
| Last Updated | 2026-02-10 02:00 GMT |
Overview
External data file paths must be relative to the model file; absolute paths and directory traversal (`..`) are rejected as security measures.
Description
When ONNX models use external data storage, each tensor stores a `location` field that points to the external file containing its raw data. The ONNX library enforces strict path validation rules on these location fields: they must be relative paths (not absolute), must not contain `..` path components (preventing directory traversal), and must have valid filenames (not `.` or `..`). These constraints prevent a malicious model from reading arbitrary files on the filesystem when loaded.
Usage
Use this heuristic when:
- Creating models with external data to ensure paths are correctly formatted
- Debugging `ValidationError` from external data loading
- Building tools that process ONNX models with external data
- Understanding security implications of loading untrusted ONNX models
The Insight (Rule of Thumb)
- Action: Always use simple relative filenames (e.g., `"model_weights.data"` or `"weights/layer1.bin"`) for external data locations. Never use absolute paths or `..` in the path.
- Value: All external data files must reside in the same directory as the model file or in subdirectories thereof.
- Trade-off: This limits flexibility in organizing external data files but prevents path traversal attacks. If you need to reference data outside the model directory, copy or symlink the data instead.
Reasoning
When a user or runtime loads an ONNX model, the external data handler automatically reads files from the paths specified in the model. Without path validation, a malicious model could contain a tensor with `location="/etc/passwd"` or `location="../../secret/data"` and trick the runtime into reading sensitive files. The validation catches three specific attack vectors:
- Absolute paths: `location_path.is_absolute()` rejects paths like `/etc/passwd`
- Directory traversal: `".." in location_path.parts` rejects paths like `../../secret`
- Invalid names: `location_path.name in (".", "..")` rejects degenerate path names
Code evidence from `onnx/external_data_helper.py:201-218`:
location_path = pathlib.Path(info.location)
if location_path.is_absolute() and len(location_path.parts) > 1:
raise onnx_checker.ValidationError(
f"Tensor {tensor.name!r} is external and must not be defined "
f"with an absolute path such as {info.location!r}, "
f"base_path={base_path!r}"
)
if ".." in location_path.parts:
raise onnx_checker.ValidationError(
f"Tensor {tensor.name!r} is external and must be placed in folder "
f"{base_path!r}, '..' is not needed in {info.location!r}."
)
if location_path.name in (".", ".."):
raise onnx_checker.ValidationError(
f"Tensor {tensor.name!r} is external and its name "
f"{info.location!r} is invalid."
)