Zusammenfassung

Dieser PEP beschreibt eine Methode zur Aufzeichnung der Herkunft installierter Python-Distributionen. Der Datensatz wird von einem Installer erstellt und steht Benutzern in Form einer JSON-Datei provenance_url.json im Verzeichnis .dist-info zur Verfügung. Die genannte JSON-Datei erfasst zusätzliche Metadaten, um die Aufzeichnung einer URL zu einem Distributionspaket zusammen mit dem Hash der installierten Distribution zu ermöglichen. Dieser Vorschlag baut auf PEP 610 auf, folgt seiner entsprechenden kanonischen PyPA-Spezifikation und ergänzt direct_url.json mit provenance_url.json für Fälle, in denen Pakete durch einen Namen und optional eine Version identifiziert werden.

Motivation

Die Installation eines Python-Projekts beinhaltet das Herunterladen eines Distributionspakets von einem Paketindex und das Extrahieren seines Inhalts an einen geeigneten Ort. Nach Abschluss des Installationsprozesses gehen Informationen über das verwendete Release-Artefakt und seine Quelle im Allgemeinen verloren. Es gibt jedoch Anwendungsfälle, um Aufzeichnungen der für die Installation von Paketen verwendeten Distributionen und ihrer Herkunft aufzubewahren.

Python-Wheels können mit unterschiedlichen Compiler-Flags erstellt werden oder verschiedene Wheel-Tags unterstützen. In beiden Fällen können Benutzer in eine Situation geraten, in der mehrere Wheels von Installern (möglicherweise aus verschiedenen Paketindizes) berücksichtigt werden könnten und es hilfreich wäre, sofort herauszufinden, welche Wheel-Datei tatsächlich während der Installation verwendet wurde. Auf diese Weise können Entwickler Informationen über Wheels verwenden, um Probleme zu debuggen und sicherzustellen, dass das gewünschte Wheel tatsächlich installiert wurde. Ein weiterer Anwendungsfall könnten Werkzeuge sein, die installierte Software berichten, wie z. B. Werkzeuge, die eine SBOM (Software Bill of Materials) berichten, die genauere Berichte liefern könnten. Ein weiterer Anwendungsfall könnte die Rekonstruktion der Python-Umgebung sein, indem jedes installierte Paket an ein bestimmtes Distributionsartefakt angeheftet wird, das aus einem Python-Paketindex bezogen wurde.

Begründung

Die in diesem PEP beschriebene Motivation ist eine Erweiterung der Spezifikation Recording the Direct URL Origin of installed distributions. Zusätzlich zur Aufzeichnung von Herkunftsinformationen für Pakete, die über eine direkte URL installiert wurden, sollten Installer dies auch für Pakete tun, die nach Namen (und optional nach Version) aus Python-Paketindizes installiert werden.

Die in diesem PEP beschriebene Idee hat ihren Ursprung in einem Tool namens micropipenv, das zur Installation von Distributionspaketen in containerisierten Umgebungen verwendet wird (siehe gemeldete Issue thoth-station/micropipenv#206). Derzeit trägt die zusammengestellte containerisierte Anwendung nicht implizit Informationen über die Herkunft installierter Distributionspakete (es sei denn, diese werden von vollständigen URLs installiert und über direct_url.json erfasst). Dies erfordert, dass Lieferanten von Container-Images Container-Images mit dem entsprechenden Build-Prozess, seiner Konfiguration und dem Anwendungscod verknüpfen, um Anforderungsdateien zu prüfen, wenn Software in containerisierten Umgebungen geprüft werden muss.

Die anschließende Diskussion im Discourse-Thread brachte auch die neue Option --report von pip zur Sprache, die einen detaillierten JSON-Bericht über den Installationsprozess generieren kann. Diese Option könnte bei dem Herkunftsproblem helfen, das dieser PEP behandelt. Nichtsdestotrotz muss diese Option *explizit* an pip übergeben werden, um die Herkunftsinformationen zu erhalten, und sie enthält zusätzliche Metadaten, die für die Prüfung der Herkunft möglicherweise nicht notwendig sind (wie z. B. Python-Versionsanforderungen jedes Distributionspakets). Außerdem ist diese Option zum Zeitpunkt der Erstellung dieses PEP spezifisch für pip.

Beachten Sie, dass die aktuelle Spezifikation für die Aufzeichnung installierter Pakete eine RECORD-Datei definiert, die installierte Dateien aufzeichnet, aber nicht das Distributionsartefakt, von dem diese Dateien bezogen wurden. Die Prüfung installierter Artefakte kann auf der Grundlage von Übereinstimmungen mit den Einträgen in der RECORD-Datei erfolgen. Diese Technik erfordert jedoch eine vorab erstellte Datenbank von Dateien, die jedes Artefakt bereitstellt, oder einen Vergleich mit dem tatsächlichen Artefaktinhalt. Beide Ansätze sind relativ teure und zeitaufwändige Operationen, die mit der vorgeschlagenen Datei provenance_url.json eliminiert werden könnten.

Die Aufzeichnung von Herkunftsinformationen für installierte Distributionspakete, sowohl die von direkten URLs als auch die nach Namen/Version aus einem Index bezogenen, kann die Prüfung von Python-Umgebungen im Allgemeinen vereinfachen, über den spezifischen Anwendungsfall für containerisierte Anwendungen hinaus. Ein Community-Projekt pip-audit hat sein mögliches Interesse in pypa/pip-audit#170 geäußert.

Spezifikation

Die Schlüsselwörter „MUST“, „MUST NOT“, „REQUIRED“, „SHOULD“, „SHOULD NOT“, „RECOMMENDED“, „MAY“ und „OPTIONAL“ in diesem Dokument sind wie in RFC 2119 beschrieben zu interpretieren.

Die Datei provenance_url.json SOLLTE im Verzeichnis .dist-info von Installern erstellt werden, wenn ein Distributionspaket, das nach Namen (und optional nach Versionsspezifizierer) angegeben ist, installiert wird.

Diese Datei DARF NICHT erstellt werden, wenn ein Distributionspaket aus einer Anforderung installiert wird, die eine direkte URL-Referenz (einschließlich einer VCS-URL) angibt.

Nur eine der Dateien provenance_url.json und direct_url.json (aus der Spezifikation Recording the Direct URL Origin of installed distributions und der entsprechenden Spezifikation der Direct URL Data Structure) darf in einem gegebenen Verzeichnis .dist-info vorhanden sein; Installer DÜRFEN NICHT beide hinzufügen.

Die JSON-Datei provenance_url.json MUSS ein Dictionary sein, das mit RFC 8259 konform und UTF-8-kodiert ist.

Falls vorhanden, MUSS sie genau zwei Schlüssel enthalten. Der erste MUSS url vom Typ string sein. Der zweite Schlüssel MUSS archive_info sein, mit einem unten definierten Wert.

Der Wert des Schlüssels url MUSS die URL sein, von der das Distributionspaket heruntergeladen wurde. Wenn ein Wheel aus einer Quellverteilung gebaut wird, MUSS der url-Wert die URL sein, von der die Quellverteilung heruntergeladen wurde. Wenn ein Wheel direkt heruntergeladen und installiert wird, MUSS das Feld url die URL sein, von der das Wheel heruntergeladen wurde. Wie in der Spezifikation Direct URL Data Structure muss der url-Wert aus Sicherheitsgründen von jeglichen sensiblen Authentifizierungsinformationen bereinigt werden.

Der Benutzer:Passwort-Teil der URL KANN jedoch aus Umgebungsvariablen bestehen, die dem folgenden regulären Ausdruck entsprechen

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

Zusätzlich KANN der Benutzer:Passwort-Teil der URL eine bekannte, nicht sicherheitsrelevante Zeichenkette sein. Ein typisches Beispiel ist git im Falle einer URL wie ssh://git@gitlab.com.

Der Wert von archive_info MUSS ein Dictionary mit einem einzigen Schlüssel hashes sein. Der Wert von hashes ist ein Dictionary, das Hash-Funktionsnamen auf einen hex-kodierten Digest der Datei abbildet, auf die der url-Wert verweist. Mindestens ein Hash MUSS aufgezeichnet werden. Mehrere Hashes KÖNNEN enthalten sein, und es liegt am Konsumenten, zu entscheiden, was mit mehreren Hashes geschehen soll (er kann sie alle oder eine Teilmenge davon validieren oder gar nichts).

Jeder Hash MUSS einer der einargumentigen Hashes sein, die von hashlib.algorithms_guaranteed bereitgestellt werden, mit Ausnahme von sha1 und md5, die NICHT verwendet werden dürfen. Ab Python 3.11 sind mit Ausnahme von shake_128 und shake_256 für Mehrfachargumente die erlaubten Hashes:

>>> import hashlib
>>> sorted(hashlib.algorithms_guaranteed - {"shake_128", "shake_256", "sha1", "md5"})
['blake2b', 'blake2s', 'sha224', 'sha256', 'sha384', 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512', 'sha512']

Jeder Hash MUSS unter dem kanonischen Namen des Hashs, immer in Kleinbuchstaben, referenziert werden.

Hashes sha1 und md5 DÜRFEN NICHT vorhanden sein, aufgrund der Sicherheitsbeschränkungen dieser Hash-Algorithmen. Umgekehrt SOLLTE der Hash sha256 enthalten sein.

Installer, die Distributionspakete aus einem Index cachen, SOLLTEN Informationen über das gecachte Distributionsartefakt beibehalten, damit die Datei provenance_url.json auch beim Installieren von Distributionspaketen aus dem Cache des Installers erstellt werden kann.

Abwärtskompatibilität

Gemäß der Spezifikation Recording installed projects können Installer zusätzliche, spezifische Dateien im Verzeichnis .dist-info speichern. Um sicherzustellen, dass dieser PEP keine Rückwärtskompatibilitätsprobleme verursacht, fand eine umfassende Umfrage von Installern und Bibliotheken keine aktuellen Tools, die eine ähnlich benannte Datei verwenden, oder andere wesentliche Machbarkeitsprobleme.

Die Spezifikation Wheel specification listet Dateien auf, die im Verzeichnis .dist-info vorhanden sein können. Keine dieser Dateinamen kollidiert mit der vorgeschlagenen Datei provenance_url.json aus diesem PEP.

Sicherheitsimplikationen

Eines der Hauptsicherheitsmerkmale der Datei provenance_url.json ist die Möglichkeit, installierte Artefakte in Python-Umgebungen zu überprüfen. Tools können überprüfen, welche Python-Paketindizes zum Installieren von Python-Distributionspaketen verwendet wurden, sowie die Hash-Digests ihrer Release-Artefakte.

Als Beispiel können wir die kürzlich kompromittierte Abhängigkeitskette im PyTorch-Vorfall nehmen. Der PyTorch-Index stellte ein Paket namens torchtriton bereit. Ein Angreifer veröffentlichte torchtriton auf PyPI, das eine bösartige Binärdatei ausführte. Durch die Überprüfung der in der Datei provenance_url.json angegebenen URL der installierten Python-Distribution können Tools die Quelle der installierten Python-Distribution automatisch überprüfen. Im Fall des PyTorch-Vorfalls sollte die URL von torchtriton auf den PyTorch-Index und nicht auf PyPI verweisen. Tools können helfen, solche installierten bösartigen Python-Distributionen zu identifizieren, indem sie die URL der installierten Python-Distribution überprüfen. Eine genauere Prüfung kann auch den Hash der installierten Python-Distribution umfassen, der in der Datei provenance_url.json angegeben ist. Solche Hash-Prüfungen können für gespiegelte Python-Paketindizes hilfreich sein, bei denen Python-Distributionen nicht anhand ihrer Quell-URLs unterscheidbar sind, und stellen sicher, dass nur die gewünschten Python-Paketdistributionen installiert werden.

Ein böswilliger Akteur kann den Inhalt von provenance_url.json absichtlich anpassen, um möglicherweise die Herkunftsinformationen der installierten Python-Distribution zu verbergen. Eine Sicherheitsprüfung, die solche bösartigen Aktivitäten aufdecken würde, liegt außerhalb des Rahmens dieses PEP, da sie die Überwachung von Dateisystemaktivitäten und die anschließende Überprüfung von Benutzer- oder Dateiberechtigungen erfordern würde.

Wie man das lehrt

Die Metadaten-Datei provenance_url.json ist für Tools gedacht und für Endbenutzer nicht direkt sichtbar.

Beispiele

{
  "archive_info": {
    "hashes": {
      "blake2s": "fffeaf3d0bd71dc960ca2113af890a2f2198f2466f8cd58ce4b77c1fc54601ff",
      "sha256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f",
      "sha3_256": "c856930e0f707266d30e5b48c667a843d45e79bb30473c464e92dfa158285eab",
      "sha512": "6bad5536c30a0b2d5905318a1592948929fbac9baf3bcf2e7faeaf90f445f82bc2b656d0a89070d8a6a9395761f4793c83187bd640c64b2656a112b5be41f73d"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

{
  "archive_info": {
    "hashes": {
      "sha256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

{
  "archive_info": {
    "hashes": {
      "sha256": "8bfe29f17c10e2f2e619de8033a07a224058d96b3bfe2ed61777596f7ffd7fa9"
    }
  },
  "url": "https://files.pythonhosted.org/packages/1d/43/ad8ae671de795ec2eafd86515ef9842ab68455009d864c058d0c3dcf680d/micropipenv-0.0.1.tar.gz"
}

{
  "archive_info": {
    "hash": "sha256=236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f",
    "hashes": {
      "sha256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

{
  "archive_info": {
    "hashes": {
      "SHA-256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

{
  "archive_info": {
    "hashes": {}
   }
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

Referenzimplementierung

Ein Proof-of-Concept zur Erstellung der Metadaten-Datei provenance_url.json bei der Installation eines Python-Distributionspakets ist im PR zu pip pypa/pip#11865 verfügbar. Er nutzt die bereits vorhandene Implementierung für die direct URL data structure, um die Metadaten-Datei provenance_url.json für Fälle bereitzustellen, in denen direct_url.json nicht erstellt wird.

Eine Referenzimplementierung zur Unterstützung der Datei provenance_url.json in PDM existiert im PR pdm-project/pdm#3013.

Ein Prototyp namens pip-preserve wurde entwickelt, um die Erstellung von requirements.txt-Dateien unter Berücksichtigung der Metadaten-Dateien direct_url.json und provenance_url.json zu demonstrieren. Dieses Tool imitiert die Funktionalität von pip freeze, aber die Auflistung der installierten Pakete enthält auch die Hashes der Python-Distributionsartefakte.

Zur weiteren Unterstützung dieses Vorschlags demonstriert pip-sbom die Erstellung von SBOMs im SPDX-Format. Das Tool verwendet Informationen aus der Datei provenance_url.json.

Abgelehnte Ideen

Offene Fragen

Anhang: Umfrage von Installern und Bibliotheken

Danksagungen

Vielen Dank an Dustin Ingram, Brett Cannon und Paul Moore für die anfängliche Diskussion, aus der diese Idee entstanden ist.

Vielen Dank an Donald Stufft, Ofek Lev und Trishank Kuppusamy für frühes Feedback und Unterstützung bei der Arbeit an diesem PEP.

Vielen Dank an Gregory P. Smith, Stéphane Bidoul, C.A.M. Gerlach und Adam Turner für die Überprüfung dieses PEP und die wertvollen Vorschläge.

Vielen Dank an Seth Michael Larson für die Unterstützung, wertvolle Vorschläge und den vorgeschlagenen pip-sbom-Prototyp.

Vielen Dank an Stéphane Bidoul und Chris Jerdonek für PEP 610 und die zugehörigen Spezifikationen Recording the Direct URL Origin of installed distributions und Direct URL Data Structure.

Vielen Dank an Frost Ming für die Anregung möglicher Bedenken bezüglich der Speicherung der Index-URL in der provenance_url.json Datei und die anfängliche Unterstützung für PEP 710 in PDM.

Vielen Dank an Charlie Marsh und Zanie Blue für die Beiträge im Zusammenhang mit dem uv-Installer.

Zu guter Letzt, aber nicht unwichtig, vielen Dank an Donald Stufft für die Förderung dieses PEP.

Urheberrecht

Dieses Dokument wird in die Public Domain oder unter die CC0-1.0-Universal-Lizenz gestellt, je nachdem, welche Lizenz permissiver ist.