Mapowanie źródła pakietu

Mapowanie źródła pakietów to narzędzie, które może służyć do poprawy bezpieczeństwa łańcucha dostaw, zwłaszcza jeśli używasz kombinacji źródeł pakietów publicznych i prywatnych.

Domyślnie narzędzie NuGet wyszukuje wszystkie skonfigurowane źródła pakietów, gdy musi pobrać pakiet. Jeśli pakiet istnieje w wielu źródłach, może nie być deterministyczny, z którego źródła zostanie pobrany pakiet. Za pomocą mapowania źródła pakietów można filtrować według pakietu, które źródła NuGet będą wyszukiwane.

Mamy również sugestie dotyczące innych najlepszych rozwiązań , które pomogą Ci wzmocnić łańcuch dostaw przed atakami.

Mapowanie źródła pakietów zostało dodane w programie NuGet 6.0. Począwszy od programu Visual Studio 17.5, można dodawać i usuwać mapowania źródła pakietów za pomocą okna dialogowego Opcje programu Visual Studio.

Obsługa programu Visual Studio

Visual Studio	Mapowanie źródła pakietu	Obsługa w narzędziach —> opcje	Obsługa interfejsu użytkownika Menedżer pakietów
17.0 - 17.4	✅ Dostępny	❌ Niedostępne	❌ Niedostępne
17.5	✅ Dostępny	✅ Dostępny	❌ Niedostępne
17.7 (wersja zapoznawcza 3)	✅ Dostępny	✅ Dostępny	✅ Wyświetlany stan

Ta funkcja jest dostępna we wszystkich zintegrowanych narzędziach NuGet.

• Program Visual Studio 2022 lub nowszy
• Zestaw .NET SDK 6.0.100 lub nowszy
• nuget.exe w wersji 6.0.0 lub nowszej

Starsze narzędzia ignorują konfigurację mapowania źródła pakietów. Aby użyć tej funkcji, upewnij się, że wszystkie środowiska kompilacji używają zgodnych wersji narzędzi.

Mapowania źródła pakietów będą stosowane do wszystkich typów projektów — w tym programu .NET Framework — o ile jest używane zgodne narzędzia.

Przewodnik wideo

Aby uzyskać wideo omówienie funkcji mapowania źródła pakietów, rozważ obejrzenie wideo Zabezpieczanie pakietów NuGet za pomocą wideo mapowania źródła pakietów w serwisie YouTube.

Włączanie mapowania źródła pakietów

Aby wybrać tę funkcję, musisz mieć nuget.config plik. Posiadanie pojedynczego nuget.config elementu w katalogu głównym repozytorium jest uważane za najlepsze rozwiązanie. Aby dowiedzieć się więcej, zobacz dokumentację narzędzia nuget.config.

Włączanie przy użyciu okna dialogowego Opcje programu Visual Studio

1. Otwórz rozwiązanie w programie Visual Studio.
2. Przejdź do okna dialogowego Package Source Mappings Opcje.

Z interfejsu użytkownika Menedżer pakietów

• Wybierz pakiet z listy, aby wyświetlić go w okienku Szczegółów.
• Naciśnij przycisk , Configure aby otworzyć stronę Opcje mapowania źródła pakietów.

W oknie dialogowym Opcje programu Visual Studio

• Przejdź do menu na Tools głównym pasku narzędzi programu Visual Studio i wybierz pozycję NuGet Package Manager ->Package Manager Settings.
• Przejdź do strony Package Source Mappings.

3. Add Naciśnij przycisk na Package Source Mappings stronie, aby otworzyć Add Package Source Mappings okno dialogowe.

4. Wprowadź identyfikator pakietu lub wzorzec pakietu i wybierz co najmniej jedno źródło pakietów, przełączając pole wyboru dla żądanych źródeł.

5. Na Package Source Mapping stronie opcji zostanie wyświetlone nowo utworzone mapowanie źródła.

6. Naciśnij OK okno dialogowe Opcje, aby zapisać zmiany w odpowiednich elementach nuget.config.
7. Okno Menedżer pakietów NuGet zostanie odświeżone i będzie odzwierciedlać nowy stan mapowań źródłowych wybranego pakietu.

Włącz, ręcznie edytując nuget.config

• Zadeklaruj żądane źródła pakietów w pliku nuget.config .
• Po deklaracjach źródłowych dodaj <packageSourceMapping> element określający żądane mapowania dla każdego źródła.
• Zadeklaruj dokładnie jeden packageSource element dla każdego używanego źródła.
  • Dodaj dowolną liczbę wzorców, ile znajdziesz w razie potrzeby.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Ustawienia mapowania źródła pakietów są stosowane zgodnie z regułami pierwszeństwa nuget.config, gdy istnieje wiele nuget.config plików na różnych poziomach (na poziomie komputera, na poziomie użytkownika, repozytorium).

Reguły mapowania źródła pakietów

Aby zapewnić maksymalną elastyczność i kontrolę, pakiet NuGet wymaga, aby wszystkie pakiety odpowiadały wzorzecowi pakietu za pomocą dobrze zdefiniowanego pierwszeństwa.

Wymagania dotyczące wzorca pakietu

Wszystkie żądane pakiety muszą być mapowane na co najmniej jedno źródło, pasując do zdefiniowanego wzorca pakietu. Innymi słowy, po zdefiniowaniu packageSourceMapping elementu należy jawnie zdefiniować źródła dla każdego pakietu — w tym pakietów przechodnich — zostaną przywrócone.

• Zarówno pakiety najwyższego poziomu, jak i przechodnie muszą być zgodne ze zdefiniowanymi wzorcami. Nie ma potrzeby, aby pakiet najwyższego poziomu i jego zależności pochodziły z tego samego źródła.
• Ten sam wzorzec identyfikatora można zdefiniować w wielu źródłach, co umożliwia przywrócenie pasujących identyfikatorów pakietów z dowolnego źródła, które definiują wzorzec. Nie jest to jednak zalecane ze względu na wpływ na przewidywalność przywracania (dany pakiet może pochodzić z wielu źródeł). Może to być prawidłowa konfiguracja, jeśli ufasz wszystkim odpowiednim źródłom.

Składnia wzorca pakietu

Wzorzec	Przykładowa składnia	opis
Wzorzec prefiksu pakietu	*, NuGet.*	Musi kończyć się znakiem *, gdzie * pasuje do co najmniej 0 znaków. * jest najkrótszym dozwolonym wzorcem prefiksu i pasuje do wszystkich identyfikatorów pakietów.
Wzorzec identyfikatora pakietu	NuGet.Common, Contoso.Contracts	Dokładny identyfikator pakietu.

Pierwszeństwo wzorca pakietu

Jeśli wiele unikatowych wzorców pasuje do identyfikatora pakietu, preferowane będzie najbardziej konkretne wzorce. Wzorce identyfikatorów pakietów zawsze mają najwyższy priorytet, podczas gdy ogólny * zawsze ma najniższy priorytet. W przypadku wzorców prefiksów pakietów najdłuższy ma pierwszeństwo.

Ustawianie domyślnych źródeł

Wzorzec * może służyć do deklarowania de facto domyślnego źródła — co oznacza, że każdy pakiet, który nie pasuje do innych określonych wzorców, zostanie przywrócony z tego źródła bez zgłaszania błędu. Ta konfiguracja jest korzystna, jeśli używasz głównie pakietów z nuget.orgpolecenia , i ma tylko kilka pakietów wewnętrznych lub użyj standardowych prefiksów dla wszystkich pakietów wewnętrznych, takich jak Contoso.*.

Jeśli twój zespół nie używa standardowych prefiksów dla wewnętrznych identyfikatorów pakietów lub pakietów weterynarzy przed instalacją, wówczas nuget.org ustawienie domyślne będzie lepiej odpowiadać Twoim potrzebom.

Uwaga

Gdy żądany pakiet już istnieje w folderze pakietów globalnych, nie nastąpi wyszukiwanie źródłowe i mapowania zostaną zignorowane. Rozważ zadeklarowanie folderu pakietów globalnych dla repozytorium , aby uzyskać pełne korzyści z zabezpieczeń tej funkcji. Aby ulepszyć środowisko pracy z domyślnym folderem pakietów globalnych, planowane jest przeprowadzenie następnej iteracji. Aby dowiedzieć się więcej na temat sposobu działania instalacji pakietu, zobacz dokument koncepcyjny.

Rozpocznij

Istnieją 2 sposoby pełnego dołączenia repozytorium, ręcznie lub przy użyciu narzędzia NuGet.PackageSourceMapper.

Ręczne dołączanie

W przypadku ręcznego dołączania możesz wykonać następujące czynności:

1. Zadeklaruj nowy folder pakietów globalnych dla repozytorium.
2. Uruchom polecenie dotnet restore , aby przywrócić zależności.
3. Uruchom polecenie dotnet list package --include-transitive , aby wyświetlić wszystkie pakiety najwyższego poziomu i przechodnie w rozwiązaniu.
   • W przypadku projektów .NET Framework korzystających z programu packages.configpackages.config plik będzie miał płaską listę wszystkich pakietów bezpośrednich i przechodnich.
4. Zdefiniuj mapowania, tak aby każdy identyfikator pakietu w rozwiązaniu — w tym pakiety przechodnie — był zgodny ze wzorcem dla źródła docelowego.
5. Uruchom polecenie dotnet nuget locals global-packages -c , aby wyczyścić katalog global-packages.
6. Uruchom polecenie przywróć, aby sprawdzić, czy mapowania zostały prawidłowo skonfigurowane. Jeśli mapowania nie obejmują w pełni każdego identyfikatora pakietu w rozwiązaniu, komunikaty o błędach ułatwią zidentyfikowanie problemu.
7. Po pomyślnym przywróceniu wszystko będzie gotowe. Opcjonalnie rozważ następujące kwestie:
   • Uproszczenie konfiguracji do mniejszej liczby deklaracji przy użyciu szerszych prefiksów identyfikatorów pakietu lub ustawienie domyślnego źródła tam, gdzie to możliwe.
   • Weryfikowanie źródła z każdego pakietu zostało przywrócone, sprawdzając pliki metadanych w folderze pakietów globalnych lub przeglądając dzienniki przywracania.

Automatyczne dołączanie przy użyciu narzędzia

Wiele repozytoriów ma dużą liczbę pakietów i ręczne wykonywanie pracy może być czasochłonne. Narzędzie NuGet.PackageSourceMapper może automatycznie wygenerować plik NuGet.config na podstawie znanych pakietów i źródeł projektu.

Narzędzie mapowania źródłowego pakietu wymaga pomyślnego przywrócenia pakietu, w którym będzie odczytywać każdy odpowiedni .nupkg.metadata plik wygenerowany w ramach kompilacji, aby najlepiej zrozumieć sposób mapowania odpowiednich pakietów i źródeł. Narzędzie nie tylko obejmuje najważniejsze zależności, które uwzględnia również wszystkie zależności przechodnie podczas generowania mapowania.

Narzędzie ma kilka opcji generowania wzorca mapowania w zależności od potrzeb, zapoznaj się z wpisem w blogu i instrukcjami readme narzędzia, aby uzyskać więcej szczegółów.

Aby dowiedzieć się, jak mogą wyglądać mapowania źródła, zapoznaj się z naszym repozytorium przykładów.

Uwaga

• Nie ma nuget.exe ani dotnet.exe poleceń do zarządzania konfiguracją mapowania źródła pakietu, zobacz NuGet/Home#10735.
• Nie ma możliwości mapowania pakietów w czasie instalacji pakietu, zobacz NuGet/Home#10730.
• Istnieje ograniczenie podczas korzystania z DotNetCoreCLI@2 zadania usługi Azure Pipelines, które można obejść za pomocą feed- prefiksów w konfiguracji mapowania źródła. Zaleca się jednak używanie go NuGetAuthenticate do potrzeb uwierzytelniania i wywoływanie interfejsu wiersza polecenia dotnet bezpośrednio z zadania skryptu. Zobacz microsoft/azure-pipelines-tasks#15542.