Сопоставление источников пакетов

Сопоставление источников пакетов — это средство, которое можно использовать для улучшения безопасности цепочки поставок, особенно при использовании сочетания общедоступных и частных источников пакетов.

По умолчанию NuGet будет искать все настроенные источники пакетов при необходимости скачивания пакета. Если пакет существует в нескольких источниках, он может быть не детерминирован, из которого будет скачан исходный пакет. С помощью сопоставления источников пакетов можно фильтровать по каждому пакету, в котором будет выполняться поиск в NuGet источника.

Мы также предлагаем другие рекомендации по укреплению цепочки поставок в отношении атак.

Сопоставление источников пакетов было добавлено в NuGet 6.0. Начиная с Visual Studio 17.5, можно добавлять и удалять сопоставления источников пакетов с помощью диалогового окна параметров Visual Studio.

Поддержка Visual Studio

Visual Studio	Сопоставление источников пакетов	Поддержка в средствах —> параметры	Поддержка в пользовательском интерфейсе диспетчер пакетов
17.0 - 17.4	✅ Доступен	❌ Недоступно	❌ Недоступно
17,5	✅ Доступен	✅ Доступен	❌ Недоступно
17.7 Предварительная версия 3	✅ Доступен	✅ Доступен	✅ Отображается состояние

Эта функция доступна во всех интегрированных средствах NuGet:

• Visual Studio 2022 и более поздних версий;
• пакет SDK для .NET 6.0.100 и более поздних версий;
• nuget.exe 6.0.0 и более поздних версий.

Более старые средства будут игнорировать конфигурацию сопоставления источников пакетов. Чтобы применить эту функцию, убедитесь, что все среды сборки используют совместимые версии инструментов.

Сопоставление источников пакетов будут применяться ко всем типам проектов, включая .NET Framework, — при условии, что используются совместимые средства.

Видеоруководство

Посмотрите видеообзор функции сопоставления источников пакетов Защита пакетов NuGet с помощью сопоставления источников пакетов на YouTube.

Включение сопоставления источников пакетов

Чтобы использовать эту функцию, требуется файл nuget.config. Рекомендуется обеспечить наличие одного файла nuget.config в корне репозитория. Дополнительные сведения см. в документации по nuget.config.

Включение с помощью диалогового окна параметров Visual Studio

1. Откройте решение в Visual Studio.
2. Перейдите в диалоговое Package Source Mappings окно "Параметры".

Из пользовательского интерфейса диспетчер пакетов

• Выберите пакет из списка, чтобы отобразить его в области сведений.
• Нажмите кнопку, Configure чтобы открыть страницу параметров сопоставления источников пакетов.

В диалоговом окне параметров Visual Studio

• Перейдите Tools в меню на главной панели инструментов Visual Studio и нажмите кнопку NuGet Package Manager ->Package Manager Settings.
• Перейдите к странице Package Source Mappings.

3. Add Нажмите кнопку на Package Source Mappings странице, чтобы открыть диалоговое Add Package Source Mappings окно.

4. Введите идентификатор пакета или шаблон пакета и выберите один или несколько источников пакетов, переключив проверка box для нужных источников.

5. На Package Source Mapping странице параметров будет отображаться только что созданное сопоставление источников.

6. Нажмите OK диалоговое окно "Параметры", чтобы сохранить изменения в применимых nuget.config.
7. Окно диспетчер пакетов NuGet обновится и отражает новое состояние сопоставлений источников выбранного пакета.

Включение путем редактирования вручную nuget.config

• Объявите требуемые источники пакетов в файле nuget.config.
• После объявления источников добавьте элемент <packageSourceMapping>, указывающий требуемые сопоставления для каждого источника.
• Объявите ровно один элемент packageSource для каждого используемого источника.
  • Добавьте столько шаблонов, сколько необходимо.

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

Параметры сопоставления источников пакетов применяются в соответствии с правилами приоритета nuget.config, если в наличии несколько файлов nuget.config на различных уровнях (уровни компьютера, пользователя, репозитория).

Правила сопоставления источников пакетов

Для максимальной гибкости и контроля NuGet требует, чтобы все пакеты соответствовали шаблону пакета с точно определенным приоритетом.

Требования шаблона пакета

Все запрошенные пакеты должны быть сопоставлены с одним или несколькими источниками путем сопоставления с определенным шаблоном пакета. Иными словами, как только вы определите элемент packageSourceMapping, вам нужно будет явно определить, из каких источников будет восстанавливаться каждый пакет, включая транзитивные пакеты.

• И пакеты верхнего уровня, и транзитивные пакеты должны соответствовать определенным шаблонам. Не требуется, чтобы пакет верхнего уровня и его зависимости поступали из одного источника.
• Один и тот же шаблон идентификатора можно определить в нескольких источниках. Это позволяет восстанавливать совпадающие идентификаторы пакетов из любого веб-канала, определяющего шаблон. Но это не рекомендуется из-за влияния на прогнозируемость восстановления (нужный пакет может поступать из нескольких источников). Такая конфигурация допустима, если вы доверяете всем соответствующим источникам.

Синтаксис шаблона пакета

Расписание	Пример синтаксиса	Description
Шаблон префикса пакета	*, NuGet.*	В конце нужно использовать *, где * соответствует 0 или большему числу знаков. * — это самый короткий допустимый шаблон префикса. Он соответствует всем идентификаторам пакетов.
Шаблон идентификатора пакета	NuGet.Common, Contoso.Contracts	Точный идентификатор пакета.

Приоритет шаблона пакета

Если несколько уникальных шаблонов соответствуют идентификатору пакета, предпочтение отдается самому строго определенному. Шаблоны идентификаторов пакетов всегда имеют самый высокий приоритет, а общее значение * — самый низкий. Что касается шаблонов префиксов пакетов, приоритетным будет самый длинный.

Настройка источников по умолчанию

С помощью шаблона * можно объявить фактический источник по умолчанию. Это означает, что любой пакет, который не соответствует другим указанным шаблонам, будет восстановлен из этого источника без возникновения ошибки. Такая конфигурация удобна, если вы в основном используете пакеты, скажем, из nuget.org, а также у вас есть только несколько внутренних пакетов или вы применяете стандартные префиксы для всех внутренних пакетов, таких как Contoso.*.

Если команда не использует стандартные префиксы для идентификаторов внутренних пакетов или проверяет пакеты nuget.org перед установкой, то установка закрытого источника по умолчанию будет лучше удовлетворять ваши потребности.

Примечание.

Если запрошенный пакет уже существует в папке глобальных пакетов, то поиск источника не будет выполняться и сопоставления будут игнорироваться. Рекомендуем объявить папку глобальных пакетов для вашего репозитория, чтобы получить максимум преимуществ в области безопасности при использовании этой функции. В следующей итерации мы планируем сделать удобнее работу с папкой глобальных пакетов по умолчанию. Дополнительные сведения о том, как выполняется установка пакетов, см. в документе, раскрывающем основные понятия.

Начать

Полностью подключить репозиторий можно двумя способами: вручную или с помощью средства NuGet.PackageSourceMapper.

Подключение вручную

Чтобы подключить репозиторий вручную, можно выполнить следующие шаги:

1. Объявите новую папку глобальных пакетов для своего репозитория.
2. Выполните команду dotnet restore, чтобы восстановить зависимости.
3. Выполните команду dotnet list package --include-transitive, чтобы просмотреть все пакеты верхнего уровня и транзитивные пакеты в своем решении.
   • Для проектов .NET Framework с использованием packages.config в файле packages.config будет содержаться неструктурированный список всех прямых и транзитивных пакетов.
4. Определите сопоставления таким образом, чтобы каждый идентификатор пакета в решении, включая транзитивные пакеты, соответствовал шаблону целевого источника.
5. Выполните команду dotnet nuget locals global-packages -c, чтобы очистить каталог global-packages.
6. Выполните восстановление, чтобы проверить, правильно ли настроены ваши сопоставления. Если сопоставления не полностью охватывают каждый идентификатор пакета в вашем решении, сообщения об ошибках помогут вам определить причину проблемы.
7. Если восстановление успешно выполнено, значит, все получилось! При необходимости рассмотрим:
   • Упрощение конфигурации. Для этого сократите число объявлений с использованием более подробных префиксов идентификаторов пакетов или во всех возможных случаях задайте источник по умолчанию.
   • Проверка источника, из которого был восстановлен исходный пакет. Для этого просмотрите файлы метаданных в папке глобальных пакетов или журналы восстановления.

Автоматическое подключение с помощью средства

Многие репозитории имеют большое количество пакетов, и выполнение вручную может занять много времени. Средство NuGet.PackageSourceMapper может автоматически создавать NuGet.config на основе известных пакетов и источников проекта.

Средство сопоставления источников с пакетами требует успешного восстановления пакетов, при котором оно будет считывать каждый соответствующий файл .nupkg.metadata, созданный в рамках сборки, чтобы лучше изучить, как сопоставляются соответствующие пакеты и источники. Средство не только охватывает основные зависимости, но и учитывает все транзитивные зависимости при создании сопоставления.

Средство имеет предусматривает несколько вариантов создания шаблона сопоставления в зависимости от потребностей. Дополнительные сведения см. в этой записи блога и в файле сведений о средстве.

Чтобы понять, что собой представляют сопоставления источников, см. наш репозиторий примеров.

Примечание.

• Команды nuget.exe или dotnet.exe для управления настройкой сопоставления источников пакетов не предусмотрены. См. сведения по адресу NuGet/Home#10735.
• Сопоставление пакетов нельзя выполнять во время установки пакета. См. сведения по адресу NuGet/Home#10730.
• Существует ограничение при использовании задачи Azure Pipelines DotNetCoreCLI@2, которое можно обойти с помощью префиксов feed- в конфигурации сопоставления источника. Однако рекомендуется использовать NuGetAuthenticate для проверки подлинности и вызывать CLI DotNet непосредственно из задачи скрипта. См. microsoft/azure-pipelines-tasks#15542.