diff --git a/src/supervision/dataset/formats/coco.py b/src/supervision/dataset/formats/coco.py index aa99f0aa..709a1b0a 100644 --- a/src/supervision/dataset/formats/coco.py +++ b/src/supervision/dataset/formats/coco.py @@ -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 diff --git a/tests/dataset/formats/test_coco.py b/tests/dataset/formats/test_coco.py index cf554fbf..5965b674 100644 --- a/tests/dataset/formats/test_coco.py +++ b/tests/dataset/formats/test_coco.py @@ -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: