{"record":{"id":"dc9e205d0cb33043","repo":"docling-project/docling","slug":"resource-bundle-references-an-image-outside-the-bu","errorCode":null,"errorMessage":"Resource bundle references an image outside the bundle: {uri}","messagePattern":"Resource bundle references an image outside the bundle: (.+?)","errorType":"exception","errorClass":"ArtifactDownloadError","httpStatus":null,"severity":"error","filePath":"docling/service_client/client.py","lineNumber":1838,"sourceCode":"        and resolves relative ``Path`` URIs against the process working directory.\n        Bundle artifacts are extracted into a temporary directory, so both\n        picture and page image references must be resolved against ``base_dir``\n        explicitly before being inlined.\n        \"\"\"\n\n        base_resolved = base_dir.resolve()\n\n        def embed(image_ref: ImageRef) -> ImageRef:\n            uri = image_ref.uri\n            if not isinstance(uri, Path) or uri.is_absolute():\n                return image_ref\n            resolved = (base_dir / uri).resolve()\n            # Containment guard: the document JSON is server-supplied, so a\n            # relative URI like ``../../secret.png`` must not escape the extract\n            # dir and read arbitrary local image files. The zip-slip guard only\n            # validates ZIP members, not the URIs the JSON references.\n            if resolved != base_resolved and base_resolved not in resolved.parents:\n                raise ArtifactDownloadError(\n                    f\"Resource bundle references an image outside the bundle: {uri}\"\n                )\n            with PILImage.open(resolved) as pil_image:\n                pil_image.load()\n                return ImageRef.from_pil(pil_image.copy(), dpi=image_ref.dpi)\n\n        for item, _level in document.iterate_items(with_groups=False):\n            if isinstance(item, PictureItem) and item.image is not None:\n                item.image = embed(item.image)\n        for page in document.pages.values():\n            if page.image is not None:\n                page.image = embed(page.image)\n\n    def _build_conversion_result_from_artifact_item(\n        self,\n        item: DocumentArtifactItem,\n        document: DoclingDocument,\n        descriptor: _SourceDescriptor,","sourceCodeStart":1820,"sourceCodeEnd":1856,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/client.py#L1820-L1856","documentation":"Raised as ArtifactDownloadError during _embed_referenced_images: the server-supplied document JSON references an image with a relative URI (e.g. '../../secret.png') that resolves outside the extraction directory. The zip-slip guard only validates ZIP members, so URIs inside the JSON get their own containment check before being opened with PIL. This blocks the document JSON from reading arbitrary local image files.","triggerScenarios":"Bundle-mode convert() where a PictureItem.image.uri or page image uri is a relative Path that escapes base_dir after resolution; absolute URIs are skipped (returned as-is), only escaping relative paths trigger it.","commonSituations":"Malicious or corrupted server response crafting traversal URIs; a server bug emitting workspace-relative paths instead of bundle-relative ones.","solutions":["Read the failure from the per-document ConversionResult; the document is reported as FAILURE","Verify the docling-serve instance is trusted and up to date","Avoid referenced-image mode for untrusted service endpoints"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":"def is_artifact_download_error(exc: BaseException) -> bool:\n    return isinstance(exc, ArtifactDownloadError)","tryCatchPattern":"if res.status == ConversionStatus.FAILURE:\n    # containment violation on server-supplied URIs — do not whitelist, investigate\n    log_security_event(res.errors)","preventionTips":["Do not disable or bypass the URI containment guard — it blocks local file reads","Validate the service endpoint is trusted before enabling referenced images"],"tags":["security","path-traversal","artifact-download","service-client"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}