gh-156026: Document that the 'tar' filter does not bound link targets

[drengir1]

Documentation only. No behaviour change.

tar_filter does not check TarInfo.linkname, so a symbolic link member whose target is
absolute, or relative and climbing outside the destination, is extracted as given. Only
data_filter refuses those. That is consistent with PEP 706 and I am not proposing to change it —
but the docs never say it, and the containment bullet of tar_filter reads as though they do:

Refuse to extract files whose absolute path (after following symlinks) would end up outside the
destination.

"(after following symlinks)" describes realpath() on the member's own destination path, not the
link target the member creates. Today the non-guarantee is derivable only by noticing that
data_filter says "In addition to what tar_filter does" and that link-target containment appears
only in that second list.

The recently added normalization bullet sharpens this rather than covering it: it now warns that
removing internal .. components "may change the meaning of the name if it traverses symbolic
links", so the section does discuss symlinks — but only as they affect a member's own name.
linkname is still never mentioned.

This adds two things:

1. One clause in the 'tar' entry of the filter list, since that list is where the choice between
   'tar' and 'data' is actually made.
2. A .. warning:: on tar_filter stating the non-guarantee positively and pointing at
   data_filter. It is placed before the existing .. versionchanged:: note so version history
   stays last.

Motivation and the measured behaviour (with controls, and with the scope limited to symbolic links,
which is what I verified) are in #156026. Briefly: five independent projects picked 'tar' in code
whose stated purpose is safe extraction — unstructured-ingest, container-inspector, portage,
poetry, and Samba's safe_tarfile.py, whose comment "which prevents escape" is close to a
verbatim restatement of the bullet above.

No Misc/NEWS.d entry — docs-only change, so this should carry skip news.

Happy to reword any of it; I care that the fact is stated somewhere in the tar_filter section,
not about the phrasing.

• Issue: Doc/library/tarfile.rst: document that the 'tar' extraction filter does not bound link targets #156026

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34727590 | 📁 Comparing 8bfc405 against main (6893326)

  🔍 Preview build  

1 file changed

± library/tarfile.html