Title: Doc/library/tarfile.rst: document that the 'tar' extraction filter does not bound link targets · Issue #156026 · python/cpython · GitHub
Open Graph Title: Doc/library/tarfile.rst: document that the 'tar' extraction filter does not bound link targets · Issue #156026 · python/cpython
X Title: Doc/library/tarfile.rst: document that the 'tar' extraction filter does not bound link targets · Issue #156026 · python/cpython
Description: Documentation Documentation Doc/library/tarfile.rst, the "Extraction filters" section — specifically tar_filter and the 'tar' entry in the filter list. Summary The 'tar' extraction filter does not check TarInfo.linkname. A symbolic link ...
Open Graph Description: Documentation Documentation Doc/library/tarfile.rst, the "Extraction filters" section — specifically tar_filter and the 'tar' entry in the filter list. Summary The 'tar' extraction filter does not ...
X Description: Documentation Documentation Doc/library/tarfile.rst, the "Extraction filters" section — specifically tar_filter and the 'tar' entry in the filter list. Summary The 'tar' e...
Opengraph URL: https://github.com/python/cpython/issues/156026
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Doc/library/tarfile.rst: document that the 'tar' extraction filter does not bound link targets","articleBody":"### Documentation\n\n# Documentation\n\n`Doc/library/tarfile.rst`, the \"Extraction filters\" section — specifically `tar_filter` and the `'tar'` entry in the filter list.\n\n## Summary\n\nThe `'tar'` extraction filter does not check `TarInfo.linkname`. A symbolic link member whose target is an absolute path, or a relative path that climbs outside the destination, is extracted as given. Only `'data'` refuses such members.\n\nThis is deliberate and consistent with PEP 706 — **I am not proposing a behaviour change.** The problem is that the documentation never states it, and one sentence in the `tar_filter` description reads as though it does the opposite.\n\n## Where the docs mislead\n\n`tar_filter`'s third bullet currently reads:\n\n> Refuse to extract files whose absolute path (after following symlinks) would end up outside the destination. This raises `OutsideDestinationError`.\n\nThe parenthetical \"(after following symlinks)\" describes `os.path.realpath()` applied to the member's **own destination path** — i.e. symlinks that already exist in the destination tree. It reads naturally as \"symlink-related escapes are handled here\".\n\nThat link *targets* are unchecked is currently derivable only by *absence*: the reader has to notice that `data_filter` is introduced with \"In addition to what `tar_filter` does\", and that link-target containment appears only in that second list. The non-guarantee is never stated positively, so nobody reading the `tar_filter` section can learn it from that section.\n\n## Why it matters in practice\n\nI found this because five independent projects selected the `'tar'` filter (or `tarfile.tar_filter` directly) in code whose stated purpose is safe extraction, leaving link targets unbounded as a result: `unstructured-ingest`, `container-inspector`, `portage`, `poetry`, and Samba's `python/samba/safe_tarfile.py`. Each has been reported to its maintainers separately; I am raising this here because five independent readings landing the same way looks like a docs problem rather than five coincidences.\n\nSamba's case shows the mechanism most clearly, because the comment quotes the docs almost verbatim:\n\n```python\n# The 'data' filter preserves no permissions so we select the\n# intermediate 'tar' filter here which prevents escape but\n# preserves permissions.\nextraction_filter = staticmethod(tarfile.tar_filter)\n```\n\n\"which prevents escape\" is a restatement of the bullet above. That same class's pre-3.12 fallback implements `_is_unsafe_symlink()` and `_is_unsafe_link()` by hand — so the module became *less* strict when it moved to the stdlib filter, which is presumably the opposite of what was intended.\n\n## Measurement\n\nPython 3.10.12 on Linux. The harness diffs the destination tree against a pre-extraction snapshot, so a member that was never created cannot be miscounted as written, and it runs with `errorlevel=2` so nothing is silently skipped.\n\n```\nCONTROLS -- if these do not pass, nothing below means anything\n CONTROL-BENIGN plain file filter=tar -> extracted [ok]\n CONTROL-BENIGN plain file filter=data -> extracted [ok]\n CONTROL-DOTDOT member path filter=tar -> REFUSED (OutsideDestinationError) [ok]\n CONTROL-DOTDOT member path filter=data -> REFUSED (OutsideDestinationError) [ok]\n\nPAYLOADS -- symlink TARGETS\n sym -> /etc filter=tar -> LINK CREATED, POINTS OUTSIDE\n sym -> /etc filter=data -> REFUSED (AbsoluteLinkError)\n sym -> /etc/passwd filter=tar -> LINK CREATED, POINTS OUTSIDE\n sym -> /etc/passwd filter=data -> REFUSED (AbsoluteLinkError)\n sym -> ../../OUTSIDE filter=tar -> LINK CREATED, POINTS OUTSIDE\n sym -> ../../OUTSIDE filter=data -> REFUSED (LinkOutsideDestinationError)\n```\n\nThe `CONTROL-DOTDOT` row is the one that makes the rest meaningful: `tar_filter` genuinely does close the original CVE-2007-4559 path-traversal case, so \"refused\" is observable in this harness and the symlink rows are a real difference rather than a broken probe.\n\nReading through the resulting link works:\n\n```\nread through .../sandbox/lvl1/lvl2/dest/secrets\n -> /etc/passwd line 1: 'root:x:0:0:root:/root:/bin/bash'\n```\n\nStated precisely so the proposed wording is not overclaimed: writing *through* such a link with a later member in the same archive is refused (`OutsideDestinationError`), because each member path is re-resolved at extraction time. Under `'tar'` this is link placement and file read, not arbitrary write. Hard links to absolute outside paths failed here for an unrelated reason (`ExtractError` during link-target resolution), so I make no claim about them — the wording below covers symbolic links, which is what I measured.\n\n## Proposed change\n\nTwo edits, no behaviour change:\n\n1. In the filter list, the `'tar'` entry gains one clause, since that list is where the choice between `'tar'` and `'data'` is actually made:\n\n```rst\n* the string ``'tar'``: Honor most *tar*-specific features (i.e. features of\n UNIX-like filesystems), but block features that are very likely to be\n surprising or malicious. This does not include limiting the targets of\n symbolic links. See :func:`tar_filter` for details.\n```\n\n2. `tar_filter` gains a warning stating the non-guarantee positively:\n\n```rst\n .. warning::\n\n This filter does not limit where a link member *points*.\n :attr:`TarInfo.linkname` is not checked, so a symbolic link whose target\n is an absolute path, or a relative path that climbs outside the\n destination, is extracted as given.\n The rule above constrains where each member is *written*; it does not\n constrain where a link resolves to.\n\n Only :func:`data_filter` refuses such members, raising\n :class:`~tarfile.AbsoluteLinkError` or\n :class:`~tarfile.LinkOutsideDestinationError`.\n```\n\nI have this as a patch and am happy to open the PR. I care that the fact appears somewhere in the `tar_filter` section — the phrasing is entirely yours to change.\n\n\n\u003c!-- gh-linked-prs -->\n### Linked PRs\n* gh-156056\n* gh-158038\n* gh-159019\n\u003c!-- /gh-linked-prs -->\n","author":{"url":"https://github.com/drengir1","@type":"Person","name":"drengir1"},"datePublished":"2026-08-18T18:53:17Z","url":"https://github.com/python/cpython/issues/156026"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:3be669c8-3f47-73c3-e609-6243a5a1965f |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D13C:3CBB3E:3BD72C2:4C39722:6B025006 |
| html-safe-nonce | ba5aae11424cc9b80f6556aceb01d2fd54427769cdce08fac3c5b758ee5c2b7b |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEMTNDOjNDQkIzRTozQkQ3MkMyOjRDMzk3MjI6NkIwMjUwMDYiLCJ2aXNpdG9yX2lkIjoiODQ3MTI3NjA3NjMxNDgwODMyNiIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 1b854bbd6d1e68ddcbf0e8e2f2f259e173f1cb20e7c6dfe99c363c77cb91d52d |
| hovercard-subject-tag | issue:5185208728 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/cpython/156026/issue_layout |
| twitter:image | https://opengraph.githubassets.com/10cc336c712925a3d4679457ece2084ff8d765f993794caca4fd8f710ab33dea/python/cpython/issues/156026 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/10cc336c712925a3d4679457ece2084ff8d765f993794caca4fd8f710ab33dea/python/cpython/issues/156026 |
| og:image:alt | Documentation Documentation Doc/library/tarfile.rst, the "Extraction filters" section — specifically tar_filter and the 'tar' entry in the filter list. Summary The 'tar' extraction filter does not ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | drengir1 |
| hostname | github.com |
| expected-hostname | github.com |
| None | 87e774ee7c6b3bee0490394e4d3e57ec9dbc956f74b87ea685dc8996c1676456 |
| turbo-cache-control | no-preview |
| go-import | github.com/python/cpython git https://github.com/python/cpython.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 81598961 |
| octolytics-dimension-repository_nwo | python/cpython |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 81598961 |
| octolytics-dimension-repository_network_root_nwo | python/cpython |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 423dbb54c5e7bfecc838eb387c1435eb3d0e760d |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width