Mapping origine pacchetto

Mapping origine pacchetti è uno strumento che può essere usato per migliorare la sicurezza della supply chain, soprattutto se si usa una combinazione di origini di pacchetti pubblici e privati.

Per impostazione predefinita, NuGet cercherà tutte le origini dei pacchetti configurate quando deve scaricare un pacchetto. Quando un pacchetto esiste in più origini, potrebbe non essere deterministico da quale origine verrà scaricato il pacchetto. Con Il mapping dell'origine del pacchetto è possibile filtrare, per ogni pacchetto, in base alle origini in cui verrà eseguita la ricerca di NuGet.

Sono inoltre disponibili suggerimenti per altre procedure consigliate che consentono di rafforzare la supply chain contro gli attacchi.

Il mapping dell'origine del pacchetto è stato aggiunto in NuGet 6.0. A partire da Visual Studio 17.5, è possibile aggiungere e rimuovere mapping origine pacchetto con la finestra di dialogo Opzioni di Visual Studio.

Supporto di Visual Studio

Visual Studio	Mapping origine pacchetto	Supporto in Strumenti -> Opzioni	Supporto nell'interfaccia utente di Gestione pacchetti
17.0 - 17.4	✅ Disponibile	❌ Non disponibile	❌ Non disponibile
17.5	✅ Disponibile	✅ Disponibile	❌ Non disponibile
17.7 anteprima 3	✅ Disponibile	✅ Disponibile	✅ Stato visualizzato

La funzionalità è disponibile in tutti gli strumenti integrati NuGet.

• Visual Studio 2022 e versioni successive
• .NET SDK 6.0.100 e versioni successive
• nuget.exe 6.0.0 e versioni successive

Gli strumenti meno recenti ignoreranno la configurazione del mapping dell'origine del pacchetto. Per usare questa funzionalità, assicurarsi che tutti gli ambienti di compilazione usino versioni compatibili degli strumenti.

I mapping dell'origine del pacchetto verranno applicati a tutti i tipi di progetto, incluso .NET Framework, purché vengano usati strumenti compatibili.

Procedura dettagliata video

Per una panoramica basata su video della funzionalità Mapping origine pacchetti, è consigliabile guardare il video Proteggere i pacchetti NuGet con mapping origine pacchetti su YouTube.

Abilitazione del mapping dell'origine dei pacchetti

Per acconsentire esplicitamente a questa funzionalità, è necessario disporre di un nuget.config file. La presenza di un singolo nuget.config nella radice del repository è considerata una procedura consigliata. Per altre informazioni, vedere la documentazione di nuget.config.

Abilitare tramite la finestra di dialogo Opzioni di Visual Studio

1. Aprire la soluzione in Visual Studio.
2. Passare alla Package Source Mappings finestra di dialogo Opzioni.

Dall'interfaccia utente di Gestione pacchetti

• Selezionare un pacchetto dall'elenco per visualizzarlo nel riquadro dei dettagli.
• Premere il Configure pulsante per aprire la pagina opzioni Mapping origine pacchetto.

Dalla finestra di dialogo Opzioni di Visual Studio

• Passare al Tools menu nella barra degli strumenti principale di Visual Studio e scegliere NuGet Package Manager ->Package Manager Settings.
• Passare alla pagina Package Source Mappings.

3. Premere il Add pulsante nella Package Source Mappings pagina per aprire la Add Package Source Mappings finestra di dialogo.

4. Immettere un ID pacchetto o un modello di pacchetto e selezionare una o più origini pacchetto attivando o disattivando la casella di controllo per le origini desiderate.

5. Nella Package Source Mapping pagina delle opzioni verrà visualizzato il mapping di origine appena creato.

6. Premere OK la finestra di dialogo Opzioni per salvare le modifiche apportate all'oggetto applicabile nuget.config.
7. La finestra di Gestione pacchetti NuGet verrà aggiornata e rifletterà il nuovo stato dei mapping di origine del pacchetto selezionato.

Abilitare modificando manualmente nuget.config

• Dichiarare le origini del pacchetto desiderate nel nuget.config file.
• Dopo le dichiarazioni di origine, aggiungere un <packageSourceMapping> elemento che specifica i mapping desiderati per ogni origine.
• Dichiarare esattamente un packageSource elemento per ogni origine in uso.
  • Aggiungere tutti i modelli necessari.

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

Le impostazioni mapping origine pacchetto vengono applicate seguendo le regole di precedenza nuget.config quando sono presenti più nuget.config file a vari livelli (a livello di computer, a livello di utente, a livello di repository).

Regole di mapping dell'origine del pacchetto

Per garantire la massima flessibilità e controllo, NuGet richiede che tutti i pacchetti corrispondano a un modello di pacchetto tramite una precedenza ben definita.

Requisiti del modello di pacchetto

Tutti i pacchetti richiesti devono essere mappati a una o più origini associando un modello di pacchetto definito. In altre parole, dopo aver definito un packageSourceMapping elemento, è necessario definire in modo esplicito le origini da cui ogni pacchetto, inclusi i pacchetti transitivi, verrà ripristinato.

• Sia i pacchetti di primo livello che i pacchetti transitivi devono corrispondere a modelli definiti. Non è necessario che un pacchetto di primo livello e le relative dipendenze provengano dalla stessa origine.
• Lo stesso modello ID può essere definito in più origini, consentendo il ripristino degli ID pacchetto corrispondenti da uno dei feed che definiscono il modello. Tuttavia, questo non è consigliato a causa dell'impatto sulla prevedibilità del ripristino (un determinato pacchetto potrebbe provenire da più origini). Potrebbe trattarsi di una configurazione valida se si considerano attendibili tutte le rispettive origini.

Sintassi del modello di pacchetto

Modello	Sintassi di esempio	Descrizione
Modello di prefisso del pacchetto	*, NuGet.*	Deve terminare con un oggetto *, dove * corrisponde a 0 o più caratteri. * è il modello di prefisso più breve consentito e corrisponde a tutti gli ID pacchetti.
Modello ID pacchetto	NuGet.Common, Contoso.Contracts	ID pacchetto esatto.

Precedenza del modello di pacchetto

Quando più modelli univoci corrispondono a un ID pacchetto, sarà preferibile quello più specifico. I modelli ID pacchetto hanno sempre la precedenza più alta, mentre il generico * ha sempre la precedenza più bassa. Per i modelli di prefisso del pacchetto, la precedenza è maggiore.

Impostazione delle origini predefinite

Il * modello può essere usato per dichiarare un'origine predefinita de facto, ovvero qualsiasi pacchetto che non corrisponde ad altri criteri specificati verrà ripristinato da tale origine senza generare un errore. Questa configurazione è vantaggiosa se si usano principalmente pacchetti, nuget.orgad esempio , e hanno solo alcuni pacchetti interni o si usano prefissi standard per tutti i pacchetti interni come Contoso.*.

Se il team non usa prefissi standard per id pacchetto interni o pacchetti di certificati nuget.org prima dell'installazione, l'impostazione predefinita di un'origine privata sarà più adatta alle proprie esigenze.

Nota

Quando il pacchetto richiesto esiste già nella cartella dei pacchetti globali, non verrà eseguita alcuna ricerca di origine e i mapping verranno ignorati. Valutare la possibilità di dichiarare una cartella di pacchetti globali per il repository per ottenere i vantaggi di sicurezza completi di questa funzionalità. Per migliorare l'esperienza con la cartella predefinita dei pacchetti globali, è prevista un'iterazione successiva. Per altre informazioni sul funzionamento dell'installazione dei pacchetti, vedere il documento concettuale.

Operazioni preliminari

Esistono due modi per eseguire l'onboarding completo del repository, manualmente o usando lo strumento NuGet.PackageSourceMapper.

Onboarding manuale

Per l'onboarding manuale, è possibile seguire questa procedura:

1. Dichiarare una nuova cartella dei pacchetti globali per il repository.
2. Eseguire dotnet restore per ripristinare le dipendenze.
3. Eseguire dotnet list package --include-transitive per visualizzare tutti i pacchetti transitivi e di primo livello nella soluzione.
   • Per i progetti .NET Framework che usano packages.config, il packages.config file avrà un elenco flat di tutti i pacchetti diretti e transitivi.
4. Definire i mapping in modo che ogni ID pacchetto nella soluzione, inclusi i pacchetti transitivi, corrisponda a un modello per l'origine di destinazione.
5. Eseguire dotnet nuget locals global-packages -c per cancellare la directory global-packages.
6. Eseguire il ripristino per verificare che i mapping siano stati configurati correttamente. Se i mapping non coprono completamente ogni ID pacchetto nella soluzione, i messaggi di errore consentiranno di identificare il problema.
7. Al termine del ripristino, l'operazione è stata completata. Facoltativamente, prendere in considerazione:
   • Semplificare la configurazione a un minor numero di dichiarazioni usando prefissi ID pacchetto più ampi o impostando un'origine predefinita laddove possibile.
   • La verifica dell'origine di ogni pacchetto è stata ripristinata controllando i file di metadati nella cartella dei pacchetti globali o esaminando i log di ripristino.

Onboarding automatizzato con lo strumento

Molti repository hanno un numero elevato di pacchetti e l'esecuzione manuale del lavoro può richiedere molto tempo. Lo strumento NuGet.PackageSourceMapper può generare automaticamente un oggetto NuGet.config in base ai pacchetti e alle origini noti del progetto.

Lo strumento del mapper di origine del pacchetto richiede che sia stato completato un corretto ripristino del pacchetto in cui leggerà ogni rispettivo .nupkg.metadata file generato come parte della compilazione per comprendere meglio come eseguire il mapping dei rispettivi pacchetti e origini. Lo strumento non solo illustra le dipendenze principali che considera anche tutte le dipendenze transitive durante la generazione del mapping.

Lo strumento offre diverse opzioni per generare un modello di mapping a seconda delle esigenze, consultare il post di blog e l'istruzione leggimi dello strumento per altri dettagli.

Per un'idea dell'aspetto dei mapping di origine, vedere il repository degli esempi.

Nota

• Non esistono nuget.exe o comandi dotnet.exe per la gestione della configurazione del mapping dell'origine del pacchetto, vedere NuGet/Home#10735.
• Non esistono mezzi per eseguire il mapping dei pacchetti in fase di installazione del pacchetto, vedere NuGet/Home#10730.
• Esiste una limitazione quando si usa l'attività DotNetCoreCLI@2 Azure Pipelines che può essere usata usando feed- i prefissi nella configurazione del mapping di origine. È tuttavia consigliabile usare NuGetAuthenticate per le esigenze di autenticazione e chiamare l'interfaccia della riga di comando dotnet direttamente da un'attività script. Vedere microsoft/azure-pipelines-tasks#15542.