Setzt einen Präzedenzfall

Wenn und wenn andere Bibliotheken für die Archivextraktion, wie z. B. zipfile, ähnliche Funktionalität erhalten, sollten sie diese API, soweit sinnvoll, nachahmen.

Um dies für einfache Fälle zu ermöglichen, erhalten die integrierten Filter Zeichenkettennamen; z. B. können Benutzer filter='data' anstelle einer spezifischen Funktion übergeben, die mit TarInfo-Objekten arbeitet.

Die Funktion shutil.unpack_archive() erhält ein filter-Argument, das sie an extractall weiterleitet.

Das Hinzufügen einer funktionsbasierten API, die über Archivformate hinweg funktioniert, liegt außerhalb des Rahmens dieses PEP.

Volle Offenlegung & Informationen für Weiterverteiler

Der PEP-Autor arbeitet für Red Hat, einen Weiterverteiler von Python mit anderen Sicherheitsanforderungen und Support-Zeiträumen als CPython im Allgemeinen. Solche Weiterverteiler möchten möglicherweise Vendor-Patches mitführen, um

• die Standardwerte systemweit konfigurieren zu können und
• den Standard so schnell wie möglich zu ändern, auch in älteren Python-Versionen.

Der Vorschlag macht dies einfach und ermöglicht es Benutzern, die Einstellungen abzufragen.

Ändern und Vergessen von Member-Metadaten

Die Klasse TarInfo erhält eine neue Methode, replace(), die ähnlich wie dataclasses.replace funktioniert. Sie gibt eine Kopie des TarInfo-Objekts zurück, mit Attributen, die als schlüsselwortbasierte Argumente ersetzt werden.

• name
• mtime
• Modus
• linkname
• uid
• gid
• uname
• gname

Jeder dieser Werte, außer name und linkname, darf auf None gesetzt werden. Wenn extract oder extractall auf ein solches None trifft, wird dieser Metadatenwert nicht gesetzt. (Wenn uname oder gname None ist, wird auf uid bzw. gid zurückgegriffen, als ob der Name nicht gefunden worden wäre.) Wenn addfile oder tobuf auf ein solches None trifft, löst es einen ValueError aus. Wenn list auf ein solches None trifft, wird ein Platzhalterstring gedruckt.

Die Dokumentation wird den Grund für die Existenz der Methode erwähnen: TarInfo-Objekte, die von TarFile.getmembers abgerufen werden, sind „live“; ihre direkte Änderung wirkt sich auf nachfolgende, nicht zusammenhängende Operationen aus.

Filter

Die Methoden TarFile.extract und TarFile.extractall erhalten einen schlüsselwortbasierten Parameter filter, der einen aufrufbaren Wert annimmt, der aufgerufen werden kann als

filter(/, member: TarInfo, path: str) -> TarInfo|None

wobei member das zu extrahierende Mitglied ist und path der Pfad ist, zu dem das Archiv extrahiert wird (d. h. er ist für jedes Mitglied gleich).

Wenn es verwendet wird, wird es bei jedem zu extrahierenden Mitglied aufgerufen, und die Extraktion funktioniert mit dem Ergebnis. Wenn es None zurückgibt, wird das Mitglied übersprungen.

Die Funktion kann auch eine Ausnahme auslösen. Dies kann, abhängig von TarFile.errorlevel, die Extraktion abbrechen oder dazu führen, dass das Mitglied übersprungen wird.

Wir werden auch eine Reihe von Standardwerten für gängige Anwendungsfälle bereitstellen. Zusätzlich zu einer Funktion kann das filter-Argument eine der folgenden Zeichenketten sein:

• 'fully_trusted': Aktuelles Verhalten: Metadaten unverändert übernehmen. Sollte verwendet werden, wenn der Benutzer dem Archiv vollständig vertraut oder seine eigene komplexe Verifizierung implementiert.
• 'tar': Verhält sich ungefähr wie die Standardeinstellungen des GNU tar-Befehls (wenn er als normaler Benutzer ausgeführt wird)
  • Entfernt führende '/' und os.sep aus Dateinamen
  • Verweigert die Extraktion von Dateien mit absoluten Pfaden (nach dem obigen Entfernen von /, z. B. C:/foo unter Windows).
  • Verweigert die Extraktion von Dateien, deren absoluter Pfad (nach dem Auflösen von Symlinks) außerhalb des Ziels liegt. (Beachten Sie, dass GNU tar stattdessen die Erstellung einiger Links verzögert.)
  • Löscht hohe Modusbits (setuid, setgid, sticky) und Gruppen-/andere Schreibbits (S_IWGRP|S_IWOTH). (Dies ist eine Annäherung an die Standardeinstellung von GNU tar, die den Modus anhand der aktuellen umask-Einstellung begrenzt.)
• 'data': Extrahiert ein „Daten“-Archiv, verbietet gängige Angriffsvektoren, schränkt aber die Funktionalität ein. Insbesondere werden viele Funktionen, die für UNIX-ähnliche Dateisysteme (oder gleichwertig, für das tar-Archivformat) spezifisch sind, ignoriert, was dies zu einem guten Filter für plattformübergreifende Archive macht. Zusätzlich zu tar:
  • Verweigert die Extraktion von Links (hart oder symbolisch), die auf absolute Pfade verweisen.
  • Verweigert die Extraktion von Links (hart oder symbolisch), die auf einen Pfad außerhalb des Ziels verweisen. (Auf Systemen, die keine Links unterstützen, fällt tarfile in den meisten Fällen auf die Erstellung regulärer Dateien zurück. Dieser Vorschlag ändert dieses Verhalten nicht.)
  • Verweigert die Extraktion von Gerätedateien (einschließlich Pipes).
  • Für reguläre Dateien und Hardlinks
    • Setzt die Lese- und Schreibberechtigungen des Besitzers (S_IRUSR|S_IWUSR).
    • Entfernt die Gruppen- & anderen ausführbaren Berechtigungen (S_IXGRP|S_IXOTH), wenn der Besitzer diese nicht hat (S_IXUSR).
  • Für andere Dateien (Verzeichnisse) wird der Modus vollständig ignoriert (auf None gesetzt).
  • Ignoriert Benutzer- und Gruppeninformationen (setzt uid, gid, uname, gname auf None).

Jede andere Zeichenkette verursacht einen ValueError.

Die entsprechenden Filterfunktionen werden als tarfile.fully_trusted_filter(), tarfile.tar_filter() usw. verfügbar sein, sodass sie leicht in benutzerdefinierten Richtlinien verwendet werden können.

Beachten Sie, dass diese Filter niemals None zurückgeben. Das Überspringen von Members auf diese Weise ist eine Funktion für benutzerdefinierte Filter.

Standardwerte und deren Konfiguration

TarFile erhält ein neues Attribut, extraction_filter, um die Konfiguration des Standardfilters zu ermöglichen. Standardmäßig ist es None, aber Benutzer können es auf einen aufrufbaren Wert setzen, der verwendet wird, wenn das filter-Argument fehlt oder None ist.

Wenn sowohl das Argument als auch das Attribut None sind

• In Python 3.12-3.13 wird eine DeprecationWarning ausgegeben und die Extraktion verwendet den 'fully_trusted'-Filter.
• Ab Python 3.14+ verwendet er den 'data'-Filter.

Anwendungen und Systemintegratoren möchten möglicherweise extraction_filter der Klasse TarFile selbst ändern, um einen globalen Standard festzulegen. Bei Verwendung einer Funktion werden sie diese im Allgemeinen in staticmethod() verpacken, um die Injektion eines self-Arguments zu verhindern.

Unterklassen von TarFile können auch extraction_filter überschreiben.

FilterError

Eine neue Ausnahme, FilterError, wird dem Modul tarfile hinzugefügt. Sie wird mehrere neue Unterklassen haben, eine für jeden der oben genannten Ablehnungsgründe. Das member-Attribut von FilterError enthält die relevante TarInfo.

In den obigen Listen bedeutet „Verweigern“ der Extraktion einer Datei, dass ein FilterError ausgelöst wird. Wie bei anderen Extraktionsfehlern bricht dies die Extraktion ab, wenn TarFile.errorlevel 1 oder höher ist; bei errorlevel=0 wird der Fehler protokolliert und das Mitglied ignoriert, aber die Extraktion wird fortgesetzt. Beachten Sie, dass extractall() das Archiv möglicherweise teilweise extrahiert zurücklässt; es liegt in der Verantwortung des Benutzers, aufzuräumen.

Fehlerstufe und fatale/nicht-fatale Fehler

Derzeit hat TarFile ein errorlevel-Argument/Attribut, das angibt, wie Fehler behandelt werden.

• Bei errorlevel=0 besagt die Dokumentation, dass „alle Fehler bei der Verwendung von extract() und extractall() ignoriert werden“. Der Code ignoriert nur nicht-fatale und fatale Fehler (siehe unten), sodass Sie beispielsweise immer noch einen TypeError erhalten, wenn Sie None als Zielpfad übergeben.
• Bei errorlevel=1 (dem Standard) werden alle nicht-fatalen Fehler ignoriert. (Sie können nach sys.stderr protokolliert werden, indem das debug-Argument/-Attribut gesetzt wird.) Welche Fehler nicht-fatal sind, ist nicht in der Dokumentation definiert, aber der Code behandelt ExtractionError als solche. Insbesondere handelt es sich um diese Probleme:
  • „Link kann nicht innerhalb des Archivs aufgelöst werden“ (ausgelöst auf Systemen, die keine Symlinks unterstützen)
  • „Fifo/Sondergeräte werden vom System nicht unterstützt“ (wird nicht für Fehler verwendet, wenn das System diese unterstützt, z. B. für einen PermissionError)
  • „Besitzer/Modus/Änderungszeit konnte nicht geändert werden“

  Beachten Sie, dass z. B. Dateiname zu lang oder Festplattenspeicher voll nicht dazu gehören. Die nicht-fatalen Fehler treten auf Unix-ähnlichen Systemen eher selten auf.

• Bei errorlevel=2 werden alle Fehler ausgelöst, einschließlich fataler. Welche Fehler fatal sind, ist wieder nicht definiert; praktisch ist es OSError.

Ein Filter, der die Extraktion eines Members verweigert, passt nicht sauber in die Kategorien fatal/nicht-fatal.

• Dieses PEP ändert das bestehende Verhalten nicht. (Ideen für Verbesserungen sind in Discourse topic 25970 willkommen.)
• Wenn ein Filter die Extraktion eines Members verweigert, sollte der Fehler standardmäßig nicht lautlos vorübergehen.

Um dies zu gewährleisten, wird FilterError als fataler Fehler betrachtet, d. h. er wird nur mit errorlevel=0 ignoriert.

Benutzer, die FilterError, aber nicht andere fatale Fehler ignorieren möchten, sollten eine benutzerdefinierte Filterfunktion erstellen und in einem try-Block einen anderen Filter aufrufen.

Hinweise für weitere Überprüfung

Selbst mit den vorgeschlagenen Änderungen ist tarfile nicht für die Extraktion nicht vertrauenswürdiger Dateien ohne vorherige Prüfung geeignet. Unter anderem verhindern die vorgeschlagenen Richtlinien keine Denial-of-Service-Angriffe. Benutzer sollten zusätzliche Prüfungen durchführen.

Neue Dokumente werden den Benutzern empfehlen, Folgendes zu beachten:

• Extrahieren in ein neues leeres Verzeichnis,
• Verwendung von externen (z. B. OS-Level) Grenzen für Festplatten-, Speicher- und CPU-Auslastung,
• Überprüfung von Dateinamen gegen eine Whitelist von Zeichen (um Steuerzeichen, Verwechslungsgefahr usw. zu filtern),
• Überprüfung, ob Dateinamen erwartete Erweiterungen haben (um Dateien abzuschrecken, die beim „Anklicken“ ausgeführt werden, oder dateilose Dateien wie spezielle Windows-Gerätenamen),
• Begrenzung der Anzahl extrahierter Dateien, der Gesamtgröße der extrahierten Daten und der Größe einzelner Dateien,
• Prüfung auf Dateien, die auf fallunempfindlichen Dateisystemen überschattet würden.

Außerdem wird die Dokumentation darauf hinweisen, dass

• tar-Dateien häufig mehrere Versionen derselben Datei enthalten: spätere sollen frühere beim Extrahieren überschreiben,
• tarfile schützt nicht vor Problemen mit „lebenden“ Daten, z. B. wenn ein Angreifer das Zielverzeichnis während der Extraktion (oder Hinzufügung) manipuliert (siehe das GNU tar-Handbuch für weitere Informationen).

Diese Liste ist nicht erschöpfend, aber die Dokumentation ist ein guter Ort, um solche allgemeinen Tipps zu sammeln. Sie kann in ein separates Dokument verschoben werden, wenn sie zu lang wird oder wenn sie mit zipfile oder shutil konsolidiert werden muss (was außerhalb des Rahmens dieses Vorschlags liegt).

TarInfo-Identität und offset

Bei Filtern, die replace() verwenden, sind die von der Extraktionsmaschinerie verarbeiteten TarInfo-Objekte nicht notwendigerweise dieselben Objekte wie die in members vorhandenen. Dies kann TarInfo-Unterklassen beeinträchtigen, die Methoden wie makelink überschreiben und von der Objektidentität abhängen.

Solcher Code kann auf den Vergleich von offset, der Position des Member-Headers innerhalb der Datei, umstellen.

Beachten Sie, dass sowohl die überschreibbaren Methoden als auch offset nur in Quellcode-Kommentaren dokumentiert sind.

Tarfile CLI

Die CLI (python -m tarfile) erhält eine Option --filter, die den Namen eines der bereitgestellten Standardfilter annimmt. Es wird nicht möglich sein, eine benutzerdefinierte Filterfunktion anzugeben.

Wenn --filter nicht angegeben wird, verwendet die CLI den Standardfilter ('fully_trusted' mit einer Deprecation-Warnung jetzt und 'data' ab Python 3.14).

Es wird keine Kurzoption geben. (Die Option -f wäre verwirrend ähnlich zur Dateinamenoption von GNU tar.)

Andere Archivbibliotheken

Wenn und wenn andere Archivbibliotheken, wie z. B. zipfile, ähnliche Funktionalität erhalten, sollten ihre Extraktionsfunktionen ein filter-Argument verwenden, das zumindest die Zeichenketten 'fully_trusted' (was alle Sicherheitsvorkehrungen deaktivieren sollte) und 'data' (was Funktionen vermeiden sollte, die Benutzer überraschen könnten) annimmt.

Die Standardisierung einer funktionsbasierten Filter-API liegt außerhalb des Rahmens dieses PEP.

Shutil

shutil.unpack_archive() erhält ein filter-Argument. Wenn es angegeben wird, wird es an die zugrunde liegende Extraktionsfunktion übergeben. Die Übergabe für ein zip-Archiv schlägt vorerst fehl (bis zipfile ein filter-Argument erhält, falls jemals).

Wenn filter nicht angegeben ist (oder als None belassen wird), wird es nicht weitergegeben, sodass die Extraktion eines Tarballs den Standardfilter verwendet ('fully_trusted' mit einer Deprecation-Warnung jetzt und 'data' ab Python 3.14).

Komplexe Filter

Beachten Sie, dass einige benutzerdefinierte Filter beispielsweise die Anzahl der extrahierten Members zählen oder Nachbearbeitungen durchführen müssen. Dies erfordert eine komplexere API als ein filter-Callable. Diese komplexe API muss jedoch nicht für tarfile zugänglich gemacht werden. Mit einem hypothetischen StatefulFilter würden Benutzer zum Beispiel schreiben:

with StatefulFilter() as filter_func:
    my_tar.extract(path, filter=filter_func)

Ein einfaches StatefulFilter-Beispiel wird der Dokumentation hinzugefügt.

SafeTarFile

Eine erste Idee von Lars Gustäbel war, eine separate Klasse bereitzustellen, die Sicherheitsprüfungen implementiert (siehe gh-65308). Dieser Ansatz hat zwei Hauptprobleme:

• Der Name ist irreführend. Allgemeine Archivoperationen können niemals "sicher" gegen alle Arten von unerwünschtem Verhalten gemacht werden, ohne legitime Anwendungsfälle zu beeinträchtigen.
• Das Problem unsicherer Standardeinstellungen wird nicht gelöst.

Viele der Ideen hinter SafeTarFile wurden jedoch in diesem PEP wiederverwendet.

Option absolute_path zu tarfile hinzufügen

Das Issue gh-73974 fordert die Hinzufügung einer Option absolute_path zu Extraktionsmethoden. Dies wäre eine minimale Änderung, um CVE-2007-4559 formell zu beheben. Es geht nicht weit genug, um die Unwissenden zu schützen, noch um die Fleißigen und Neugierigen zu befähigen.

Andere Namen für den 'tar'-Filter

Der 'tar'-Filter gibt Features preis, die für UNIX-ähnliche Dateisysteme spezifisch sind, daher könnte er 'unix' genannt werden. Oder 'unix-like', 'nix', '*nix', 'posix'?

Funktional gesehen sind *Tar-Format* und *UNIX-ähnliches Dateisystem* im Wesentlichen äquivalent, daher ist tar ein guter Name.

Hinzufügen von Filtern zu zipfile und shutil.unpack_archive

Zur Konsistenz könnten zipfile und shutil.unpack_archive() die Unterstützung für ein filter-Argument erhalten. Dies würde jedoch Forschung erfordern, die der Autor dieses PEPs für Python 3.12 nicht versprechen kann.

Filter für zipfile würden wahrscheinlich nicht zur Sicherheit beitragen. Zip wird hauptsächlich für plattformübergreifende Datenpakete verwendet, und entsprechend sind die Standardeinstellungen von ZipFile.extract bereits ähnlich dem, was ein 'data'-Filter tun würde. Ein 'fully_trusted'-Filter, der absolute Pfade und ..-Pfadkomponenten neu zulassen würde, wäre möglicherweise nicht für viel anderes nützlich als eine einheitliche unpack_archive-API.

Filter sollten für andere Anwendungsfälle als die Sicherheit nützlich sein, aber diese würden normalerweise benutzerdefinierte Filterfunktionen benötigen, und diese würden eine API benötigen, die sowohl mit TarInfo als auch mit ZipInfo funktioniert. Das liegt definitiv außerhalb des Rahmens dieses PEPs.

Wenn nur dieses PEP implementiert wird und sich für zipfile nichts ändert, ist die Auswirkung für Aufrufer von unpack_archive, dass der Standard für Tar-Dateien von 'fully_trusted' auf das passendere 'data' geändert wird. In der Übergangszeit werden Python 3.12-3.13 eine DeprecationWarning ausgeben. Das ist ärgerlich, aber es gibt mehrere Möglichkeiten, damit umzugehen: z. B. ein filter-Argument bedingt hinzufügen, TarFile.extraction_filter global setzen oder die Warnung bis Python 3.14 ignorieren/unterdrücken.

Da viele Aufrufe von unpack_archive wahrscheinlich unsicher sind, besteht die Hoffnung, dass die DeprecationWarning oft ein hilfreicher Hinweis sein wird, den betroffenen Code zu überprüfen.