Mappage de source de package
La protection de votre chaîne d’approvisionnement logicielle est essentielle si vous utilisez une combinaison de sources de packages publics et privés. Utilisez le mappage de source de package avec d’autres bonnes pratiques pour vous aider à fortifier votre chaîne d’approvisionnement contre les attaques.
À compter de NuGet 6.0, vous pouvez déclarer de manière centralisée la source à partir de laquelle chaque package de votre solution doit être restauré dans votre fichier nuget.config.
La fonctionnalité est disponible dans tous les outils intégrés NuGet.
- Visual Studio 2022 et versions ultérieures
- Sdk .NET 6.0.100 et versions ultérieures
- nuget.exe 6.0.0 et versions ultérieures
Les outils plus anciens ignorent la configuration du mappage de source de package. Pour utiliser cette fonctionnalité, vérifiez que tous vos environnements de build utilisent des versions d’outils compatibles.
Les mappages de sources de package s’appliquent à tous les types de projet, y compris .NET Framework, tant que les outils compatibles sont utilisés.
Vidéo de procédure pas à pas
Pour obtenir une vue d’ensemble vidéo de la fonctionnalité De mappage de source de package, envisagez de regarder la vidéo Sécuriser vos packages NuGet avec la vidéo de mappage de source de package sur YouTube.
Activation du mappage de source de package
Pour choisir cette fonctionnalité, vous devez disposer d’un nuget.config
fichier. Le fait d’avoir un seul nuget.config
à la racine de votre dépôt est considéré comme une bonne pratique. Pour en savoir plus , consulteznuget.config documentation .
- Déclarez vos sources de package souhaitées dans votre
nuget.config
fichier. - Après vos déclarations sources, ajoutez un
<packageSourceMapping>
élément qui spécifie les mappages souhaités pour chaque source. - Déclarez exactement un
packageSource
élément pour chaque source en cours d’utilisation.- Ajoutez autant de modèles que nécessaire.
<!-- 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>
Les paramètres de mappage de source de package sont appliqués après nuget.config règles de précédence lorsque plusieurs nuget.config
fichiers à différents niveaux (au niveau de l’ordinateur, au niveau de l’utilisateur, au niveau du dépôt) sont présents.
Règles de mappage de source de package
Pour une flexibilité et un contrôle maximum, NuGet exige que tous les packages correspondent à un modèle de package par le biais d’une priorité bien définie.
Configuration requise pour le modèle de package
Tous les packages demandés doivent être mappés à une ou plusieurs sources en correspondant à un modèle de package défini. En d’autres termes, une fois que vous avez défini un packageSourceMapping
élément, vous devez définir explicitement les sources à partir de laquelle chaque package , y compris les packages transitifs , sera restauré.
- Les packages de niveau supérieur et transitif doivent correspondre aux modèles définis. Il n’est pas nécessaire qu’un package de niveau supérieur et ses dépendances proviennent de la même source.
- Le même modèle d’ID peut être défini sur plusieurs sources, ce qui permet de restaurer les ID de package correspondants à partir de l’un des flux qui définissent le modèle. Toutefois, cela n’est pas recommandé en raison de l’impact sur la prévisibilité de la restauration (un package donné peut provenir de plusieurs sources). Il peut s’agir d’une configuration valide si vous approuvez toutes les sources respectives.
Syntaxe du modèle de package
Modèle | Exemple de syntaxe | Description |
---|---|---|
Modèle de préfixe de package | * , NuGet.* , NuGet.* |
Doit se terminer par un * caractère , où * correspond à 0 ou plusieurs caractères. * est le modèle de préfixe autorisé le plus court et correspond à tous les ID de packages. |
Modèle d’ID de package | NuGet.Common , Contoso.Contracts |
ID de package exact. |
Priorité du modèle de package
Lorsque plusieurs modèles uniques correspondent à un ID de package, celui le plus spécifique est préféré. Les modèles d’ID de package ont toujours la priorité la plus élevée, tandis que le générique *
a toujours la priorité la plus basse. Pour les modèles de préfixe de package, le plus long est prioritaire.
Définition des sources par défaut
Le *
modèle peut être utilisé pour déclarer une source par défaut de facto, ce qui signifie que tout package qui ne correspond pas à d’autres modèles spécifiés sera restauré à partir de cette source sans générer d’erreur.
Cette configuration est avantageuse si vous utilisez principalement des packages tels que , nuget.org
et n’avez que quelques packages internes, ou utilisez des préfixes standard pour tous les packages internes comme Contoso.*
.
Si votre équipe n’utilise pas de préfixes standard pour les ID de package internes ou les packages vétérinaires nuget.org
avant l’installation, la création d’une source privée adaptée à vos besoins est meilleure.
Notes
Lorsque le package demandé existe déjà dans le dossier des packages globaux, aucune recherche source ne se produit et les mappages sont ignorés. Envisagez de déclarer un dossier de packages globaux pour votre dépôt afin d’obtenir les avantages de sécurité complets de cette fonctionnalité. Travailler pour améliorer l’expérience avec le dossier de packages globaux par défaut dans la planification d’une prochaine itération. Pour en savoir plus sur le fonctionnement de l’installation du package, consultez le document conceptuel.
Prendre en main
Il existe 2 façons d’intégrer entièrement votre référentiel, manuellement ou à l’aide de l’outil NuGet.PackageSourceMapper.
Intégration manuelle
Pour l’intégration manuelle, vous pouvez effectuer les étapes suivantes :
- Déclarez un nouveau dossier de packages globaux pour votre dépôt.
- Exécutez la restauration dotnet pour restaurer les dépendances.
- Exécutez
dotnet list package --include-transitive
pour afficher tous les packages de niveau supérieur et transitif dans votre solution.- Pour les projets .NET Framework utilisant
packages.config
, lepackages.config
fichier aura une liste plate de tous les packages directs et transitifs.
- Pour les projets .NET Framework utilisant
- Définissez des mappages de sorte que chaque ID de package de votre solution , y compris les packages transitifs , correspond à un modèle pour la source cible.
- Exécutez dotnet nuget locals global-packages -c pour effacer le répertoire global-packages.
- Exécutez la restauration pour vérifier que vous avez correctement configuré vos mappages. Si vos mappages ne couvrent pas entièrement chaque ID de package dans votre solution, les messages d’erreur vous aideront à identifier le problème.
- Une fois la restauration réussie, vous avez terminé ! Envisagez éventuellement les éléments suivants :
- Simplification de la configuration à moins de déclarations à l’aide de préfixes d’ID de package plus larges ou définition d’une source par défaut si possible.
- La vérification de la source à partir de laquelle chaque package a été restauré en vérifiant les fichiers de métadonnées dans le dossier packages globaux ou en examinant les journaux de restauration.
Intégration automatisée à l’aide de l’outil
De nombreux référentiels ont un grand nombre de packages et effectuent le travail manuellement peuvent prendre du temps. L’outil NuGet.PackageSourceMapper peut générer automatiquement une NuGet.config pour vous, en fonction des packages et sources connus de votre projet.
L’outil mappeur source de package vous oblige à avoir effectué une restauration de package réussie dans laquelle il lit chaque fichier respectif .nupkg.metadata
généré dans le cadre de votre build pour mieux comprendre comment vous mappez vos packages et sources respectifs. L’outil couvre non seulement les principales dépendances qu’il considère également toutes les dépendances transitives lors de la génération du mappage.
L’outil a plusieurs options pour générer un modèle de mappage en fonction de vos besoins, consultez le billet de blog et l’instruction lisez-moi de l’outil pour plus d’informations.
Pour une idée de l’apparence de vos mappages sources, reportez-vous à notre dépôt d’exemples.
Notes
- Il n’existe aucune commande nuget.exe ou dotnet.exe pour la gestion de la configuration du mappage de source de package, consultez NuGet/Home#10735.
- Il n’existe aucun moyen de mapper les packages au moment de l’installation du package, voir NuGet/Home#10730.
- Il existe une limitation lors de l’utilisation de la
DotNetCoreCLI@2
tâche Azure Pipelines qui peut être utilisée à l’aidefeed-
de préfixes dans votre configuration de mappage source. Il est toutefois recommandé d’utiliserNuGetAuthenticate
pour vos besoins d’authentification et d’appeler l’interface cli dotnet directement à partir d’une tâche de script. Consultez microsoft/azure-pipelines-tasks#15542.