From 7e2eca3b0f9b29e9754369926dfad0da760f983c Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Tue, 11 Aug 2026 17:19:03 +0200 Subject: [PATCH 1/9] add first draft for a blog about maven artifact resolution --- .../2026-08-xx-maven-artefakt-herkunft.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 content/posts/2026-08-xx-maven-artefakt-herkunft.md diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.md new file mode 100644 index 00000000..9aade985 --- /dev/null +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.md @@ -0,0 +1,88 @@ +# Woher kommt dieses Artefakt eigentlich? Maven, das lokale Repository und die Datei `_remote.repositories` + +Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den ersten Blick nicht ansehen kann, woher sein Inhalt stammt. + +Dieser Artikel geht der Frage nach, wie Maven Artefakte auflöst, welche Rolle die Manager und Requests des Maven Resolvers dabei spielen, was in der unscheinbaren Datei `_remote.repositories` steht, und wie sich daraus eine konkrete Verbesserung für das Apache Maven Artifact Plugin ableiten lässt. + +## Warum die Herkunft ein Supply-Chain-Thema ist + +Das Maven Artifact Plugin ist das Werkzeug, mit dem im Maven-Ökosystem Reproducible Builds nachgewiesen werden. Das Ziel `artifact:buildinfo` erzeugt eine Beschreibung des Build-Ergebnisses inklusive Checksummen, und `artifact:compare` vergleicht das Ergebnis des aktuellen Builds mit einer Referenz. Wenn beide übereinstimmen, ist gezeigt, dass die veröffentlichten Artefakte tatsächlich aus dem angegebenen Quellcode entstanden sein können. + +Ein Vergleich ist allerdings nur so gut wie sein Vergleichsmaßstab. Wenn eine der beteiligten Abhängigkeiten nicht aus einem öffentlichen Repository stammt, sondern aus einem `mvn install`, das vor drei Wochen auf demselben Rechner gelaufen ist, dann vergleicht man am Ende ein lokales Ergebnis mit einem anderen lokalen Ergebnis. Das Resultat sieht sauber aus, es sagt aber nichts über die öffentlich veröffentlichten Artefakte aus. Aus Supply-Chain-Sicht ist ein lokal installiertes Artefakt ein Eingang in den Build, der von niemandem geprüft wurde, weder durch eine Signatur noch durch eine Checksumme gegen ein Remote-Repository. + +Genau diese Lücke wurde in MARTIFACT-58 beschrieben. Seine Beobachtung: `artifact:compare` vergleicht die Ausgabe des aktuellen Builds mit Inhalten aus dem lokalen Repository, und was sich dabei nicht leicht erkennen lässt, ist, ob dieser Inhalt aus einem früheren lokalen `mvn install` stammt oder aus einem Remote-Repository heruntergeladen wurde. Sein Vorschlag war, dass das Plugin diese Information selbst ermitteln und anzeigen könnte. + +## Das lokale Repository als gemischte Ablage + +Die Maven-Dokumentation beschreibt das lokale Repository offen als gemischte Ablage, die zwei Aufgaben gleichzeitig erfüllt: Sie ist Cache für Artefakte, die von einem Remote-Repository geladen wurden, und sie ist Ablage für Artefakte, die lokal gebaut und installiert wurden. Beide landen im selben Layout, also unter demselben Pfad aus GroupId, ArtifactId und Version. Aus dem Pfad allein lässt sich die Herkunft folglich nicht ablesen. + +Die Dokumentation ist an dieser Stelle sehr deutlich: Nutzer sollen niemals mit einfachen Dateioperationen direkt in das lokale Repository greifen, sondern immer die bereitgestellte API verwenden. Der Grund ist, dass es heute mehrere Implementierungen des lokalen Repositorys gibt, dass sich das Layout ändern kann, und dass direkter Dateizugriff wichtige Aspekte wie Locking und Synchronisation umgeht. Wer die Herkunftsfrage beantworten will, sollte sie also über die API stellen. + +## Die Manager im Maven Resolver + +Unterhalb von Maven arbeitet der Maven Artifact Resolver, das frühere Aether. Er kapselt alles, was mit Repositories zu tun hat, hinter dem Einstiegspunkt `RepositorySystem` und einer `RepositorySystemSession`, die die aktuelle Konfiguration des Builds trägt. + +Für das lokale Repository ist der `LocalRepositoryManager` zuständig, kurz LRM. Der Resolver bringt zwei Implementierungen mit. Die Variante `simple` ist funktionsfähig, aber vor allem für Tests gedacht und nicht für den produktiven Einsatz empfohlen. Die Variante `enhanced` ist die zur Laufzeit verwendete, und sie ist genau dort erweitert, wo es für dieses Thema zählt: Sie merkt sich, aus welchem Repository ein gecachtes Artefakt aufgelöst wurde. + +Diese Buchführung hat einen ganz praktischen Zweck. Wenn ein Artefakt A1 aus dem Repository R1 geladen wurde und ein späterer Build dasselbe Artefakt benötigt, R1 aber nicht kennt, dann behandelt der Enhanced LRM das lokal vorhandene A1 als nicht vorhanden und lädt es erneut. Die Begründung ist ein Vertrauensargument: Zwei Artefakte mit identischen Koordinaten aus zwei verschiedenen Repositories müssen nicht dasselbe sein. Dieselbe Mechanik erklärt übrigens die gelegentlich verwirrende Fehlermeldung, dass ein Artefakt nicht auflösbar sei, obwohl es sichtbar im Verzeichnis liegt. + +Ergänzend gibt es weitere Manager und Komponenten, die in derselben Schicht arbeiten. Der `RemoteRepositoryManager` aggregiert Repositories, wendet Mirrors an und verwaltet Update-Policies. Ein `WorkspaceReader` erlaubt es, Artefakte aus dem laufenden Reactor oder einer IDE zu beziehen, ohne dass sie überhaupt installiert werden. Und der Chained Local Repository Manager kombiniert ein schreibbares LRM mit einer Liste nur lesbarer weiterer lokaler Repositories, was insbesondere für verschachtelte Builds hilfreich ist. + +Erwähnenswert ist außerdem das Split-Feature des Enhanced LRM. Es ist standardmäßig deaktiviert, kann aber über Konfigurationsschalter aktiviert werden und trennt den Inhalt des lokalen Repositorys physisch, nämlich nach gecacht und lokal installiert, nach Herkunftsrepository, sowie nach Release und Snapshot. Wer regelmäßig Rebuilds verifiziert, bekommt damit ein sehr direktes Werkzeug in die Hand, denn dann lassen sich alle lokal installierten Artefakte löschen, ohne dass anschließend das halbe Internet erneut heruntergeladen werden muss. + +## Die Requests im Maven Resolver + +Die Resolver-API ist konsequent nach dem Muster Request und Result aufgebaut, und die verschiedenen Request-Typen entsprechen den verschiedenen Fragen, die man an ein Repository stellen kann. + +`VersionRequest` und `VersionRangeRequest` klären Koordinaten, etwa die Auflösung eines Versionsbereichs oder die Übersetzung einer Snapshot-Version in eine konkrete Zeitstempelversion. Der `ArtifactDescriptorRequest` liest die Beschreibung eines Artefakts, also im Wesentlichen dessen POM inklusive direkter Abhängigkeiten und möglicher Relocations. Der `CollectRequest` baut daraus einen Abhängigkeitsgraphen auf und liefert im `CollectResult` einen Baum aus `DependencyNode`-Objekten, ohne dabei die eigentlichen Dateien herunterzuladen. Der `DependencyRequest` geht einen Schritt weiter und löst zusätzlich die Dateien des Graphen auf. Der `ArtifactRequest` schließlich fragt nach genau einem Artefakt und liefert ein `ArtifactResult` zurück. Daneben stehen `MetadataRequest` für Repository-Metadaten, `LocalArtifactRequest` als Frage direkt an das lokale Repository, sowie `InstallRequest` und `DeployRequest` für den Weg nach außen. + +Die Trennung zwischen Sammeln und Auflösen ist für unsere Fragestellung der entscheidende Punkt. Man kann den vollständigen Abhängigkeitsbaum aufbauen, ohne Downloads auszulösen, und danach gezielt einzelne Knoten auflösen, um zu erfahren, woher sie kommen. Denn `ArtifactResult` trägt eine Methode `getRepository()`, und diese liefert das Repository, aus dem das Artefakt tatsächlich bezogen wurde. + +## Die Datei `_remote.repositories` + +Damit `getRepository()` überhaupt eine sinnvolle Antwort geben kann, muss die Information irgendwo persistiert sein, und genau das ist die Aufgabe der Tracking-Datei `_remote.repositories`. Der Enhanced LRM legt sie in jedem Verzeichnis des lokalen Repositorys an, in dem er Artefakte verwaltet. Ihr Name ist konfigurierbar, der Standard ist der genannte. + +Der Inhalt ist eine Java-Properties-Datei. Die Schlüssel bestehen aus dem Dateinamen, einem `>` als Trenner und der Id des Repositorys, aus dem die Datei bezogen wurde. Der Wert bleibt leer. Ein Verzeichnis kann damit etwa so aussehen: + +``` +#NOTE: This is a Maven Resolver internal implementation file, its format can be changed without prior notice. +artifact-1.0.pom>central= +artifact-1.0.jar>central= +artifact-1.0.pom>my_repo_id= +``` + +Der entscheidende Sonderfall ist die leere Repository-Id. Ein Eintrag der Form `artifact-1.0.jar>=` bedeutet, dass diese Datei nicht heruntergeladen, sondern lokal installiert wurde. Der Resolver verwendet dafür intern eine Konstante mit dem Wert einer leeren Zeichenkette. Fehlt zu einer vorhandenen Datei jeglicher Eintrag, dann behandelt der Enhanced LRM sie ebenfalls als lokal installiert, und zwar aus Kompatibilität mit dem Simple LRM, der keine Tracking-Datei schreibt. + +Diese Datei ist damit die eigentliche Antwort auf MARTIFACT-58, allerdings nicht als Datei, die man selbst lesen sollte. Sie trägt ihren Warnhinweis im Kopf, ihr Format kann sich jederzeit ändern, ihr Name ist konfigurierbar, und bei aktiviertem Split-Feature liegt sie ohnehin an einem anderen Ort als erwartet. Der richtige Weg führt über die API, und dort ist die Information bereits aufbereitet: `LocalArtifactResult.getRepository()` liefert das Remote-Repository, aus dem ein Artefakt gecacht wurde, und `null`, wenn es lokal installiert wurde. Der `DefaultArtifactResolver` übersetzt diesen Fall nach oben, indem er im `ArtifactResult` das lokale Repository einträgt. Aus der leeren Repository-Id in einer Textdatei wird auf diesem Weg eine Instanz von `LocalRepository` in der Plugin-API. + +## Die Umsetzung im Maven Artifact Plugin + +Genau diese Kette nutzt der Pull Request [#227](https://github.com/apache/maven-artifact-plugin/pull/227) für das Apache Maven Artifact Plugin. Die Änderung sitzt in `ReferenceBuildinfoUtil`, also dort, wo das Plugin die Referenz für den Vergleich ermittelt, und wird aus `CompareMojo` aufgerufen, das nun die `RepositorySystemSession` und die Liste der Remote-Repositories durchreicht. + +Der Ablauf ist bewusst schlicht. Zunächst wird über einen `CollectRequest` der Abhängigkeitsbaum des betrachteten Artefakts gesammelt, was ohne Downloads geschieht. Anschließend wird der Baum traversiert, und für jeden betrachteten Knoten wird ein `ArtifactRequest` gestellt, dem explizit die Remote-Repositories des Projekts mitgegeben werden. Aus dem `ArtifactResult` wird das Repository ausgelesen, und wenn dieses eine `LocalRepository` ist, dann steht fest, dass das Artefakt aus einer lokalen Installation stammt. + +In diesem Fall gibt das Plugin eine Warnung aus: + +``` +The artifact org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your +local Maven repository. Please ensure that this is intended. If not, consider +removing this artifact and rebuilding and that your locally installed artifact +from /home/user/.m2/repository/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar +matches public reference from remote. +``` + +Drei Details an dieser Meldung sind das Ergebnis des Reviews und lohnen einen Blick. Erstens wurde die Formulierung von der ursprünglichen Fassung präzisiert, denn die Aussage lautet nicht, dass das Artefakt aus dem lokalen Repository kommt, was auf jedes gecachte Artefakt zutreffen würde, sondern dass es aus einer lokalen Installation in dieses Repository stammt. Zweitens benennt die Meldung ausdrücklich das eigentliche Risiko, nämlich dass das lokal installierte Artefakt der öffentlich veröffentlichten Referenz entsprechen muss. Drittens enthält sie den absoluten Pfad, damit man die betroffene Datei direkt löschen und den Build wiederholen kann. + +Bewusst gewählt ist auch, dass es sich um eine Warnung handelt und nicht um einen Fehler. Lokale Installationen sind ein legitimer Teil vieler Arbeitsabläufe, etwa bei Multi-Modul-Projekten oder beim Testen eines noch nicht veröffentlichten Snapshots. Der Build soll deshalb weiterlaufen, aber die Information soll sichtbar sein. Aus demselben Grund führt ein Fehlschlag der Prüfung selbst nur zu einer weiteren Warnung und nicht zum Abbruch. Ein Integrationstest im Szenario `compare-mono` prüft, dass die Warnung tatsächlich im Build-Log erscheint, damit die Zusage nicht unbemerkt verloren geht. + +## Was sich daraus für die Praxis ergibt + +Für Anwender bedeutet die Änderung, dass ein Reproducible-Build-Vergleich künftig von selbst darauf hinweist, wenn seine Grundlage nicht so belastbar ist, wie sie aussieht. Wer Rebuilds systematisch verifiziert, sollte darüber hinaus zwei Dinge in Betracht ziehen. Zum einen lohnt es sich, Verifikationsbuilds in einem separaten lokalen Repository laufen zu lassen, damit lokal installierte Artefakte gar nicht in Reichweite kommen. Zum anderen ist das Split-Feature des Enhanced LRM genau für diese Art von Hygiene gedacht, denn es macht die Trennung zwischen selbst gebauten und heruntergeladenen Artefakten physisch sichtbar und erlaubt gezieltes Aufräumen. + +Der allgemeinere Punkt aber ist, dass die Information über die Herkunft eines Artefakts in Maven längst vorhanden war. Sie lag in einer internen Datei, die man nicht anfassen soll, und war über eine API erreichbar, die man dafür kennen muss. Was gefehlt hat, war die Verbindung zwischen dieser vorhandenen Information und der Stelle, an der sie eine Entscheidung beeinflusst. Solche Verbindungen zu ziehen ist ein guter Teil der Arbeit an Supply-Chain-Sicherheit, und sie besteht seltener aus neuen Mechanismen als aus dem Sichtbarmachen dessen, was das Werkzeug längst weiß. + +--- + +*Die Arbeit an Apache Maven im Rahmen von Support & Care wird durch die Sovereign Tech Agency gefördert.* + +*Dieser Artikel ist mithilfe von AI entstanden* \ No newline at end of file From efb87b9c2ff0ef2c2b51ec1039f86f07457fe125 Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Wed, 12 Aug 2026 09:15:42 +0200 Subject: [PATCH 2/9] add metadata --- content/posts/2026-08-xx-maven-artefakt-herkunft.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.md index 9aade985..66d22891 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.md @@ -1,3 +1,16 @@ +--- +outdated: false +showInBlog: true +title: "Von der Supply Chain, lokal gebauten Artefakten und wie Maven damit umgeht" +slug: genug-geredet-wie-digitale-souveränität-von-der-un-bis-dortmund-konkret-wird +date: 2026-08-12 +author: sebastian +excerpt: "Lokal gebaute Artefakte können ein Problem für Reproducible Builds sein und damit ein Risiko für die Supply Chain. Ich zeige hier, wie das Auflösen von Artefakten in Maven passiert und wie man sehen kann, ob ein selbstgebautes Artefakt fäschlicher Weise verwerndet wurde." +categories: [Open Elements, Open-Source, Security, Java] +preview_image: "/posts/preview-images/oss-world.svg" +--- + + # Woher kommt dieses Artefakt eigentlich? Maven, das lokale Repository und die Datei `_remote.repositories` Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den ersten Blick nicht ansehen kann, woher sein Inhalt stammt. From 7bcde00eb319249bd685ce56615384f8e98bad30 Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Fri, 28 Aug 2026 09:43:41 +0200 Subject: [PATCH 3/9] apply comments, remove depper technical details --- .../2026-08-xx-maven-artefakt-herkunft.md | 44 +++++++------------ 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.md index 66d22891..aee32cc8 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.md @@ -13,47 +13,37 @@ preview_image: "/posts/preview-images/oss-world.svg" # Woher kommt dieses Artefakt eigentlich? Maven, das lokale Repository und die Datei `_remote.repositories` -Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den ersten Blick nicht ansehen kann, woher sein Inhalt stammt. +Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den ersten Blick nicht ansehen kann, woher sein Inhalt stammt. Technisch haben wir das Thema bereits in einem anderen [Blogpost](https://open-elements.com/posts/2025/09/12/reproducible-builds) im Kontext von Apache Maven und den Auswirkungen auf die Supply Chain beleuchtet. -Dieser Artikel geht der Frage nach, wie Maven Artefakte auflöst, welche Rolle die Manager und Requests des Maven Resolvers dabei spielen, was in der unscheinbaren Datei `_remote.repositories` steht, und wie sich daraus eine konkrete Verbesserung für das Apache Maven Artifact Plugin ableiten lässt. +Hier wollen wir die Frage beantworten, wie Maven Artefakte auflöst und verwaltet, was in der unscheinbaren Datei `_remote.repositories` steht, und wie sich daraus eine konkrete Verbesserung für das Apache Maven Artifact Plugin ableiten lässt. ## Warum die Herkunft ein Supply-Chain-Thema ist -Das Maven Artifact Plugin ist das Werkzeug, mit dem im Maven-Ökosystem Reproducible Builds nachgewiesen werden. Das Ziel `artifact:buildinfo` erzeugt eine Beschreibung des Build-Ergebnisses inklusive Checksummen, und `artifact:compare` vergleicht das Ergebnis des aktuellen Builds mit einer Referenz. Wenn beide übereinstimmen, ist gezeigt, dass die veröffentlichten Artefakte tatsächlich aus dem angegebenen Quellcode entstanden sein können. +Das [Maven Artifact Plugin](https://maven.apache.org/plugins/maven-artifact-plugin/) ist das Werkzeug, mit dem im Maven-Ökosystem Reproducible Builds nachgewiesen werden. Das Ziel `artifact:buildinfo` erzeugt eine Beschreibung des Build-Ergebnisses inklusive Checksummen, und `artifact:compare` vergleicht das Ergebnis des aktuellen Builds mit einer Referenz. Wenn beide übereinstimmen, ist gezeigt, dass die veröffentlichten Artefakte tatsächlich aus dem angegebenen Quellcode entstanden sein können. Ein Vergleich ist allerdings nur so gut wie sein Vergleichsmaßstab. Wenn eine der beteiligten Abhängigkeiten nicht aus einem öffentlichen Repository stammt, sondern aus einem `mvn install`, das vor drei Wochen auf demselben Rechner gelaufen ist, dann vergleicht man am Ende ein lokales Ergebnis mit einem anderen lokalen Ergebnis. Das Resultat sieht sauber aus, es sagt aber nichts über die öffentlich veröffentlichten Artefakte aus. Aus Supply-Chain-Sicht ist ein lokal installiertes Artefakt ein Eingang in den Build, der von niemandem geprüft wurde, weder durch eine Signatur noch durch eine Checksumme gegen ein Remote-Repository. -Genau diese Lücke wurde in MARTIFACT-58 beschrieben. Seine Beobachtung: `artifact:compare` vergleicht die Ausgabe des aktuellen Builds mit Inhalten aus dem lokalen Repository, und was sich dabei nicht leicht erkennen lässt, ist, ob dieser Inhalt aus einem früheren lokalen `mvn install` stammt oder aus einem Remote-Repository heruntergeladen wurde. Sein Vorschlag war, dass das Plugin diese Information selbst ermitteln und anzeigen könnte. +Genau diese Lücke wurde in [MARTIFACT-58](https://github.com/apache/maven-artifact-plugin/issues/146) beschrieben. Seine Beobachtung: `artifact:compare` vergleicht die Ausgabe des aktuellen Builds mit Inhalten aus dem lokalen Repository, und was sich dabei nicht leicht erkennen lässt, ist, ob dieser Inhalt aus einem früheren lokalen `mvn install` stammt oder aus einem Remote-Repository heruntergeladen wurde. Sein Vorschlag war, dass das Plugin diese Information selbst ermitteln und anzeigen könnte. ## Das lokale Repository als gemischte Ablage -Die Maven-Dokumentation beschreibt das lokale Repository offen als gemischte Ablage, die zwei Aufgaben gleichzeitig erfüllt: Sie ist Cache für Artefakte, die von einem Remote-Repository geladen wurden, und sie ist Ablage für Artefakte, die lokal gebaut und installiert wurden. Beide landen im selben Layout, also unter demselben Pfad aus GroupId, ArtifactId und Version. Aus dem Pfad allein lässt sich die Herkunft folglich nicht ablesen. +Die [Maven-Dokumentation](https://maven.apache.org/guides/introduction/introduction-to-repositories.html) beschreibt das lokale Repository als gemischte Ablage, die zwei Aufgaben gleichzeitig erfüllt: Sie ist Cache für Artefakte, die von einem Remote-Repository geladen wurden, und sie ist Ablage für Artefakte, die lokal gebaut und installiert wurden. Beide landen im selben Layout, also unter demselben Pfad aus GroupId, ArtifactId und Version. Aus dem Pfad allein lässt sich die Herkunft folglich nicht ablesen. Die Dokumentation ist an dieser Stelle sehr deutlich: Nutzer sollen niemals mit einfachen Dateioperationen direkt in das lokale Repository greifen, sondern immer die bereitgestellte API verwenden. Der Grund ist, dass es heute mehrere Implementierungen des lokalen Repositorys gibt, dass sich das Layout ändern kann, und dass direkter Dateizugriff wichtige Aspekte wie Locking und Synchronisation umgeht. Wer die Herkunftsfrage beantworten will, sollte sie also über die API stellen. -## Die Manager im Maven Resolver +## Wie Maven das lokale Repository verwaltet -Unterhalb von Maven arbeitet der Maven Artifact Resolver, das frühere Aether. Er kapselt alles, was mit Repositories zu tun hat, hinter dem Einstiegspunkt `RepositorySystem` und einer `RepositorySystemSession`, die die aktuelle Konfiguration des Builds trägt. +Unterhalb von Maven arbeitet der Maven Artifact Resolver, das frühere Aether. Er kapselt alles, was mit Repositories zu tun hat, also das Auflösen von Koordinaten, das Herunterladen, das Zwischenspeichern und das Installieren. Für das lokale Repository ist dabei eine eigene Verwaltungsschicht zuständig, und die zur Laufzeit verwendete Variante tut mehr, als Dateien an der richtigen Stelle abzulegen. Sie führt Buch darüber, aus welchem Repository ein zwischengespeichertes Artefakt ursprünglich stammt. -Für das lokale Repository ist der `LocalRepositoryManager` zuständig, kurz LRM. Der Resolver bringt zwei Implementierungen mit. Die Variante `simple` ist funktionsfähig, aber vor allem für Tests gedacht und nicht für den produktiven Einsatz empfohlen. Die Variante `enhanced` ist die zur Laufzeit verwendete, und sie ist genau dort erweitert, wo es für dieses Thema zählt: Sie merkt sich, aus welchem Repository ein gecachtes Artefakt aufgelöst wurde. +Diese Buchführung hat einen ganz praktischen Zweck. Wenn ein Artefakt aus einem Repository R1 geladen wurde und ein späterer Build dasselbe Artefakt benötigt, R1 aber nicht kennt, dann gilt das lokal vorhandene Artefakt als nicht vorhanden und wird erneut geladen. Die Begründung ist ein Vertrauensargument: Zwei Artefakte mit identischen Koordinaten aus zwei verschiedenen Repositories müssen nicht dasselbe sein. Dieselbe Mechanik erklärt übrigens die gelegentlich verwirrende Fehlermeldung, dass ein Artefakt nicht auflösbar sei, obwohl es sichtbar im Verzeichnis liegt. -Diese Buchführung hat einen ganz praktischen Zweck. Wenn ein Artefakt A1 aus dem Repository R1 geladen wurde und ein späterer Build dasselbe Artefakt benötigt, R1 aber nicht kennt, dann behandelt der Enhanced LRM das lokal vorhandene A1 als nicht vorhanden und lädt es erneut. Die Begründung ist ein Vertrauensargument: Zwei Artefakte mit identischen Koordinaten aus zwei verschiedenen Repositories müssen nicht dasselbe sein. Dieselbe Mechanik erklärt übrigens die gelegentlich verwirrende Fehlermeldung, dass ein Artefakt nicht auflösbar sei, obwohl es sichtbar im Verzeichnis liegt. +Erwähnenswert ist außerdem eine Möglichkeit, die standardmäßig nicht aktiv ist, sich aber über Konfigurationsschalter einschalten lässt. Maven kann das lokale Repository physisch aufteilen, nämlich nach zwischengespeichert und lokal installiert, nach Herkunftsrepository, sowie nach Release und Snapshot. Wer regelmäßig Rebuilds verifiziert, bekommt damit ein sehr direktes Werkzeug in die Hand, denn dann lassen sich alle lokal installierten Artefakte löschen, ohne dass anschließend das halbe Internet erneut heruntergeladen werden muss. -Ergänzend gibt es weitere Manager und Komponenten, die in derselben Schicht arbeiten. Der `RemoteRepositoryManager` aggregiert Repositories, wendet Mirrors an und verwaltet Update-Policies. Ein `WorkspaceReader` erlaubt es, Artefakte aus dem laufenden Reactor oder einer IDE zu beziehen, ohne dass sie überhaupt installiert werden. Und der Chained Local Repository Manager kombiniert ein schreibbares LRM mit einer Liste nur lesbarer weiterer lokaler Repositories, was insbesondere für verschachtelte Builds hilfreich ist. - -Erwähnenswert ist außerdem das Split-Feature des Enhanced LRM. Es ist standardmäßig deaktiviert, kann aber über Konfigurationsschalter aktiviert werden und trennt den Inhalt des lokalen Repositorys physisch, nämlich nach gecacht und lokal installiert, nach Herkunftsrepository, sowie nach Release und Snapshot. Wer regelmäßig Rebuilds verifiziert, bekommt damit ein sehr direktes Werkzeug in die Hand, denn dann lassen sich alle lokal installierten Artefakte löschen, ohne dass anschließend das halbe Internet erneut heruntergeladen werden muss. - -## Die Requests im Maven Resolver - -Die Resolver-API ist konsequent nach dem Muster Request und Result aufgebaut, und die verschiedenen Request-Typen entsprechen den verschiedenen Fragen, die man an ein Repository stellen kann. - -`VersionRequest` und `VersionRangeRequest` klären Koordinaten, etwa die Auflösung eines Versionsbereichs oder die Übersetzung einer Snapshot-Version in eine konkrete Zeitstempelversion. Der `ArtifactDescriptorRequest` liest die Beschreibung eines Artefakts, also im Wesentlichen dessen POM inklusive direkter Abhängigkeiten und möglicher Relocations. Der `CollectRequest` baut daraus einen Abhängigkeitsgraphen auf und liefert im `CollectResult` einen Baum aus `DependencyNode`-Objekten, ohne dabei die eigentlichen Dateien herunterzuladen. Der `DependencyRequest` geht einen Schritt weiter und löst zusätzlich die Dateien des Graphen auf. Der `ArtifactRequest` schließlich fragt nach genau einem Artefakt und liefert ein `ArtifactResult` zurück. Daneben stehen `MetadataRequest` für Repository-Metadaten, `LocalArtifactRequest` als Frage direkt an das lokale Repository, sowie `InstallRequest` und `DeployRequest` für den Weg nach außen. - -Die Trennung zwischen Sammeln und Auflösen ist für unsere Fragestellung der entscheidende Punkt. Man kann den vollständigen Abhängigkeitsbaum aufbauen, ohne Downloads auszulösen, und danach gezielt einzelne Knoten auflösen, um zu erfahren, woher sie kommen. Denn `ArtifactResult` trägt eine Methode `getRepository()`, und diese liefert das Repository, aus dem das Artefakt tatsächlich bezogen wurde. +Bleibt die Frage, wo diese Buchführung eigentlich liegt, und die Antwort ist eine einzelne, leicht zu übersehende Datei. ## Die Datei `_remote.repositories` -Damit `getRepository()` überhaupt eine sinnvolle Antwort geben kann, muss die Information irgendwo persistiert sein, und genau das ist die Aufgabe der Tracking-Datei `_remote.repositories`. Der Enhanced LRM legt sie in jedem Verzeichnis des lokalen Repositorys an, in dem er Artefakte verwaltet. Ihr Name ist konfigurierbar, der Standard ist der genannte. +Die Herkunftsinformation, die Maven beim Herunterladen mitschreibt, landet in der Tracking-Datei `_remote.repositories`. Maven legt sie in jedem Verzeichnis des lokalen Repositorys an, in dem Artefakte verwaltet werden. Ihr Name ist konfigurierbar, der Standard ist der genannte. Der Inhalt ist eine Java-Properties-Datei. Die Schlüssel bestehen aus dem Dateinamen, einem `>` als Trenner und der Id des Repositorys, aus dem die Datei bezogen wurde. Der Wert bleibt leer. Ein Verzeichnis kann damit etwa so aussehen: @@ -64,15 +54,15 @@ artifact-1.0.jar>central= artifact-1.0.pom>my_repo_id= ``` -Der entscheidende Sonderfall ist die leere Repository-Id. Ein Eintrag der Form `artifact-1.0.jar>=` bedeutet, dass diese Datei nicht heruntergeladen, sondern lokal installiert wurde. Der Resolver verwendet dafür intern eine Konstante mit dem Wert einer leeren Zeichenkette. Fehlt zu einer vorhandenen Datei jeglicher Eintrag, dann behandelt der Enhanced LRM sie ebenfalls als lokal installiert, und zwar aus Kompatibilität mit dem Simple LRM, der keine Tracking-Datei schreibt. +Der entscheidende Sonderfall ist die leere Repository-Id. Ein Eintrag der Form `artifact-1.0.jar>=` bedeutet, dass diese Datei nicht heruntergeladen, sondern lokal installiert wurde. Fehlt zu einer vorhandenen Datei jeglicher Eintrag, dann gilt sie ebenfalls als lokal installiert. -Diese Datei ist damit die eigentliche Antwort auf MARTIFACT-58, allerdings nicht als Datei, die man selbst lesen sollte. Sie trägt ihren Warnhinweis im Kopf, ihr Format kann sich jederzeit ändern, ihr Name ist konfigurierbar, und bei aktiviertem Split-Feature liegt sie ohnehin an einem anderen Ort als erwartet. Der richtige Weg führt über die API, und dort ist die Information bereits aufbereitet: `LocalArtifactResult.getRepository()` liefert das Remote-Repository, aus dem ein Artefakt gecacht wurde, und `null`, wenn es lokal installiert wurde. Der `DefaultArtifactResolver` übersetzt diesen Fall nach oben, indem er im `ArtifactResult` das lokale Repository einträgt. Aus der leeren Repository-Id in einer Textdatei wird auf diesem Weg eine Instanz von `LocalRepository` in der Plugin-API. +Diese Datei ist damit die eigentliche Antwort auf MARTIFACT-58, allerdings nicht als Datei, die man selbst lesen sollte. Sie trägt ihren Warnhinweis im Kopf, ihr Format kann sich jederzeit ändern, ihr Name ist konfigurierbar, und bei aufgeteiltem lokalen Repository liegt sie ohnehin an einem anderen Ort als erwartet. Der richtige Weg führt über die API, und dort ist die Information bereits aufbereitet. Wer ein Artefakt auflöst, erfährt gleich mit, aus welchem Repository es kam, und im Fall einer lokalen Installation ist das eben das lokale Repository selbst. Aus der leeren Repository-Id in einer Textdatei wird auf diesem Weg eine schlichte Ja-oder-Nein-Frage, die ein Plugin stellen kann. ## Die Umsetzung im Maven Artifact Plugin -Genau diese Kette nutzt der Pull Request [#227](https://github.com/apache/maven-artifact-plugin/pull/227) für das Apache Maven Artifact Plugin. Die Änderung sitzt in `ReferenceBuildinfoUtil`, also dort, wo das Plugin die Referenz für den Vergleich ermittelt, und wird aus `CompareMojo` aufgerufen, das nun die `RepositorySystemSession` und die Liste der Remote-Repositories durchreicht. +Genau diese Möglichkeit nutzt der Pull Request [#227](https://github.com/apache/maven-artifact-plugin/pull/227) für das Apache Maven Artifact Plugin. Die Änderung sitzt dort, wo das Plugin die Referenz für den Vergleich ermittelt, und sie bekommt vom Vergleichsziel die aktuelle Repository-Konfiguration des Builds mitgegeben. -Der Ablauf ist bewusst schlicht. Zunächst wird über einen `CollectRequest` der Abhängigkeitsbaum des betrachteten Artefakts gesammelt, was ohne Downloads geschieht. Anschließend wird der Baum traversiert, und für jeden betrachteten Knoten wird ein `ArtifactRequest` gestellt, dem explizit die Remote-Repositories des Projekts mitgegeben werden. Aus dem `ArtifactResult` wird das Repository ausgelesen, und wenn dieses eine `LocalRepository` ist, dann steht fest, dass das Artefakt aus einer lokalen Installation stammt. +Der Ablauf ist bewusst schlicht. Zunächst wird der Abhängigkeitsbaum des betrachteten Artefakts aufgebaut, ohne dass dabei Dateien heruntergeladen werden. Anschließend wird der Baum durchlaufen, und jedes betrachtete Artefakt wird gegen die Remote-Repositories des Projekts aufgelöst. Stellt sich dabei heraus, dass die Auflösung im lokalen Repository geendet hat, dann stammt das Artefakt aus einer lokalen Installation. In diesem Fall gibt das Plugin eine Warnung aus: @@ -86,11 +76,11 @@ matches public reference from remote. Drei Details an dieser Meldung sind das Ergebnis des Reviews und lohnen einen Blick. Erstens wurde die Formulierung von der ursprünglichen Fassung präzisiert, denn die Aussage lautet nicht, dass das Artefakt aus dem lokalen Repository kommt, was auf jedes gecachte Artefakt zutreffen würde, sondern dass es aus einer lokalen Installation in dieses Repository stammt. Zweitens benennt die Meldung ausdrücklich das eigentliche Risiko, nämlich dass das lokal installierte Artefakt der öffentlich veröffentlichten Referenz entsprechen muss. Drittens enthält sie den absoluten Pfad, damit man die betroffene Datei direkt löschen und den Build wiederholen kann. -Bewusst gewählt ist auch, dass es sich um eine Warnung handelt und nicht um einen Fehler. Lokale Installationen sind ein legitimer Teil vieler Arbeitsabläufe, etwa bei Multi-Modul-Projekten oder beim Testen eines noch nicht veröffentlichten Snapshots. Der Build soll deshalb weiterlaufen, aber die Information soll sichtbar sein. Aus demselben Grund führt ein Fehlschlag der Prüfung selbst nur zu einer weiteren Warnung und nicht zum Abbruch. Ein Integrationstest im Szenario `compare-mono` prüft, dass die Warnung tatsächlich im Build-Log erscheint, damit die Zusage nicht unbemerkt verloren geht. +Bewusst gewählt ist auch, dass es sich um eine Warnung handelt und nicht um einen Fehler. Lokale Installationen sind ein legitimer Teil vieler Arbeitsabläufe, etwa bei Multi-Modul-Projekten oder beim Testen eines noch nicht veröffentlichten Snapshots. Der Build soll deshalb weiterlaufen, aber die Information soll sichtbar sein. Aus demselben Grund führt ein Fehlschlag der Prüfung selbst nur zu einer weiteren Warnung und nicht zum Abbruch. Ein Integrationstest prüft, dass die Warnung tatsächlich im Build-Log erscheint, damit die Zusage nicht unbemerkt verloren geht. ## Was sich daraus für die Praxis ergibt -Für Anwender bedeutet die Änderung, dass ein Reproducible-Build-Vergleich künftig von selbst darauf hinweist, wenn seine Grundlage nicht so belastbar ist, wie sie aussieht. Wer Rebuilds systematisch verifiziert, sollte darüber hinaus zwei Dinge in Betracht ziehen. Zum einen lohnt es sich, Verifikationsbuilds in einem separaten lokalen Repository laufen zu lassen, damit lokal installierte Artefakte gar nicht in Reichweite kommen. Zum anderen ist das Split-Feature des Enhanced LRM genau für diese Art von Hygiene gedacht, denn es macht die Trennung zwischen selbst gebauten und heruntergeladenen Artefakten physisch sichtbar und erlaubt gezieltes Aufräumen. +Für Anwender bedeutet die Änderung, dass ein Reproducible-Build-Vergleich künftig von selbst darauf hinweist, wenn seine Grundlage nicht so belastbar ist, wie sie aussieht. Wer Rebuilds systematisch verifiziert, sollte darüber hinaus zwei Dinge in Betracht ziehen. Zum einen lohnt es sich, Verifikationsbuilds in einem separaten lokalen Repository laufen zu lassen, damit lokal installierte Artefakte gar nicht in Reichweite kommen. Zum anderen ist die oben erwähnte Aufteilung des lokalen Repositorys genau für diese Art von Hygiene gedacht, denn sie macht die Trennung zwischen selbst gebauten und heruntergeladenen Artefakten physisch sichtbar und erlaubt gezieltes Aufräumen. Der allgemeinere Punkt aber ist, dass die Information über die Herkunft eines Artefakts in Maven längst vorhanden war. Sie lag in einer internen Datei, die man nicht anfassen soll, und war über eine API erreichbar, die man dafür kennen muss. Was gefehlt hat, war die Verbindung zwischen dieser vorhandenen Information und der Stelle, an der sie eine Entscheidung beeinflusst. Solche Verbindungen zu ziehen ist ein guter Teil der Arbeit an Supply-Chain-Sicherheit, und sie besteht seltener aus neuen Mechanismen als aus dem Sichtbarmachen dessen, was das Werkzeug längst weiß. From 5ab19d51f9dee0fc53300867b56ece94c2da2a7b Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Thu, 3 Sep 2026 10:19:46 +0200 Subject: [PATCH 4/9] polish the content, remove some unimportant details --- .../2026-08-xx-maven-artefakt-herkunft.md | 99 +++++++++++++------ 1 file changed, 70 insertions(+), 29 deletions(-) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.md index aee32cc8..4366052d 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.md @@ -11,41 +11,74 @@ preview_image: "/posts/preview-images/oss-world.svg" --- -# Woher kommt dieses Artefakt eigentlich? Maven, das lokale Repository und die Datei `_remote.repositories` +# Woher kommt dieses Artefakt eigentlich? Vom Maven Repository und der Datei `_remote.repositories` -Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den ersten Blick nicht ansehen kann, woher sein Inhalt stammt. Technisch haben wir das Thema bereits in einem anderen [Blogpost](https://open-elements.com/posts/2025/09/12/reproducible-builds) im Kontext von Apache Maven und den Auswirkungen auf die Supply Chain beleuchtet. +Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, +Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es +interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den +ersten Blick nicht ansehen kann, woher sein Inhalt stammt. Technisch haben wir das Thema Reproducible Builds bereits +in einem anderen [Blogpost](https://open-elements.com/posts/2025/09/12/reproducible-builds) im Kontext von Apache Maven +und den Auswirkungen auf die Supply Chain beleuchtet. -Hier wollen wir die Frage beantworten, wie Maven Artefakte auflöst und verwaltet, was in der unscheinbaren Datei `_remote.repositories` steht, und wie sich daraus eine konkrete Verbesserung für das Apache Maven Artifact Plugin ableiten lässt. +Hier wollen wir die Frage beantworten, wie Maven Artefakte auflöst und verwaltet, was in der +unscheinbaren Datei `_remote.repositories` steht, und wie sich daraus eine konkrete Verbesserung für +das Apache Maven Artifact Plugin und am Ende sogar die Supply Chain integrieren lässt. ## Warum die Herkunft ein Supply-Chain-Thema ist -Das [Maven Artifact Plugin](https://maven.apache.org/plugins/maven-artifact-plugin/) ist das Werkzeug, mit dem im Maven-Ökosystem Reproducible Builds nachgewiesen werden. Das Ziel `artifact:buildinfo` erzeugt eine Beschreibung des Build-Ergebnisses inklusive Checksummen, und `artifact:compare` vergleicht das Ergebnis des aktuellen Builds mit einer Referenz. Wenn beide übereinstimmen, ist gezeigt, dass die veröffentlichten Artefakte tatsächlich aus dem angegebenen Quellcode entstanden sein können. - -Ein Vergleich ist allerdings nur so gut wie sein Vergleichsmaßstab. Wenn eine der beteiligten Abhängigkeiten nicht aus einem öffentlichen Repository stammt, sondern aus einem `mvn install`, das vor drei Wochen auf demselben Rechner gelaufen ist, dann vergleicht man am Ende ein lokales Ergebnis mit einem anderen lokalen Ergebnis. Das Resultat sieht sauber aus, es sagt aber nichts über die öffentlich veröffentlichten Artefakte aus. Aus Supply-Chain-Sicht ist ein lokal installiertes Artefakt ein Eingang in den Build, der von niemandem geprüft wurde, weder durch eine Signatur noch durch eine Checksumme gegen ein Remote-Repository. - -Genau diese Lücke wurde in [MARTIFACT-58](https://github.com/apache/maven-artifact-plugin/issues/146) beschrieben. Seine Beobachtung: `artifact:compare` vergleicht die Ausgabe des aktuellen Builds mit Inhalten aus dem lokalen Repository, und was sich dabei nicht leicht erkennen lässt, ist, ob dieser Inhalt aus einem früheren lokalen `mvn install` stammt oder aus einem Remote-Repository heruntergeladen wurde. Sein Vorschlag war, dass das Plugin diese Information selbst ermitteln und anzeigen könnte. +Das [Maven Artifact Plugin](https://maven.apache.org/plugins/maven-artifact-plugin/) ist das Werkzeug, mit dem im +Maven-Ökosystem Reproducible Builds nachgewiesen werden. Das Goal `artifact:buildinfo` erzeugt eine Beschreibung des +Build-Ergebnisses inklusive Checksummen, und `artifact:compare` vergleicht das Ergebnis des aktuellen Builds mit einer +Referenz. Wenn beide übereinstimmen, ist gezeigt, dass die veröffentlichten Artefakte tatsächlich aus dem angegebenen +Quellcode entstanden sein können. + +Ein Vergleich ist allerdings nur so gut wie sein Vergleichsmaßstab. Wenn eine der beteiligten Abhängigkeiten nicht aus +einem öffentlichen Repository stammt, sondern lokal via `mvn install` vor drei Wochen auf demselben Rechner +gebaut worden sind, dann vergleicht man am Ende ein lokales Ergebnis mit einem anderen lokalen Ergebnis. Das Resultat +sieht sauber aus, es sagt aber nichts über die veröffentlichten Artefakte aus. Aus Supply-Chain-Perspektive ist ein +lokal installiertes Artefakt ein Input in den Build, der von niemandem geprüft wurde, weder durch eine Signatur noch +durch eine Checksumme gegen ein Remote-Repository. Wie sich in der Vergangenheit gezeigt hat, könnte hier bereits +eine böswillige Manipulation stattgefunden haben, mehr dazu auf [hier](https://reproducible-builds.org/docs/why/) +von (reproducible-builds.org)[https://reproducible-builds.org] + +Genau diese Lücke wurde in [MARTIFACT-58](https://github.com/apache/maven-artifact-plugin/issues/146) beschrieben. +Die Beobachtung: `artifact:compare` vergleicht die Ausgabe des aktuellen Builds mit Inhalten aus dem lokalen Repository, +und was sich dabei nicht leicht erkennen lässt, ist, ob dieser Inhalt aus einem früheren lokalen `mvn install` stammt +oder aus einem Remote-Repository heruntergeladen wurde. Der Vorschlag war, dass das Plugin diese Information selbst +ermitteln und anzeigen könnte. ## Das lokale Repository als gemischte Ablage -Die [Maven-Dokumentation](https://maven.apache.org/guides/introduction/introduction-to-repositories.html) beschreibt das lokale Repository als gemischte Ablage, die zwei Aufgaben gleichzeitig erfüllt: Sie ist Cache für Artefakte, die von einem Remote-Repository geladen wurden, und sie ist Ablage für Artefakte, die lokal gebaut und installiert wurden. Beide landen im selben Layout, also unter demselben Pfad aus GroupId, ArtifactId und Version. Aus dem Pfad allein lässt sich die Herkunft folglich nicht ablesen. - -Die Dokumentation ist an dieser Stelle sehr deutlich: Nutzer sollen niemals mit einfachen Dateioperationen direkt in das lokale Repository greifen, sondern immer die bereitgestellte API verwenden. Der Grund ist, dass es heute mehrere Implementierungen des lokalen Repositorys gibt, dass sich das Layout ändern kann, und dass direkter Dateizugriff wichtige Aspekte wie Locking und Synchronisation umgeht. Wer die Herkunftsfrage beantworten will, sollte sie also über die API stellen. +Für die Umsetzung ist ein Blick und das Verstehen der Funktionsweise des lokalen Maven-Repositories notwendig. +Die [Maven-Dokumentation](https://maven.apache.org/guides/introduction/introduction-to-repositories.html) beschreibt +dies als gemischte Ablage, die zwei Aufgaben gleichzeitig erfüllt: Sie ist Cache für Artefakte, +die von einem Remote-Repository geladen wurden, und sie ist Ablage für Artefakte, die lokal gebaut und installiert +wurden. Beide landen im selben Layout, also unter demselben Pfad aus GroupId, ArtifactId und Version. Aus dem Pfad +allein lässt sich die Herkunft folglich nicht ablesen. ## Wie Maven das lokale Repository verwaltet -Unterhalb von Maven arbeitet der Maven Artifact Resolver, das frühere Aether. Er kapselt alles, was mit Repositories zu tun hat, also das Auflösen von Koordinaten, das Herunterladen, das Zwischenspeichern und das Installieren. Für das lokale Repository ist dabei eine eigene Verwaltungsschicht zuständig, und die zur Laufzeit verwendete Variante tut mehr, als Dateien an der richtigen Stelle abzulegen. Sie führt Buch darüber, aus welchem Repository ein zwischengespeichertes Artefakt ursprünglich stammt. - -Diese Buchführung hat einen ganz praktischen Zweck. Wenn ein Artefakt aus einem Repository R1 geladen wurde und ein späterer Build dasselbe Artefakt benötigt, R1 aber nicht kennt, dann gilt das lokal vorhandene Artefakt als nicht vorhanden und wird erneut geladen. Die Begründung ist ein Vertrauensargument: Zwei Artefakte mit identischen Koordinaten aus zwei verschiedenen Repositories müssen nicht dasselbe sein. Dieselbe Mechanik erklärt übrigens die gelegentlich verwirrende Fehlermeldung, dass ein Artefakt nicht auflösbar sei, obwohl es sichtbar im Verzeichnis liegt. +Unterhalb von Maven arbeitet der Maven Artifact Resolver, das frühere Aether. Es kapselt alles, was mit Repositories +zu tun hat, also das Auflösen von Koordinaten, das Herunterladen, das Zwischenspeichern und das Installieren. +Für das lokale Repository ist dabei eine eigene Verwaltungsschicht zuständig, und die zur Laufzeit verwendete Variante +tut mehr, als Dateien an der richtigen Stelle abzulegen. Sie führt Buch darüber, aus welchem Repository ein +zwischengespeichertes Artefakt ursprünglich stammt. -Erwähnenswert ist außerdem eine Möglichkeit, die standardmäßig nicht aktiv ist, sich aber über Konfigurationsschalter einschalten lässt. Maven kann das lokale Repository physisch aufteilen, nämlich nach zwischengespeichert und lokal installiert, nach Herkunftsrepository, sowie nach Release und Snapshot. Wer regelmäßig Rebuilds verifiziert, bekommt damit ein sehr direktes Werkzeug in die Hand, denn dann lassen sich alle lokal installierten Artefakte löschen, ohne dass anschließend das halbe Internet erneut heruntergeladen werden muss. +Diese Buchführung hat einen ganz praktischen Zweck. Wenn ein Artefakt aus einem Repository R1 geladen wurde und ein +späterer Build dasselbe Artefakt benötigt, R1 aber nicht kennt, dann gilt das lokal vorhandene Artefakt als nicht +vorhanden und wird erneut geladen. Die Begründung ist ein Vertrauensargument: Zwei Artefakte mit identischen +Koordinaten aus zwei verschiedenen Repositories müssen nicht dasselbe sein. Dieselbe Mechanik erklärt übrigens die +gelegentlich verwirrende Fehlermeldung, dass ein Artefakt nicht auflösbar sei, obwohl es sichtbar im Verzeichnis liegt. Bleibt die Frage, wo diese Buchführung eigentlich liegt, und die Antwort ist eine einzelne, leicht zu übersehende Datei. ## Die Datei `_remote.repositories` -Die Herkunftsinformation, die Maven beim Herunterladen mitschreibt, landet in der Tracking-Datei `_remote.repositories`. Maven legt sie in jedem Verzeichnis des lokalen Repositorys an, in dem Artefakte verwaltet werden. Ihr Name ist konfigurierbar, der Standard ist der genannte. +Die Herkunftsinformation, die Maven beim Herunterladen mitschreibt, landet in der Tracking-Datei `_remote.repositories`. +Maven legt sie in jedem Verzeichnis des lokalen Repositorys an, in dem Artefakte verwaltet werden. -Der Inhalt ist eine Java-Properties-Datei. Die Schlüssel bestehen aus dem Dateinamen, einem `>` als Trenner und der Id des Repositorys, aus dem die Datei bezogen wurde. Der Wert bleibt leer. Ein Verzeichnis kann damit etwa so aussehen: +Der Inhalt ist eine Java-Properties-Datei. Die Schlüssel bestehen aus dem Dateinamen, einem `>` als Trenner und der Id +des Repositorys, aus dem die Datei bezogen wurde. Der Wert bleibt leer. Ein Verzeichnis kann damit etwa so aussehen: ``` #NOTE: This is a Maven Resolver internal implementation file, its format can be changed without prior notice. @@ -54,17 +87,26 @@ artifact-1.0.jar>central= artifact-1.0.pom>my_repo_id= ``` -Der entscheidende Sonderfall ist die leere Repository-Id. Ein Eintrag der Form `artifact-1.0.jar>=` bedeutet, dass diese Datei nicht heruntergeladen, sondern lokal installiert wurde. Fehlt zu einer vorhandenen Datei jeglicher Eintrag, dann gilt sie ebenfalls als lokal installiert. +Der entscheidende Sonderfall ist die leere Repository-Id. Ein Eintrag der Form `artifact-1.0.jar>=` bedeutet, dass diese +Datei nicht heruntergeladen, sondern lokal installiert wurde. Fehlt zu einer vorhandenen Datei jeglicher Eintrag, +dann gilt sie intern ebenfalls als lokal installiert. -Diese Datei ist damit die eigentliche Antwort auf MARTIFACT-58, allerdings nicht als Datei, die man selbst lesen sollte. Sie trägt ihren Warnhinweis im Kopf, ihr Format kann sich jederzeit ändern, ihr Name ist konfigurierbar, und bei aufgeteiltem lokalen Repository liegt sie ohnehin an einem anderen Ort als erwartet. Der richtige Weg führt über die API, und dort ist die Information bereits aufbereitet. Wer ein Artefakt auflöst, erfährt gleich mit, aus welchem Repository es kam, und im Fall einer lokalen Installation ist das eben das lokale Repository selbst. Aus der leeren Repository-Id in einer Textdatei wird auf diesem Weg eine schlichte Ja-oder-Nein-Frage, die ein Plugin stellen kann. +Diese Datei ist damit essentiell für die Basis für die Lösung von MARTIFACT-58. +Über die API lässt sich herausbekommen, aus welchem Repository ein Artefakt kam, und im Fall einer lokalen Installation +ist das eben das lokale Repository selbst. ## Die Umsetzung im Maven Artifact Plugin -Genau diese Möglichkeit nutzt der Pull Request [#227](https://github.com/apache/maven-artifact-plugin/pull/227) für das Apache Maven Artifact Plugin. Die Änderung sitzt dort, wo das Plugin die Referenz für den Vergleich ermittelt, und sie bekommt vom Vergleichsziel die aktuelle Repository-Konfiguration des Builds mitgegeben. +Genau diese Möglichkeit nutzt der Pull Request [#227](https://github.com/apache/maven-artifact-plugin/pull/227) für das +Apache Maven Artifact Plugin. Die Änderung sitzt dort, wo das Plugin die Referenz für den Vergleich ermittelt, +und sie bekommt vom Vergleichsziel die aktuelle Repository-Konfiguration des Builds mitgegeben. -Der Ablauf ist bewusst schlicht. Zunächst wird der Abhängigkeitsbaum des betrachteten Artefakts aufgebaut, ohne dass dabei Dateien heruntergeladen werden. Anschließend wird der Baum durchlaufen, und jedes betrachtete Artefakt wird gegen die Remote-Repositories des Projekts aufgelöst. Stellt sich dabei heraus, dass die Auflösung im lokalen Repository geendet hat, dann stammt das Artefakt aus einer lokalen Installation. +Zusätzlich zum zu prüfenden Artefakt ist es ebenso wichtig, den Abhängigkeitsbaum des jeweiligen Artefakts zu +durchlaufen, falls noch weitere enthaltene Komponenten oder deren Kind-Abhängigkeiten lokal gebaut wurden. -In diesem Fall gibt das Plugin eine Warnung aus: +Sollte das der Fall sein, findet sich anschließend folgende Art von Warnung im Log mit der dringenden Empfehlung, +den Build nachzuprüfen und potentiell lokal gefundene Artefakte zu löschen, um auf die Versionen des +Remote-Repositories zurückzugreifen: ``` The artifact org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your @@ -74,15 +116,14 @@ from /home/user/.m2/repository/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar matches public reference from remote. ``` -Drei Details an dieser Meldung sind das Ergebnis des Reviews und lohnen einen Blick. Erstens wurde die Formulierung von der ursprünglichen Fassung präzisiert, denn die Aussage lautet nicht, dass das Artefakt aus dem lokalen Repository kommt, was auf jedes gecachte Artefakt zutreffen würde, sondern dass es aus einer lokalen Installation in dieses Repository stammt. Zweitens benennt die Meldung ausdrücklich das eigentliche Risiko, nämlich dass das lokal installierte Artefakt der öffentlich veröffentlichten Referenz entsprechen muss. Drittens enthält sie den absoluten Pfad, damit man die betroffene Datei direkt löschen und den Build wiederholen kann. - -Bewusst gewählt ist auch, dass es sich um eine Warnung handelt und nicht um einen Fehler. Lokale Installationen sind ein legitimer Teil vieler Arbeitsabläufe, etwa bei Multi-Modul-Projekten oder beim Testen eines noch nicht veröffentlichten Snapshots. Der Build soll deshalb weiterlaufen, aber die Information soll sichtbar sein. Aus demselben Grund führt ein Fehlschlag der Prüfung selbst nur zu einer weiteren Warnung und nicht zum Abbruch. Ein Integrationstest prüft, dass die Warnung tatsächlich im Build-Log erscheint, damit die Zusage nicht unbemerkt verloren geht. - ## Was sich daraus für die Praxis ergibt -Für Anwender bedeutet die Änderung, dass ein Reproducible-Build-Vergleich künftig von selbst darauf hinweist, wenn seine Grundlage nicht so belastbar ist, wie sie aussieht. Wer Rebuilds systematisch verifiziert, sollte darüber hinaus zwei Dinge in Betracht ziehen. Zum einen lohnt es sich, Verifikationsbuilds in einem separaten lokalen Repository laufen zu lassen, damit lokal installierte Artefakte gar nicht in Reichweite kommen. Zum anderen ist die oben erwähnte Aufteilung des lokalen Repositorys genau für diese Art von Hygiene gedacht, denn sie macht die Trennung zwischen selbst gebauten und heruntergeladenen Artefakten physisch sichtbar und erlaubt gezieltes Aufräumen. - -Der allgemeinere Punkt aber ist, dass die Information über die Herkunft eines Artefakts in Maven längst vorhanden war. Sie lag in einer internen Datei, die man nicht anfassen soll, und war über eine API erreichbar, die man dafür kennen muss. Was gefehlt hat, war die Verbindung zwischen dieser vorhandenen Information und der Stelle, an der sie eine Entscheidung beeinflusst. Solche Verbindungen zu ziehen ist ein guter Teil der Arbeit an Supply-Chain-Sicherheit, und sie besteht seltener aus neuen Mechanismen als aus dem Sichtbarmachen dessen, was das Werkzeug längst weiß. +Durch diese Änderung im Artifact-Plugin ist es nun deutlich komfortabler geworden, Komponenten zu releasen, +ohne versehentlich lokal gebaute Abhängigkeiten mit zu verbauen. Gerade solche eher unscheinbare Unterschiede auf +Byte-Ebene können sehr aufwendig aufzuspüren sein, sind aber nicht weniger wichtig für vollständige Reproduzierbarkeit. +Somit kann eine mögliche Fehlerquelle gerade in komplexen Komponenten vermieden werden und am Ende Zeit +bei Fehlersuche und zusätzlicher, nachträglicher Arbeit gespart werden. Damit leistet diese scheinbar kleine +Information im Log einen weiteren Beitrag zur Supply Chain Security. --- From 8695b0b99f789142ce4a078e88e5b0996e3dbc91 Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Thu, 3 Sep 2026 14:24:31 +0200 Subject: [PATCH 5/9] fix slug & article language categorysation --- ...akt-herkunft.md => 2026-08-xx-maven-artefakt-herkunft.de.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename content/posts/{2026-08-xx-maven-artefakt-herkunft.md => 2026-08-xx-maven-artefakt-herkunft.de.md} (99%) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md similarity index 99% rename from content/posts/2026-08-xx-maven-artefakt-herkunft.md rename to content/posts/2026-08-xx-maven-artefakt-herkunft.de.md index 4366052d..59d7a685 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md @@ -2,7 +2,7 @@ outdated: false showInBlog: true title: "Von der Supply Chain, lokal gebauten Artefakten und wie Maven damit umgeht" -slug: genug-geredet-wie-digitale-souveränität-von-der-un-bis-dortmund-konkret-wird +slug: von-der-supply-chain-lokal-gebauten-artefakten-und-wie-maven-damit-umgeht date: 2026-08-12 author: sebastian excerpt: "Lokal gebaute Artefakte können ein Problem für Reproducible Builds sein und damit ein Risiko für die Supply Chain. Ich zeige hier, wie das Auflösen von Artefakten in Maven passiert und wie man sehen kann, ob ein selbstgebautes Artefakt fäschlicher Weise verwerndet wurde." From 8bab9ab6bbf15a18d604e409a423f52f8b3fa437 Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Wed, 16 Sep 2026 14:16:24 +0200 Subject: [PATCH 6/9] apply comments: fix title, add some links, sharpen some wording --- .../posts/2026-08-xx-maven-artefakt-herkunft.de.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md index 59d7a685..6a312574 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md @@ -11,9 +11,9 @@ preview_image: "/posts/preview-images/oss-world.svg" --- -# Woher kommt dieses Artefakt eigentlich? Vom Maven Repository und der Datei `_remote.repositories` +# Von der Supply Chain, Maven Repositories und der Datei `_remote.repositories` -Reproducible Builds beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, +[Reproducible Builds](https://reproducible-builds.org/) beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den ersten Blick nicht ansehen kann, woher sein Inhalt stammt. Technisch haben wir das Thema Reproducible Builds bereits @@ -32,9 +32,9 @@ Build-Ergebnisses inklusive Checksummen, und `artifact:compare` vergleicht das E Referenz. Wenn beide übereinstimmen, ist gezeigt, dass die veröffentlichten Artefakte tatsächlich aus dem angegebenen Quellcode entstanden sein können. -Ein Vergleich ist allerdings nur so gut wie sein Vergleichsmaßstab. Wenn eine der beteiligten Abhängigkeiten nicht aus +Problematisc ist allerdings, wenn eine der beteiligten Abhängigkeiten nicht aus einem öffentlichen Repository stammt, sondern lokal via `mvn install` vor drei Wochen auf demselben Rechner -gebaut worden sind, dann vergleicht man am Ende ein lokales Ergebnis mit einem anderen lokalen Ergebnis. Das Resultat +gebaut worden sind. Dann vergleicht man am Ende ein lokales Ergebnis mit einem anderen lokalen Ergebnis. Das Resultat sieht sauber aus, es sagt aber nichts über die veröffentlichten Artefakte aus. Aus Supply-Chain-Perspektive ist ein lokal installiertes Artefakt ein Input in den Build, der von niemandem geprüft wurde, weder durch eine Signatur noch durch eine Checksumme gegen ein Remote-Repository. Wie sich in der Vergangenheit gezeigt hat, könnte hier bereits @@ -58,7 +58,7 @@ allein lässt sich die Herkunft folglich nicht ablesen. ## Wie Maven das lokale Repository verwaltet -Unterhalb von Maven arbeitet der Maven Artifact Resolver, das frühere Aether. Es kapselt alles, was mit Repositories +Unterhalb von Maven arbeitet der Maven Artifact Resolver. Es kapselt alles, was mit Repositories zu tun hat, also das Auflösen von Koordinaten, das Herunterladen, das Zwischenspeichern und das Installieren. Für das lokale Repository ist dabei eine eigene Verwaltungsschicht zuständig, und die zur Laufzeit verwendete Variante tut mehr, als Dateien an der richtigen Stelle abzulegen. Sie führt Buch darüber, aus welchem Repository ein @@ -90,8 +90,7 @@ artifact-1.0.pom>my_repo_id= Der entscheidende Sonderfall ist die leere Repository-Id. Ein Eintrag der Form `artifact-1.0.jar>=` bedeutet, dass diese Datei nicht heruntergeladen, sondern lokal installiert wurde. Fehlt zu einer vorhandenen Datei jeglicher Eintrag, dann gilt sie intern ebenfalls als lokal installiert. - -Diese Datei ist damit essentiell für die Basis für die Lösung von MARTIFACT-58. + Über die API lässt sich herausbekommen, aus welchem Repository ein Artefakt kam, und im Fall einer lokalen Installation ist das eben das lokale Repository selbst. From ac742e2dfc9db99d0fda04c89d00c45570eb05e9 Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Wed, 16 Sep 2026 14:46:15 +0200 Subject: [PATCH 7/9] remove the double title (finally) --- content/posts/2026-08-xx-maven-artefakt-herkunft.de.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md index 6a312574..c0ea96d3 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md @@ -10,9 +10,6 @@ categories: [Open Elements, Open-Source, Security, Java] preview_image: "/posts/preview-images/oss-world.svg" --- - -# Von der Supply Chain, Maven Repositories und der Datei `_remote.repositories` - [Reproducible Builds](https://reproducible-builds.org/) beruhen auf einer einfachen Zusage: derselbe Quellcode, dieselbe Build-Umgebung, dasselbe Ergebnis, Byte für Byte. Wer diese Zusage überprüfen will, braucht eine verlässliche Referenz, und genau an dieser Stelle wird es interessant, denn die Referenz liegt bei Maven im lokalen Repository, also in einem Verzeichnis, dem man auf den From ae01e18fe04bf96d345eb3b43f8f2ad0ff0bd38c Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Wed, 16 Sep 2026 16:04:05 +0200 Subject: [PATCH 8/9] add english version, adjust posting date --- .../2026-08-xx-maven-artefakt-herkunft.de.md | 2 +- .../2026-08-xx-maven-artefakt-herkunft.md | 128 ++++++++++++++++++ 2 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 content/posts/2026-08-xx-maven-artefakt-herkunft.md diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md index c0ea96d3..1cd29911 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md @@ -3,7 +3,7 @@ outdated: false showInBlog: true title: "Von der Supply Chain, lokal gebauten Artefakten und wie Maven damit umgeht" slug: von-der-supply-chain-lokal-gebauten-artefakten-und-wie-maven-damit-umgeht -date: 2026-08-12 +date: 2026-09-16 author: sebastian excerpt: "Lokal gebaute Artefakte können ein Problem für Reproducible Builds sein und damit ein Risiko für die Supply Chain. Ich zeige hier, wie das Auflösen von Artefakten in Maven passiert und wie man sehen kann, ob ein selbstgebautes Artefakt fäschlicher Weise verwerndet wurde." categories: [Open Elements, Open-Source, Security, Java] diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.md new file mode 100644 index 00000000..e88f26b8 --- /dev/null +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.md @@ -0,0 +1,128 @@ +--- +outdated: false +showInBlog: true +title: "On the supply chain, locally built artifacts and how Maven handles them" +slug: on-the-supply-chain-locally-built-artifacts-and-how-maven-handles-them +date: 2026-09-16 +author: sebastian +excerpt: "Locally built artifacts can become a problem for reproducible builds and therefore a risk for the supply chain. In this post I show how Maven resolves artifacts and how you can tell whether a self-built artifact was used by mistake." +categories: [Open Elements, Open-Source, Security, Java] +preview_image: "/posts/preview-images/oss-world.svg" +--- + + +# On the supply chain, maven repositories and the File `_remote.repositories` + +[Reproducible Builds](https://reproducible-builds.org/) rest on a simple promise: the same source code, the same build +environment, the same result, byte for byte. Anyone who wants to verify that promise needs a reliable reference, and +this is exactly where things get interesting, because in Maven that reference sits in the local repository, that is, in +a directory whose contents do not indicate at first glance where they came from. We have already covered the +technical side of reproducible builds in another [blog post](https://open-elements.com/posts/2025/09/12/reproducible-builds) +in the context of Apache Maven and its effects on the supply chain. + +Here we want to answer the question of how Maven resolves and manages artifacts, what the inconspicuous file +`_remote.repositories` contains, and how a concrete improvement for the Apache Maven Artifact Plugin and ultimately for +the supply chain can be built on top of it. + +## Why provenance is a supply chain related topic + +The [Maven Artifact Plugin](https://maven.apache.org/plugins/maven-artifact-plugin/) is the tool used to demonstrate +reproducible builds in the Maven ecosystem. The goal `artifact:buildinfo` produces a description of the build result +including checksums, and `artifact:compare` compares the result of the current build with a reference. If both match, +this shows that the published artifacts can indeed have been produced from the stated source code. + +It becomes problematic, however, if one of the dependencies involved does not come from a public repository but was +built locally on the same machine three weeks ago via `mvn install`. In that case, you end up comparing one local result +with another local result. The outcome looks clean, but it says nothing about the published artifacts. From a supply +chain perspective, a locally installed artifact is an input to the build that nobody has verified, neither through a +signature nor through a checksum against a remote repository. As the past has shown, malicious manipulation may already +have taken place at this point, and you can read more about that +[here](https://reproducible-builds.org/docs/why/) on [reproducible-builds.org](https://reproducible-builds.org). + +Precisely this gap was described in +[MARTIFACT-58](https://github.com/apache/maven-artifact-plugin/issues/146). The observation: `artifact:compare` compares +the output of the current build with content from the local repository, and what is not easy to recognize is whether +that content originates from an earlier local `mvn install` or was downloaded from a remote repository. The suggestion +was that the plugin could determine and report this information itself. + +## The local repository as a mixed Store + +To implement this, you need to understand how the local Maven repository works. The +[Maven documentation](https://maven.apache.org/guides/introduction/introduction-to-repositories.html) describes it as a +mixed store that serves two purposes at once: it is a cache for artifacts that were loaded from a remote repository, and +it is a store for artifacts that were built and installed locally. Both end up in the same layout, that is, under the +same path made up of groupId, artifactId, and version. The origin can therefore not be derived from the path alone. + +## How Maven manages the local repository + +Underneath Maven, the Maven Artifact Resolver does the work. It encapsulates everything that has to do with +repositories, such as resolving coordinates, downloading, caching, and installing. A dedicated management layer is +responsible for the local repository, and the variant used at runtime does more than place files in the right spot. It +keeps track of which repository a cached artifact originally came from. + +This bookkeeping serves a very practical purpose. If an artifact was loaded from a repository R1 and a later build needs +the same artifact but does not know R1, then the locally available artifact counts as not present and is downloaded +again. The reasoning behind this is one of trust: two artifacts with identical coordinates from two different +repositories do not have to be the same thing. Incidentally, the same mechanism explains the occasionally confusing +error message that an artifact cannot be resolved even though it is visibly sitting in the directory. + +That leaves the question of where this bookkeeping actually lives, and the answer is a single file that is easy to +overlook. + +## The file `_remote.repositories` + +The provenance information that Maven records while downloading ends up in the tracking file `_remote.repositories`. +Maven creates it in every directory of the local repository in which artifacts are managed. + +Its content is a Java properties file. The keys consist of the file name, a `>` as a separator, and the ID of the +repository the file was obtained from. The value stays empty. A directory can therefore look something like this: + +``` +#NOTE: This is a Maven Resolver internal implementation file, its format can be changed without prior notice. +artifact-1.0.pom>central= +artifact-1.0.jar>central= +artifact-1.0.pom>my_repo_id= +``` + +The decisive special case is the empty repository ID. An entry of the form `artifact-1.0.jar>=` means that this file was +not downloaded but installed locally. If an existing file has no entry at all, it is internally treated as locally +installed as well. + +Through the API, you can find out which repository an artifact came from, and in the case of a local installation, that is +the local repository itself. + +## The implementation in the Maven Artifact Plugin + +Pull request [#227](https://github.com/apache/maven-artifact-plugin/pull/227) for the Apache Maven Artifact Plugin makes +use of exactly this option. The change sits where the plugin determines the reference for the comparison, and it +receives the current repository configuration of the build from the comparison goal. + +In addition to the artifact under examination, it is just as important to walk the dependency tree of that artifact, in +case further included components or their child dependencies were built locally. + +If that is the case, the following kind of warning appears in the log afterward, together with the urgent +recommendation to check the build and to potentially delete artifacts found locally so that the versions from the remote +repository are used instead: + +``` +The artifact org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your +local Maven repository. Please ensure that this is intended. If not, consider +removing this artifact and rebuilding and that your locally installed artifact +from /home/user/.m2/repository/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar +matches public reference from remote. +``` + +## What this means in practice + +Thanks to this change in the Artifact Plugin, releasing components without accidentally pulling in locally built +dependencies has become considerably more convenient. Differences at the byte level that look rather inconspicuous can be +very laborious to track down, yet they are no less important for full reproducibility. A possible source of errors can +therefore be avoided, especially in complex components, and in the end time is saved on debugging and on additional +work after the fact. In this way, a seemingly small piece of information in the log makes another contribution to supply +chain security. + +--- + +*The work on Apache Maven as part of Support & Care is funded by the Sovereign Tech Agency.* + +*This article was created with the help of AI.* From 1c3eced16764adf08eaef18605015249b3b1805d Mon Sep 17 00:00:00 2001 From: Sebastian Tiemann Date: Thu, 17 Sep 2026 09:57:40 +0200 Subject: [PATCH 9/9] apply log message modification --- content/posts/2026-08-xx-maven-artefakt-herkunft.de.md | 4 ++-- content/posts/2026-08-xx-maven-artefakt-herkunft.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md index 1cd29911..38523df0 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.de.md @@ -105,9 +105,9 @@ den Build nachzuprüfen und potentiell lokal gefundene Artefakte zu löschen, um Remote-Repositories zurückzugreifen: ``` -The artifact org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your +The dependency org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your local Maven repository. Please ensure that this is intended. If not, consider -removing this artifact and rebuilding and that your locally installed artifact +removing this artifact and rebuilding or that your locally installed artifact from /home/user/.m2/repository/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar matches public reference from remote. ``` diff --git a/content/posts/2026-08-xx-maven-artefakt-herkunft.md b/content/posts/2026-08-xx-maven-artefakt-herkunft.md index e88f26b8..11d08ab4 100644 --- a/content/posts/2026-08-xx-maven-artefakt-herkunft.md +++ b/content/posts/2026-08-xx-maven-artefakt-herkunft.md @@ -105,9 +105,9 @@ recommendation to check the build and to potentially delete artifacts found loca repository are used instead: ``` -The artifact org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your +The dependency org.slf4j:slf4j-api:1.7.36 is stemming from a local install to your local Maven repository. Please ensure that this is intended. If not, consider -removing this artifact and rebuilding and that your locally installed artifact +removing this artifact and rebuilding or that your locally installed artifact from /home/user/.m2/repository/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar matches public reference from remote. ```