Mapování zdroje balíčků

Mapování zdrojů balíčků je nástroj, který lze použít ke zlepšení zabezpečení dodavatelského řetězce, zejména pokud používáte kombinaci veřejných a privátních zdrojů balíčků.

Ve výchozím nastavení Bude NuGet prohledávat všechny nakonfigurované zdroje balíčků, když potřebuje stáhnout balíček. Pokud balíček existuje ve více zdrojích, nemusí být deterministický, ze kterého zdroje se balíček stáhne. Pomocí mapování zdrojů balíčků můžete filtrovat podle balíčku, který zdroj nuGet bude prohledávat.

Máme také návrhy na další osvědčené postupy , které vám pomůžou umocnit váš dodavatelský řetězec proti útokům.

V NuGetu 6.0 bylo přidáno mapování zdrojů balíčků. Počínaje sadou Visual Studio 17.5 můžete přidat a odebrat mapování zdrojů balíčků pomocí dialogového okna Možnosti sady Visual Studio.

Podpora sady Visual Studio

Visual Studio	Mapování zdroje balíčků	Podpora v nástrojích –> Možnosti	Podpora v uživatelském rozhraní Správce balíčků
17.0 - 17.4	✅ Dostupný	❌ Není k dispozici	❌ Není k dispozici
17.5	✅ Dostupný	✅ Dostupný	❌ Není k dispozici
17.7 Preview 3	✅ Dostupný	✅ Dostupný	✅ Zobrazený stav

Tato funkce je dostupná napříč všemi integrovanými nástroji NuGet.

• Visual Studio 2022 a novější
• .NET SDK 6.0.100 a novější
• nuget.exe 6.0.0 a novější

Starší nástroje budou ignorovat konfiguraci mapování zdrojů balíčků. Pokud chcete tuto funkci použít, ujistěte se, že všechna vaše prostředí sestavení používají kompatibilní verze nástrojů.

Mapování zdrojů balíčků budou platit pro všechny typy projektů , včetně rozhraní .NET Framework, pokud se použijí kompatibilní nástroje.

Video s návodem

Pokud potřebujete video přehled funkce Mapování zdrojů balíčků, zvažte sledování balíčků Zabezpečení balíčků pomocí videa Mapování zdrojů balíčků na YouTube.

Povolení mapování zdroje balíčku

Pokud se chcete přihlásit k této funkci, musíte mít nuget.config soubor. Osvědčeným postupem je mít jeden nuget.config v kořenovém adresáři úložiště. Další informace najdete v dokumentaci nuget.config.

Povolit pomocí dialogového okna Možnosti sady Visual Studio

1. Otevřete své řešení v prostředí Visual Studio.
2. Přejděte do dialogového Package Source Mappings okna Možnosti.

V uživatelském rozhraní Správce balíčků

• V seznamu vyberte balíček, který chcete zobrazit v podokně podrobností.
• Stisknutím tlačítka Configure otevřete stránku možností mapování zdrojů balíčků.

V dialogovém okně Možnosti sady Visual Studio

• Přejděte do Tools nabídky na hlavním panelu nástrojů sady Visual Studio a zvolte NuGet Package Manager ->Package Manager Settings.
• Přejděte na stránku Package Source Mappings.

3. Stisknutím tlačítka Add na Package Source Mappings stránce otevřete Add Package Source Mappings dialogové okno.

4. Zadejte ID balíčku nebo vzor balíčku a vyberte jeden nebo více zdrojů balíčků přepnutím zaškrtávacího políčka pro požadované zdroje.

5. Na Package Source Mapping stránce možností se zobrazí nově vytvořené mapování zdroje.

6. Stisknutím OK dialogového okna Možnosti uložte změny v příslušném nuget.configsouboru .
7. Okno Správce balíčků NuGet se aktualizuje a bude odrážet nový stav mapování zdrojů vybraného balíčku.

Povolení ruční úpravou nuget.config

• Deklarujte požadované zdroje balíčků v nuget.config souboru.
• Za deklaracemi zdroje přidejte <packageSourceMapping> prvek, který určuje požadovaná mapování pro každý zdroj.
• Deklarujte přesně jeden packageSource prvek pro každý zdroj, který se používá.
  • Přidejte tolik vzorů, kolik potřebujete.

<?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>

Nastavení mapování zdrojů balíčků se použijí podle pravidel priority nuget.config, pokud je k dispozici více nuget.config souborů na různých úrovních (úroveň počítače, uživatelská úroveň, úložiště).

Pravidla mapování zdrojů balíčků

Pro maximální flexibilitu a kontrolu NuGet vyžaduje, aby všechny balíčky odpovídaly vzoru balíčku prostřednictvím dobře definované priority.

Požadavky na model balíčků

Všechny požadované balíčky se musí mapovat na jeden nebo více zdrojů tím, že odpovídají definovanému vzoru balíčku. Jinými slovy, jakmile definujete packageSourceMapping prvek, musíte explicitně definovat, ze kterých zdrojů se obnoví každý balíček , včetně tranzitivních balíčků.

• Jak balíčky nejvyšší úrovně , tak tranzitivní balíčky musí odpovídat definovaným vzorům. Není nutné, aby balíček nejvyšší úrovně a jeho závislosti pocházejí ze stejného zdroje.
• Stejný vzor ID je možné definovat u více zdrojů, což umožňuje obnovení odpovídajících ID balíčků z libovolného informačního kanálu, který tento vzor definuje. Nedoporučuje se to ale kvůli dopadu na předvídatelnost obnovení (daný balíček může pocházet z více zdrojů). To může být platná konfigurace, pokud důvěřujete všem příslušným zdrojům.

Syntaxe vzoru balíčku

Vzor	Příklad syntaxe	Popis
Vzor předpony balíčku	*, NuGet.*	Musí končit znakem *, kde * odpovídá 0 nebo více znakům. * je nejkratší povolený vzor předpony a odpovídá všem ID balíčků.
Model ID balíčku	NuGet.Common, Contoso.Contracts	Přesné ID balíčku.

Priorita vzoru balíčku

Pokud několik jedinečných vzorů odpovídá ID balíčku, preferuje se nejvýraznější vzor. Vzory ID balíčku mají vždy nejvyšší prioritu, zatímco obecný * vždy má nejnižší prioritu. U vzorů předpon balíčku má nejdelší prioritu.

Nastavení výchozích zdrojů

Vzor * lze použít k deklaraci výchozího zdroje de facto – to znamená, že jakýkoli balíček, který neodpovídá jiným zadaným vzorům, se z daného zdroje obnoví bez vyvolání chyby. Tato konfigurace je výhodná, pokud primárně používáte balíčky z řekněme , nuget.orga máte pouze několik interních balíčků, nebo použijte standardní předpony pro všechny interní balíčky jako Contoso.*.

Pokud váš tým před instalací nepoužívá standardní předpony pro interní ID balíčků nebo sady virtuálních sad nuget.org před instalací, bude nastavení privátního zdroje lépe vyhovovat vašim potřebám.

Poznámka:

Pokud požadovaný balíček již ve složce globálních balíčků existuje, nedojde k žádnému vyhledání zdroje a mapování se bude ignorovat. Zvažte deklarování globální složky balíčků pro vaše úložiště , abyste získali úplné výhody zabezpečení této funkce. Pro další iteraci je naplánována práce na vylepšení prostředí s výchozí složkou globálních balíčků. Další informace o tom, jak instalace balíčku funguje, najdete v koncepčním dokumentu.

Začínáme

Existují 2 způsoby, jak plně připojit úložiště, ručně nebo pomocí nástroje NuGet.PackageSourceMapper.

Ruční onboarding

Při ručním onboardingu můžete provést následující kroky:

1. Deklarujte novou globální složku balíčků pro vaše úložiště.
2. Spuštěním příkazu dotnet restore obnovte závislosti.
3. Spuštěním zobrazíte dotnet list package --include-transitive všechny balíčky na nejvyšší úrovni a tranzitivní balíčky ve vašem řešení.
   • U projektů rozhraní .NET Framework používajících packages.configpackages.config soubor bude obsahovat plochý seznam všech přímých a tranzitivních balíčků.
4. Definujte mapování tak, aby každé ID balíčku ve vašem řešení ( včetně tranzitivních balíčků) odpovídalo vzoru pro cílový zdroj.
5. Spuštěním příkazu dotnet nuget locals global-packages -c vymažte adresář global-packages.
6. Spusťte obnovení a ověřte, že jste mapování nakonfigurovali správně. Pokud mapování plně nezakrývá každé ID balíčku ve vašem řešení, chybové zprávy vám pomůžou problém identifikovat.
7. Po úspěšném obnovení budete hotovi. Volitelně zvažte:
   • Zjednodušení konfigurace na méně deklarací pomocí širších předpon ID balíčku nebo nastavení výchozího zdroje , pokud je to možné.
   • Kontrola souborů metadat ve složce globálních balíčků nebo kontrola protokolů obnovení ověřte, že se zdrojový balíček obnovil.

Automatizované zprovoznění pomocí nástroje

Mnoho úložišť má velký počet balíčků a práce ručně může být časově náročná. Nástroj NuGet.PackageSourceMapper může automaticky vygenerovat NuGet.config za vás na základě známých balíčků a zdrojů projektu.

Nástroj mapper zdroje balíčku vyžaduje, abyste dokončili úspěšné obnovení balíčku, ve kterém bude číst každý příslušný .nupkg.metadata soubor vygenerovaný v rámci sestavení, abyste lépe pochopili, jak mapujete příslušné balíčky a zdroje. Nástroj nejen pokrývá hlavní závislosti, ale také bere v úvahu všechny přechodné závislosti při generování mapování.

Nástroj má několik možností, jak v závislosti na vaší potřebě generovat vzor mapování, podívejte se prosím na blogový příspěvek a pokyny ke čtení nástroje, kde najdete další podrobnosti.

Představu o tom, jak může vypadat mapování zdrojů, najdete v našem úložišti ukázek.

Poznámka:

• Neexistují žádné nuget.exe ani dotnet.exe příkazy pro správu konfigurace mapování zdrojů balíčků, viz NuGet/Home#10735.
• V době instalace balíčku neexistují žádné prostředky mapování balíčků, viz NuGet/Home#10730.
• Při použití DotNetCoreCLI@2 úlohy Azure Pipelines, která se dá obejít pomocí feed- předpon v konfiguraci mapování zdroje, platí omezení. Doporučuje se ale použít NuGetAuthenticate pro potřeby ověřování a volat rozhraní příkazového řádku dotnet přímo z úlohy skriptu. Viz microsoft/azure-pipelines-tasks#15542.