Сопоставление исходного кода пакета

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

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

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

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

Поддержка Visual Studio

Эта функция доступна во всех интегрированных инструментах 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 .

Дополнительные сведения об управлении сопоставлениями источников пакетов NuGet см. в разделе "Параметры NuGet" в Visual Studio.

Окно диспетчера пакетов 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 файлов на различных уровнях (на уровне компьютера, уровне пользователя, уровне репозитория).

Установка с помощью пользовательского интерфейса диспетчера пакетов

По состоянию на Visual Studio 17.8 или более поздней версии при выполнении указанных ниже условий пользовательский интерфейс диспетчера пакетов попытается автоматически создавать сопоставления источников пакетов для установленных идентификаторов пакетов (верхнего уровня и зависимых пакетов), при использовании компонентов установки или обновления пакета.

Следующее сообщение будет отображаться, когда критерии для этого выполняются автоматически:

Будет создано отображение источника пакета.

В настоящее время создание сопоставлений источников автоматически выполняется только в том случае, если:

• Проект использует PackageReference.
• Сопоставление источников пакетов уже включено (вы уже добавили сопоставление или создали раздел в NuGet.Config).
• В раскрывающемся списке выбран один источник пакета (т. е. выбор "Все" для источников пакетов не поддерживается, так как это неоднозначно, какой источник следует сопоставить).

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

При выборе параметра "Показать окно предварительного просмотра" отобразится список новых сопоставлений источников пакетов.

Если предварительный просмотр не является нужным для сопоставлений источников, отмените установку и настройте соответствующие сопоставления источников вручную перед выполнением установки и обновления.

Например, установка пакета Polly приводит к тому, что он и его зависимость Polly.Core автоматически связываются с выбранным источником пакетов, nuget.org. Пакеты, зависящие от Microsoft, устанавливаются с использованием существующих сопоставлений источников пакетов.

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

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

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

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

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

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

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

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

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

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

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

Начало работы

Существует 2 способа полностью подключить репозиторий, вручную или с помощью средства NuGet.PackageSourceMapper.

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

Для подключения вручную можно выполнить следующие действия.

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

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

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

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

Инструмент имеет несколько вариантов создания шаблона сопоставления в зависимости от ваших потребностей, ознакомьтесь с блогом и Readme-инструкцией средства для получения дополнительных сведений.

Сведения о том, как могут выглядеть сопоставления источников, см. в репозитории примеров.