This document describes the security model for loading and saving external data files in ONNX models. It is intended for maintainers working on the external data code paths.

When an ONNX model references external data files via relative paths, an attacker who controls the model file can attempt:

- **Symlink traversal**: A final-component symlink in the external data path pointing to a sensitive file (e.g., `/etc/shadow`), causing ONNX to read or overwrite arbitrary files.

- **Parent-directory symlink**: A symlink in a parent directory component of the external data path, bypassing a check that only inspects the final component.

- **Hardlink attacks**: A hardlink to a sensitive file appearing as a normal file, bypassing symlink-only checks while still exposing unintended data.

- **Path traversal**: Using `..` segments or absolute paths to escape the model directory.

We use a 4-layer defense-in-depth approach. Each layer is applied at every entry point that opens external data files.

- **C++**: `std::filesystem::weakly_canonical()` resolves the path, then verifies it starts with the canonical base directory.

- **Python**: `os.path.realpath()` resolves all symlinks in the full path, then verifies the result is within the model base directory.

This catches `..` traversal and symlinks in any path component (not just the final one).

- **C++**: `std::filesystem::is_symlink(data_path)` rejects the final-component symlink.

- **Python**: `os.path.islink(path)` rejects the final-component symlink.

This is a belt-and-suspenders check alongside containment. It provides a clear, specific error message when the final path component is a symlink.

- **Python**: `os.O_NOFOLLOW` added to `os.open()` flags where available (`hasattr(os, "O_NOFOLLOW")`).

The C++ checker validates paths but does not open files, so `O_NOFOLLOW` is not applicable there. In Python, this is the last-resort defense: even if a symlink is created between the check and the open (TOCTOU race), the kernel rejects the open with `ELOOP` on Linux/macOS.

- **C++**: `std::filesystem::hard_link_count(data_path) > 1` rejects files with multiple hardlinks.

- **Python**: `os.stat(path).st_nlink > 1` rejects files with multiple hardlinks.

This prevents an attacker from using a hardlink (which is not a symlink) to point external data at a sensitive file. Note that `O_NOFOLLOW` does **not** protect against hardlinks — only this explicit check does.

Not all layers apply at every entry point. The C++ checker validates paths but does not open files, so Layer 3 (O_NOFOLLOW) is Python-only.

| Entry Point | File | Layers |

|---|---|---|

| `_resolve_external_data_location` | `onnx/checker.cc` | 1, 2, 4 |

| `load_external_data_for_tensor` | `onnx/external_data_helper.py` | 1, 2, 3, 4 |

| `save_external_data` | `onnx/external_data_helper.py` | 1, 2, 3, 4 |

| `ModelContainer._load_large_initializers` | `onnx/model_container.py` | 1, 2, 3, 4 |

The C++ checker runs first for all Python load paths (via `c_checker._resolve_external_data_location`). The Python checks serve as defense-in-depth.

There is an inherent race window between the security checks (Layers 1-2, 4) and the file open (Layer 3). An attacker with write access to the model directory could:

1. Place a legitimate file to pass checks.

2. Replace it with a symlink or hardlink between the check and the open.

**Mitigation**: `O_NOFOLLOW` (Layer 3) catches late symlink replacement on Linux/macOS at the kernel level. However, `O_NOFOLLOW` does **not** protect against hardlink replacement — this TOCTOU gap cannot be fully closed at the application level.

- `O_NOFOLLOW` is **not available** on Windows (`hasattr(os, "O_NOFOLLOW")` returns `False`). The TOCTOU window for symlink attacks is fully open on Windows, relying solely on Layers 1-2.

- Symlink and hardlink tests are skipped on Windows in the test suite.

The canonical path containment check uses string comparison. On case-insensitive filesystems (Windows NTFS, macOS HFS+), paths with different casing may incorrectly fail containment. This fails closed (false rejection, not a bypass).

Test coverage is in:

- **C++**: `onnx/test/cpp/checker_test.cc` — `SymLink*` tests for symlink detection and containment.

- **Python**: `onnx/test/test_external_data.py`:

- `TestSaveExternalDataSymlinkProtection` — save-side symlink rejection.

- `TestLoadExternalDataSymlinkProtection` — load-side symlink rejection, parent-directory symlink, `load_external_data_for_model` rejection.

- `TestLoadExternalDataHardlinkProtection` — load-side hardlink rejection.

- `TestSaveExternalDataAbsolutePathValidation` — absolute path rejection.

Symlink and hardlink tests are skipped on Windows (`os.name == "nt"`).

// Verify the resolved path stays within the base directory to prevent

// path traversal via symlinks in parent directory components.

// is_symlink() only checks the final component; a path like

// "symlink_subdir/real_file.data" would bypass it.

if (data_path_str[0] != '#') {

std::error_code ec;

auto canonical_base = std::filesystem::weakly_canonical(base_dir_path, ec);

if (ec) {

fail_check(

"Data of TensorProto ( tensor name: ",

tensor_name,

") references external data at ",

data_path_str,

", but the model directory path could not be resolved.");

}

auto canonical_data = std::filesystem::weakly_canonical(data_path, ec);

if (ec) {

fail_check(

"Data of TensorProto ( tensor name: ",

tensor_name,

") references external data at ",

data_path_str,

", but the data path could not be resolved.");

}

auto canonical_base_native = canonical_base.native();

auto canonical_data_native = canonical_data.native();

if (!canonical_base_native.empty() && canonical_base_native.back() != std::filesystem::path::preferred_separator) {

canonical_base_native += std::filesystem::path::preferred_separator;

}

if (canonical_data_native.find(canonical_base_native) != 0) {

fail_check(

"Data of TensorProto ( tensor name: ",

tensor_name,

") at ",

data_path_str,

" resolves to a location outside the model directory, "

"indicating a potential path traversal attack via symbolic links in directory components.");

}

}

def _validate_external_data_path(

base_dir: str,

data_path: str,

tensor_name: str,

*,

check_exists: bool = True,

) -> str:

"""Validate that an external data path is safe to open.

real_base = os.path.realpath(base_dir)

real_path = os.path.realpath(data_path)

if not real_path.startswith(real_base + os.sep) and real_path != real_base:

raise onnx_checker.ValidationError(

f"Tensor {tensor_name!r} external data path resolves to "

f"{real_path!r} which is outside the model directory {real_base!r}."

)

if os.path.islink(data_path):

raise onnx_checker.ValidationError(

f"Tensor {tensor_name!r} external data path {data_path!r} "

f"is a symbolic link, which is not allowed for security reasons."

)

if check_exists and os.path.exists(data_path) and os.stat(data_path).st_nlink > 1:

raise onnx_checker.ValidationError(

f"Tensor {tensor_name!r} external data path {data_path!r} "

f"has multiple hard links, which is not allowed for security reasons."

)

return data_path

# Security checks (symlink, containment, hardlink) already performed

# by C++ _resolve_external_data_location() above.

# Use O_NOFOLLOW where available as defense-in-depth for symlink protection

open_flags = os.O_RDONLY

if hasattr(os, "O_NOFOLLOW"):

open_flags |= os.O_NOFOLLOW

fd = os.open(external_data_file_path, open_flags)

with os.fdopen(fd, "rb") as data_file:

# C++ _resolve_external_data_location() cannot be used on save path

# (file may not exist yet), so Python performs its own security validation.

_validate_external_data_path(

base_path, external_data_file_path, tensor.name, check_exists=True

)

# Security checks (symlink, containment, hardlink) already performed

# by C++ _resolve_external_data_location() above.

# Use O_NOFOLLOW where available for symlink protection

open_flags = os.O_RDONLY

if hasattr(os, "O_NOFOLLOW"):

open_flags |= os.O_NOFOLLOW

fd = os.open(external_data_file_path, open_flags)

with os.fdopen(fd, "rb") as data_file:

#include <fstream>

#if !defined(ONNX_NO_EXCEPTIONS) && !defined(_WIN32)

// Use a temp directory as the base_dir (simulating the model directory).

// We pass a relative filename as the location so that the absolute-path

// rejection (checker.cc line 986) is NOT triggered, and the is_symlink()

// check (checker.cc line 1016) is actually exercised.

fs::path modelDir = fs::temp_directory_path() / "onnx_symlink_checker_test";

fs::remove_all(modelDir);

fs::create_directories(modelDir);

// Create a regular target file so the symlink has a valid target.

fs::path target = modelDir / "target.data";

{

std::ofstream ofs(target);

ofs << "test data";

}

// Create a symlink pointing to the target file.

fs::path link = modelDir / "link.data";

// Pass relative filename "link.data" — the checker resolves it to

// modelDir/link.data and should reject it because it is a symlink.

EXPECT_THROW(

ONNX_NAMESPACE::checker::resolve_external_data_location(modelDir.string(), "link.data", "tensor_name"),

ONNX_NAMESPACE::checker::ValidationError);

fs::remove_all(modelDir);

}

TEST(CHECKER, ValidDataLocationParentDirSymLinkTest) {

#if !defined(ONNX_NO_EXCEPTIONS) && !defined(_WIN32)

// Test that symlinks in parent directory components are detected.

// A location like "symlink_subdir/real_file.data" where symlink_subdir

// is a symlink to an outside directory should be rejected by the

// canonical path containment check in checker.cc.

fs::path modelDir = fs::temp_directory_path() / "onnx_parent_symlink_test";

fs::remove_all(modelDir);

fs::create_directories(modelDir);

// Create a target directory outside the model directory.

fs::path outsideDir = fs::temp_directory_path() / "onnx_outside_target";

fs::remove_all(outsideDir);

fs::create_directories(outsideDir);

// Create a real file in the outside directory.

fs::path targetFile = outsideDir / "secret.data";

{

std::ofstream ofs(targetFile);

ofs << "sensitive data";

}

// Create a directory symlink inside modelDir pointing outside.

fs::path symlinkSubdir = modelDir / "subdir";

fs::create_directory_symlink(outsideDir, symlinkSubdir);

// "subdir/secret.data" is a relative path where "subdir" is a symlink.

// The canonical path resolves outside modelDir, so this should be rejected.

ONNX_NAMESPACE::checker::resolve_external_data_location(modelDir.string(), "subdir/secret.data", "tensor_name"),

fs::remove_all(modelDir);

fs::remove_all(outsideDir);