fix(dataset): reject COCO annotations whose file_name escapes the images directory (#2218)

* test: add regression tests for COCO loader path containment
* fix: reject COCO annotations whose file_name escapes the images directory
* docs: document ValueError contract in load_coco_annotations
* test: cover COCO equality-guard branch (file_name → images dir)
* test: cover COCO is_dir-guard branch (file_name → subdirectory)
* fix: wrap Path.resolve() for untrusted file_name in try/except
* test: add positive test for valid nested file_name in COCO loader
* test: add missing docstrings to COCO path-containment tests
* test: add `from __future__ import annotations` to JSON and CSV tests
* fix: replace `os.path.join` with `Path` for consistent path handling in COCO loader

---------

Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
This commit is contained in:
Junghwan
2026-04-18 00:58:44 +02:00
committed by GitHub
co-authored by Jirka Borovec Copilot Claude Code
parent 8df86e2599
commit 6beabe3fb4
2 changed files with 178 additions and 2 deletions
+41 -2
View File
@@ -1,4 +1,3 @@
import os
import warnings
from datetime import datetime
from pathlib import Path
@@ -278,6 +277,19 @@ def load_coco_annotations(
Returns:
A tuple of `(classes, image_paths, annotations)`.
Raises:
ValueError: If any annotation's ``file_name`` resolves to the images
directory itself, to a path outside the images directory (e.g. via
``../`` traversal or an absolute path), or to a subdirectory instead
of a regular image file.
Note:
Each annotation's ``file_name`` is validated against
``images_directory_path`` before loading. Annotations that reference
paths outside the directory are rejected to prevent path-traversal
attacks when loading user-supplied annotation files. Symlinked images
pointing outside the resolved images directory are also rejected.
"""
coco_data = read_json_file(file_path=annotations_path)
classes = coco_categories_to_classes(coco_categories=coco_data["categories"])
@@ -293,6 +305,7 @@ def load_coco_annotations(
images = []
annotations = {}
images_directory_resolved = Path(images_directory_path).resolve()
for coco_image in coco_images:
image_name, image_width, image_height = (
@@ -301,7 +314,33 @@ def load_coco_annotations(
coco_image["height"],
)
image_annotations = coco_annotations_groups.get(coco_image["id"], [])
image_path = os.path.join(images_directory_path, image_name)
image_path = str(Path(images_directory_path) / Path(image_name))
try:
resolved_image_path = Path(image_path).resolve()
except (OSError, ValueError) as exc:
raise ValueError(
f"COCO annotation refers to image {image_name!r}, which "
f"produces an invalid path: {exc}"
) from exc
if resolved_image_path == images_directory_resolved:
raise ValueError(
f"COCO annotation refers to image {image_name!r}, which "
f"resolves to the images directory itself "
f"({images_directory_resolved}). Expected a path to an "
"image file."
)
if images_directory_resolved not in resolved_image_path.parents:
raise ValueError(
f"COCO annotation refers to image {image_name!r}, which "
f"resolves to {resolved_image_path} — outside the images "
f"directory {images_directory_resolved}."
)
if resolved_image_path.is_dir():
raise ValueError(
f"COCO annotation refers to image {image_name!r}, which "
f"resolves to directory {resolved_image_path}. Expected a "
"path to an image file."
)
with_masks = force_masks or any(
_with_seg_mask(annotation) for annotation in image_annotations
+137
View File
@@ -1157,6 +1157,143 @@ def test_load_coco_annotations_force_masks_with_no_annotations(
assert annotations[no_annotations_path] == Detections.empty()
@pytest.mark.parametrize(
"file_name",
[".", "", "subdir/.."],
)
def test_load_coco_annotations_rejects_file_name_resolving_to_images_directory(
tmp_path,
file_name: str,
) -> None:
"""Reject file_name resolving to the images directory itself (equality guard)."""
images_directory = tmp_path / "images"
images_directory.mkdir()
annotations_path = tmp_path / "annotations.json"
coco_data = {
"categories": [{"id": 1, "name": "object", "supercategory": "none"}],
"images": [{"id": 1, "file_name": file_name, "width": 5, "height": 5}],
"annotations": [],
}
annotations_path.write_text(json.dumps(coco_data), encoding="utf-8")
with pytest.raises(ValueError, match="resolves to the images directory itself"):
load_coco_annotations(
images_directory_path=str(images_directory),
annotations_path=str(annotations_path),
)
@pytest.mark.parametrize(
"malicious_file_name",
[
"../escape.txt",
"../../escape.txt",
"subdir/../../escape.txt",
],
)
def test_load_coco_annotations_rejects_file_name_outside_images_directory(
tmp_path,
malicious_file_name: str,
) -> None:
"""Reject relative traversal file_name values that escape the images directory."""
images_directory = tmp_path / "images"
images_directory.mkdir()
annotations_path = tmp_path / "annotations.json"
coco_data = {
"categories": [{"id": 1, "name": "object", "supercategory": "none"}],
"images": [
{
"id": 1,
"file_name": malicious_file_name,
"width": 5,
"height": 5,
}
],
"annotations": [],
}
annotations_path.write_text(json.dumps(coco_data), encoding="utf-8")
with pytest.raises(ValueError, match="outside the images directory"):
load_coco_annotations(
images_directory_path=str(images_directory),
annotations_path=str(annotations_path),
)
def test_load_coco_annotations_rejects_absolute_file_name(tmp_path) -> None:
"""Reject absolute file_name values that escape the images directory."""
images_directory = tmp_path / "images"
images_directory.mkdir()
annotations_path = tmp_path / "annotations.json"
coco_data = {
"categories": [{"id": 1, "name": "object", "supercategory": "none"}],
"images": [
{
"id": 1,
"file_name": "/etc/passwd",
"width": 5,
"height": 5,
}
],
"annotations": [],
}
annotations_path.write_text(json.dumps(coco_data), encoding="utf-8")
with pytest.raises(ValueError, match="outside the images directory"):
load_coco_annotations(
images_directory_path=str(images_directory),
annotations_path=str(annotations_path),
)
def test_load_coco_annotations_rejects_file_name_resolving_to_directory(
tmp_path,
) -> None:
"""Reject file_name resolving to a subdirectory inside images/ (is_dir guard)."""
images_directory = tmp_path / "images"
images_directory.mkdir()
(images_directory / "subdir").mkdir()
annotations_path = tmp_path / "annotations.json"
coco_data = {
"categories": [{"id": 1, "name": "object", "supercategory": "none"}],
"images": [{"id": 1, "file_name": "subdir", "width": 5, "height": 5}],
"annotations": [],
}
annotations_path.write_text(json.dumps(coco_data), encoding="utf-8")
with pytest.raises(ValueError, match="resolves to directory"):
load_coco_annotations(
images_directory_path=str(images_directory),
annotations_path=str(annotations_path),
)
def test_load_coco_annotations_accepts_valid_nested_file_name(tmp_path) -> None:
"""Accept a legitimate nested file_name inside images/ without raising."""
images_directory = tmp_path / "images"
images_directory.mkdir()
(images_directory / "train").mkdir()
annotations_path = tmp_path / "annotations.json"
coco_data = {
"categories": [{"id": 1, "name": "object", "supercategory": "none"}],
"images": [{"id": 1, "file_name": "train/image.jpg", "width": 5, "height": 5}],
"annotations": [],
}
annotations_path.write_text(json.dumps(coco_data), encoding="utf-8")
_, _, annotations = load_coco_annotations(
images_directory_path=str(images_directory),
annotations_path=str(annotations_path),
)
expected_path = str(images_directory / "train" / "image.jpg")
assert expected_path in annotations
def test_load_coco_annotations_force_masks_handles_missing_segmentation(
tmp_path,
) -> None: