# Security Model for External Data in onnx-ir This document describes the threat model, implemented defenses, known limitations, and design rationale for how **onnx-ir** handles external tensor data (the `ExternalTensor` class). ## Threat model ONNX models can reference external data files via relative paths stored in the `location` field of a `TensorProto`. A malicious model could abuse this to read arbitrary files on the host. The main attack vectors are: | Vector | Example | |---|---| | **Path traversal** | `../../etc/passwd` | | **Absolute path** | `/etc/passwd` | | **Symlink escape** | `data.bin → /etc/passwd` | | **Hardlink smuggling** | Hard-linking a sensitive file into the model directory | ## Implemented defenses `ExternalTensor._check_path_containment()` enforces a three-layer check whenever a non-empty `base_dir` is set: | Layer | What it does | |---|---| | **1. String-based containment** | Normalizes the path (without resolving symlinks) and verifies it stays within `base_dir`. Catches `../` traversal and absolute paths without requiring the file to exist. | | **2. Realpath containment** | Resolves all symlinks via `os.path.realpath()` and re-checks containment. Catches symlinks whose target is outside `base_dir`. Symlinks that resolve *within* `base_dir` are allowed. | | **3. Hardlink detection** | Rejects files with more than one hard link (`st_nlink > 1`). Prevents an attacker from hard-linking a sensitive file into the model directory to bypass the containment boundary. | All three checks run at **load time** — when `numpy()`, `tofile()`, or `tobytes()` (indirectly, via `_load()`) is called — not at construction time. This allows safe deserialization of untrusted protos without triggering I/O. `save(..., external_data=...)`, `external_data.unload_from_model()`, and `save_safetensors()` also validate external source paths before writing any data. The planned external data file paths are checked before the writer publishes any files as well, so an output symlink cannot leave the saved model pointing outside its directory. An existing attribute reference is preserved only if it passes the same policy relative to the destination model directory. If a readable source cannot be referenced safely from the destination, its bytes are streamed into the new external data file instead. File identity alone does not establish that a destination reference is permitted. ## `base_dir=""` bypass (by design) When `base_dir` is empty (the default), **all security checks are skipped**. This is intentional for two reasons: 1. **Programmatic construction** — when a developer creates an `ExternalTensor` in code, they control the paths directly and do not need containment checks. 2. **Deserialization safety** — the IR deserializer may create `ExternalTensor` objects before a `base_dir` is known. Containment is only meaningful when the caller sets `base_dir` to the model's directory. If you are loading an untrusted model, always set `base_dir` to the directory containing the model file. ## Divergence from onnx/onnx The reference ONNX runtime ([onnx/onnx#7717](https://github.com/onnx/onnx/pull/7717)) implements a four-layer defense: | Layer | onnx/onnx | onnx-ir | Notes | |---|---|---|---| | 1. Canonical path containment | ✅ | ✅ | Equivalent | | 2. Symlink handling | ✅ reject all | ✅ allow within base | Different policy — see rationale below | | 3. `O_NOFOLLOW` on open | ✅ | ❌ | Planned — see *Future hardening* | | 4. Hardlink count check | ✅ | ✅ | Equivalent (added in this PR) | ### Why the differences? * **onnx-ir is a library**, not a runtime. It focuses on safe loading of model data for inspection and transformation, not sandboxed execution. * **Symlink policy** — onnx/onnx rejects all final-component symlinks. onnx-ir allows symlinks whose resolved target stays within `base_dir`. This is more permissive but still prevents escape from the containment boundary, and avoids breaking legitimate workflows that use symlinks within the model directory (e.g. shared weight files). * **`O_NOFOLLOW`** closes a TOCTOU (time-of-check-to-time-of-use) race between the containment check and the `open()` call. This is a valuable defense-in-depth measure but requires platform-specific code (`os.O_NOFOLLOW` is not available on Windows). It is planned for a future release. ## Known limitations * **TOCTOU window** — A small race exists between `_check_path_containment()` and the subsequent `open()`. An attacker who can modify the filesystem concurrently could swap a safe file for a symlink after the check passes. Mitigation: use `O_NOFOLLOW` (planned). * **`base_dir=""` bypass** — As described above, an empty `base_dir` disables all checks. Callers loading untrusted models must set `base_dir`. * **Hardlink detection is best-effort** — The `st_nlink` check only detects hard links at the time of the check. It cannot prevent hard links created after the check. On some filesystems or operating systems, `st_nlink` may not accurately reflect the number of hard links. * **Hardlink collateral** — When an attacker creates a hard link to a legitimate data file, both the original and the link get `st_nlink=2`. This means the *original* file also becomes un-loadable until the extra link is removed. This is fail-closed behavior (safe by default), but operators should be aware of it when diagnosing unexpected load failures. ## Future hardening * **`O_NOFOLLOW` on file open** — Use `os.open()` with `O_NOFOLLOW` to close the TOCTOU window at the kernel level (Linux/macOS). * **`_open_validated()` wrapper** — Centralize file-open + security checks so future code paths cannot accidentally bypass containment.