Inspekcja zależności pakietów pod kątem luk w zabezpieczeniach

Informacje o inspekcjach zabezpieczeń

Inspekcja zabezpieczeń dla menedżerów pakietów, takich jak NuGet, to proces obejmujący analizowanie zabezpieczeń pakietów zawartych w projekcie oprogramowania. Obejmuje to identyfikowanie luk w zabezpieczeniach, ocenianie zagrożeń i zalecenia dotyczące poprawy bezpieczeństwa. Inspekcja może obejmować przegląd samych pakietów, a także wszelkie zależności i powiązane z nimi zagrożenia. Celem inspekcji jest zidentyfikowanie i ograniczenie wszelkich luk w zabezpieczeniach, które mogą zostać wykorzystane przez osoby atakujące, takie jak wstrzyknięcie kodu lub ataki skryptowe obejmujące wiele witryn.

Dostępność funkcji

NuGet	Zestaw SDK platformy .NET	Visual Studio	Funkcja
5.9	Zestaw .NET 5 SDK (5.0.200)	Nie dotyczy	dotnet list package --vulnerable
6.8	Zestaw .NET 8 SDK (8.0.100)	Visual Studio 2022 17.8	NuGetAudit dla elementu PackageReference
6.10	Nie dotyczy	Visual Studio 2022 17.10	NuGetAudit for packages.config
6.11	Zestaw .NET 8 SDK (8.0.400)	Visual Studio 2022 17.11	NuGetAuditSuppress dla elementu PackageReference
6.12	Zestaw .NET 9 SDK (9.0.100)	Visual Studio 2022 17.12	Źródła inspekcji. NuGetAuditSuppress dla pliku packages.config.
7.0	Zestaw .NET 10 SDK (10.0.100)	Visual Studio 2026	Zmiany domyślne narzędzia NuGetAuditMode dla platformy .NET 10. dotnet package update --vulnerable

Uruchamianie audytu zabezpieczeń przy użyciu restore

Polecenie restore jest uruchamiane automatycznie, gdy wykonujesz typową operację pakietu, taką jak ładowanie projektu po raz pierwszy, dodawanie nowego pakietu, aktualizowanie wersji pakietu lub usuwanie pakietu z projektu w ulubionym środowisku IDE. Zależności są sprawdzane na podstawie listy znanych luk w zabezpieczeniach, dostarczanej przez Twoje źródła audytu.

1. W wierszu polecenia przejdź do katalogu projektu lub rozwiązania.
2. Uruchom restore używając preferowanych narzędzi (np. dotnet, MSBuild, NuGet.exe, Visual Studio itp.).
3. Przejrzyj ostrzeżenia i rozwiąż znane luki w zabezpieczeniach.

Konfigurowanie inspekcji narzędzia NuGet

Audyt można skonfigurować za pomocą właściwości programu MSBuild w pliku MSBuild ocenianym jako część projektu .csproj. Zalecamy skonfigurowanie inspekcji na poziomie repozytorium.

Właściwość MSBuild	Wartość domyślna	Możliwe wartości	Uwagi
NuGetAuditMode	Zobacz 1 poniżej	direct i all	Jeśli chcesz tylko przeprowadzić inspekcję zależności najwyższego poziomu, możesz ustawić wartość na direct. Moduł NuGetAuditMode nie ma zastosowania do projektów packages.config.
NuGetAuditLevel	Niski	low, moderate, highi critical	Minimalny poziom istotności, który należy zgłosić. Jeśli chcesz zobaczyć moderate, highi critical porady (wykluczanie low), ustaw wartość na moderate
NuGetAudit	prawda	true i false	Jeśli nie chcesz otrzymywać raportów z audytu bezpieczeństwa, możesz całkowicie zrezygnować z tej opcji, ustawiając wartość na false

1. NuGetAuditMode wartość domyślna to all , gdy projekt jest przeznaczony net10.0 lub wyższy. W przeciwnym razie NuGetAuditMode wartość domyślna to direct. Gdy projekt obsługuje wiele platform docelowych, jeśli którakolwiek z platform docelowych wybierze all, audyt użyje tej wartości dla wszystkich platform docelowych.

Źródła inspekcji

Przywracanie pobiera zasób serwera VulnerabilityInfo w celu porównania z listą pakietów używanych przez każdy projekt. Lista źródeł jest definiowana przez auditSources element w pliku NuGet.Config, a ostrzeżenie NU1905 jest zgłaszane, jeśli którekolwiek ze źródeł inspekcji nie udostępnia żadnych informacji o lukach w zabezpieczeniach. Jeśli auditSources nie jest zdefiniowane lub zostaje wyczyszczone bez dodania żadnych źródeł, wtedy packageSources zostanie użyte i ostrzeżenie NU1905 zostanie pominięte.

Ponieważ powszechnym sposobem zapobiegania atakom polegającym na podmianie pakietów jest zastosowanie pojedynczego źródła pakietów, które pobiera z nuget.org, aby NuGet nie był skonfigurowany do używania nuget.org jako źródła pakietów, źródła audytu można użyć do korzystania z nuget.org (lub dowolnych innych źródeł, które dostarczają informacji o lukach w zabezpieczeniach) bez używania go jako źródła pakietów.

Źródłem danych dla bazy danych luk w zabezpieczeniach nuget.org jest GitHub Advisory Database. Należy pamiętać, że protokół V2 jest przestarzały, więc jeśli twój plik nuget.config nadal używa punktu końcowego w wersji 2, musisz przeprowadzić migrację do punktu końcowego w wersji 3.

nuget.org udostępnia dwa punkty końcowe indeksu usługi, których można użyć jako źródła inspekcji:

• https://api.nuget.org/v3/index.json — pełny indeks usługi nuget.org zawierający wszystkie zasoby NuGet (pobieranie pakietów, wyszukiwanie, dane luk w zabezpieczeniach i inne).
• https://data.nuget.org/v3/index.json — indeks usługi typu vulnerability-data-only, który nie zawiera zawartości pakietu ani innych zasobów.

Punkt data.nuget.org końcowy jest przydatny dla organizacji, które blokują dostęp na api.nuget.org poziomie sieci. Ponieważ ten punkt końcowy obsługuje tylko dane dotyczące luk w zabezpieczeniach, a nie pakiety, administratorzy sieci, którzy blokują api.nuget.org w celu zapobiegania pobieraniu pakietów, mogą zechcieć zezwolić na data.nuget.org, jeśli zostaną o to poproszeni.

<configuration>
    <auditSources>
        <clear />
        <add key="nuget.org" value="https://data.nuget.org/v3/index.json" />
    </auditSources>
</configuration>

Uwaga: poniższa tabela zawiera listę funkcji, które obsługują źródła inspekcji.

Wprowadzone w	Funkcja obsługująca źródła inspekcji
NuGet 6.12, .NET 9.0.100 SDK i Visual Studio 2022 17.12	Przywróć
NuGet 6.14, .NET 9.0.300 SDK	dotnet package list --vulnerable
NuGet 7.0 i Visual Studio 2026	Obsługa biblioteki NuGet AuditSources w interfejsie użytkownika menedżera pakietów programu Visual Studio

Kody ostrzegawcze

Kod ostrzegawczy	Przyczyna
NU1900	Błąd podczas komunikowania się ze źródłem pakietu podczas uzyskiwania informacji o lukach w zabezpieczeniach.
NU1901	Wykryto pakiet o niskiej ważności
NU1902	Pakiet o wykrytej umiarkowanej ciężkości
NU1903	Wykryto pakiet o wysokiej ważności
NU1904	Wykryto pakiet o krytycznej powadze
NU1905	Źródło inspekcji nie zapewnia bazy danych luk w zabezpieczeniach

Możesz dostosować kompilację, aby traktować te ostrzeżenia jako błędy, aby traktować ostrzeżenia jako błędy lub traktować ostrzeżenia nie jako błędy. Jeśli na przykład używasz już <TreatWarningsAsErrors> do traktowania wszystkich ostrzeżeń (C#, NuGet, MSBuild itp.) jako błędów, możesz użyć polecenia <WarningsNotAsErrors>$(WarningsNotAsErrors);NU1901;NU1902;NU1903;NU1904</WarningsNotAsErrors> , aby zapobiec wykryciu luk w zabezpieczeniach w przyszłości przed przerwaniem kompilacji. Alternatywnie, jeśli chcesz zachować niskie i umiarkowane luki w zabezpieczeniach jako ostrzeżenia, ale traktować wysokie i krytyczne luki w zabezpieczeniach jako błędy, a nie używasz TreatWarningsAsErrors, możesz użyć <WarningsAsErrors>$(WarningsAsErrors);NU1903;NU1904</WarningsAsErrors>.

Uwaga

Właściwości programu MSBuild dotyczące poziomu ważności komunikatów, takie jak NoWarn i TreatWarningsAsErrors, nie są obsługiwane w projektach typu packages.config.

Wykluczenie ostrzeżeń

Można wykluczyć ostrzeżenia, dodając nowy element MSBuild NuGetAuditSuppress dla każdego ostrzeżenia. Zdefiniuj element NuGetAuditSuppress z metadanymi Include= ustawionymi na adres URL porady, który chcesz zablokować.

<ItemGroup>
    <NuGetAuditSuppress Include="https://github.com/advisories/XXXX" />
</ItemGroup>

Podobnie jak w przypadku innych właściwości konfiguracji inspekcji narzędzia NuGet, NuGetAuditSuppress elementy można zdefiniować na poziomie projektu lub repozytorium.

NuGetAuditSuppress Jest dostępny dla projektów PackageReference począwszy od nuGet 6.11, Visual Studio 17.11 i .NET 8.0.400 SDK. Jest dostępny dla pakietów.config z programu Visual Studio 17.12 i NuGet 6.12.

Kiedy należy wykluczyć porady

W scenariuszach, w których przeanalizowano konkretny poradnik i ustaliliśmy, że nie ma on zastosowania do danego scenariusza lub czujesz się komfortowo z nakładanymi przez niego ryzykiem, możesz wykluczyć określone porady z raportu inspekcji. Należy pamiętać, że spowoduje to całkowite pominięcie komunikatów doradczych, nawet w przypadku pakietów, które dzielą ten komunikat doradczy, ale mogą nie być częścią twojego projektu. NuGetAuditSuppress należy rozważyć ostateczność zarządzania poradami.

Akcje, gdy są zgłaszane pakiety ze znanymi lukami w zabezpieczeniach

Uzyskanie ostrzeżenia o pakietach ze znanymi lukami w zabezpieczeniach jest tylko częścią procesu. Po odnalezieniu należy podjąć akcję, aby usunąć potencjalną lukę w zabezpieczeniach z rozwiązania.

Najprostszym przypadkiem jest to, że pakiet, do którego odwołujesz się bezpośrednio, ma znaną lukę w zabezpieczeniach. W takiej sytuacji zaktualizuj wersję pakietu do wersji, która naprawia lukę w zabezpieczeniach.

Luki w zabezpieczeniach pakietów mogą być zgłaszane zarówno w bezpośrednich, jak i przechodnich odniesieniach do pakietów. Akcja, którą podejmujesz w celu rozwiązania, może być inna z tego powodu.

Wykryte luki w zabezpieczeniach związane z aktualizacjami

Jeśli znaleziono luki w zabezpieczeniach, a aktualizacje są dostępne dla pakietu, możesz wykonać jedną z następujących czynności:

• Edytuj lokalizację .csproj lub inną wersję pakietu (Directory.Packages.props) przy użyciu nowszej wersji zawierającej poprawkę zabezpieczeń.
• Użyj interfejsu użytkownika menedżera pakietów NuGet w programie Visual Studio, aby zaktualizować pojedynczy pakiet.
• Uruchom polecenie , dotnet package update --vulnerable aby zaktualizować wszystkie pakiety podatne na zagrożenia w projekcie lub rozwiązaniu do pierwszej wersji bez znanych luk w zabezpieczeniach.
• dotnet package update Uruchom polecenie dotnet package update lub z właściwym identyfikatorem pakietu, aby zaktualizować do najnowszej wersji. Użyj dotnet add package przy korzystaniu z programu .NET 9 lub starszych wersji.
• Użyj serwera NuGet Model Context Protocol (MCP), który ma możliwość aktualizowania pakietów w projekcie do wersji, które rozpoznają znane luki w zabezpieczeniach. Aby uzyskać więcej informacji, zobacz Naprawianie luk w zabezpieczeniach pakietów .

Pakiety przechodnie

Często w zależności przechodniej występuje luka w zabezpieczeniach. Zalecamy preferowanie aktualizacji pakietów "najbliżej" Twoich bezpośrednich powiązań. Nie ma jednak nic złego w przypadku uaktualniania pakietu ze znaną luką w zabezpieczeniach.

Załóżmy na przykład, że projekt odwołuje się do pakietu A. Pakiet A ma zależność od pakietu B, który z kolei ma zależność od pakietu C. W tym przykładzie rozważymy, że pakiet C w wersji 1.0.0 ma znaną lukę w zabezpieczeniach, usuniętą w wersji 2.0.0. Zalecamy, aby najpierw spróbować uaktualnić pakiet A. Jeśli to nie rozwiąże problemu z ostrzeżeniem inspekcji, spróbuj uaktualnić pakiet B. Jeśli to nie rozwiąże problemu z ostrzeżeniem inspekcji, uaktualnij język C bezpośrednio. Aby to ułatwić, należy znaleźć transytywną ścieżkę pakietu.

Podsumowując, jeśli w zależnościach przechodnich pakietu najwyższego poziomu istnieje znana luka w zabezpieczeniach, dostępne są następujące opcje:

• Sprawdź, czy pakiet najwyższego poziomu zawiera aktualizację, która nie ma przejściowej luki w zabezpieczeniach, i zaktualizuj je zamiast tego.
• Zaktualizuj najbliższy pakiet w twoich bezpośrednich referencjach bez odniesienia do luki w zabezpieczeniach.
• Dodaj stałą wersję pakietu jako bezpośrednie odwołanie do pakietu. Uwaga: pamiętaj, aby usunąć to odwołanie po udostępnieniu nowej aktualizacji wersji pakietu i zachować zdefiniowane atrybuty dla oczekiwanego zachowania.
• Użyj centralnego zarządzania pakietami z funkcjonalnością przypinania przechodniego. Należy pamiętać, że jeśli pakujesz projekt do własnego pakietu w celu udostępnienia innym osobom, narzędzie CPM z przejściowym przypinaniem spowoduje, że pakiety staną się zależnościami, nawet jeśli projekt nie wywołuje bezpośrednio interfejsów API dla tego pakietu.
• Zablokuj komunikat, dopóki nie będzie można go rozwiązać.
• Zgłoś problem w śledzeniu pakietu najwyższego poziomu, aby zażądać aktualizacji.

Znajdowanie przejściowej ścieżki pakietu

Istnieje kilka sposobów znajdowania ścieżki pakietu. Preferowana metoda zależy od tego, jakie narzędzia są zwykle używane podczas opracowywania.

dotnet nuget dlaczego

W wierszu polecenia możesz użyć dotnet nuget why polecenia , aby zrozumieć, dlaczego pakiety przechodnie są uwzględniane w grafie pakietów projektu.

Eksplorator rozwiązań programu Visual Studio

Projekty stylu SDK udostępniają również całkowity wykres pakietów w węźle zależności projektu. Można go również przeszukiwać! Rozwiń opcje wyszukiwania i włącz opcję "wyszukaj pliki zewnętrzne".

Przeszukaj nazwę pakietu i wyświetli wszystkie wystąpienia w węźle Zależności każdego projektu.

Interfejs użytkownika menedżera pakietów NuGet programu Visual Studio

W karcie Zainstalowane interfejsu użytkownika menedżera pakietów programu Visual Studio, w przypadku, gdy projekt korzysta z funkcji PackageReference do zarządzania pakietami, zostaną wyświetlone zarówno pakiety bezpośrednie, jak i przechodnie. Obecnie dzieje się tak tylko wtedy, gdy zarządzasz pakietami dla projektu, a nie w przypadku rozwiązania.

Jeśli umieścisz wskaźnik myszy nad pakietem na liście pakietów, etykietka narzędzia będzie zawierać nazwę jednego bezpośredniego pakietu, który spowodował dołączenie pakietu przejściowego do projektu.

Wykryto luki w zabezpieczeniach bez aktualizacji

W przypadku, gdy w pakiecie istnieje znana luka w zabezpieczeniach bez poprawki zabezpieczeń, możesz wykonać następujące czynności.

• Sprawdź, czy nie ma żadnych czynników korygujących opisanych w raporcie doradczym.
• Użyj sugerowanego pakietu, jeśli pakiet jest oznaczony jako przestarzały lub jest porzucony.
• Jeśli pakiet jest open source, rozważ przyczynienie się do poprawki.
• Otwórz zgłoszenie w systemie śledzenia zgłoszeń pakietu.

Sprawdzanie czynników korygujących

Przejrzyj poradnik zabezpieczeń pod kątem wszelkich czynników korygujących, które mogą umożliwić dalsze korzystanie z pakietu z występującą luką. Luka w zabezpieczeniach może istnieć tylko wtedy, gdy kod jest używany w określonej strukturze, systemie operacyjnym lub wywołaniu specjalnej funkcji.

Korzystanie z sugerowanego pakietu

Jeśli dla używanego pakietu zostanie zgłoszone ostrzeżenie dotyczące zabezpieczeń, a pakiet jest oznaczony jako przestarzały lub wydaje się porzucony, rozważ użycie dowolnego sugerowanego pakietu alternatywnego określonego przez autora pakietu lub pakietu o podobnej funkcjonalności, który jest aktywnie utrzymywany.

Wnieś poprawkę

Jeśli poprawka nie istnieje w biuletynie zabezpieczeń, możesz zasugerować zmiany, które dotyczą luki w zabezpieczeniach w żądaniu ściągnięcia w repozytorium open source pakietu lub skontaktować się z autorem za pośrednictwem Contact owners sekcji na stronie szczegółów pakietu NuGet.org.

Otwórz problem

Jeśli nie chcesz naprawić luki w zabezpieczeniach lub nie możesz zaktualizować lub zastąpić pakietu, otwórz problem w monitorze problemów pakietu lub preferowanej metodzie kontaktu. Na NuGet.org możesz przejść do strony szczegółów pakietu i kliknąć Report package , aby uzyskać kontakt z autorem.

Nie znaleziono luk w zabezpieczeniach

Jeśli nie znaleziono żadnych luk w zabezpieczeniach, oznacza to, że pakiety ze znanymi lukami w zabezpieczeniach nie zostały znalezione w grafie pakietu w chwili obecnej sprawdzenia. Ponieważ baza danych doradczych może być aktualizowana w dowolnym momencie, zalecamy regularne sprawdzanie poprawności dotnet restore danych wyjściowych i zapewnienie tego również w procesie ciągłej integracji.

Uruchamianie audytu narzędzia NuGet podczas ciągłej integracji

Oddzielanie błędów od ostrzeżeń za pomocą dedykowanego kanału audytu

Wyrażenia warunkowe MSBuild umożliwiają skonfigurowanie dedykowanego potoku CI do przeprowadzania audytów, bez traktowania ostrzeżeń audytowych jako błędów w innych potokach lub podczas kompilacji lokalnych. W zależności od systemu ciągłej integracji i procesów zespołu, może nieudane uruchomienia potoku audytu wysyłać e-maile do zespołu, lub można mieć dashboard, na którym można pokazać odznakę najnowszego uruchomienia potoku.

Podobnie jak wiele rzeczy w programowaniu, istnieje wiele sposobów osiągnięcia wyniku. Jedną z opcji jest traktowanie ostrzeżeń audytu NuGet jako błędów tylko w potoku audytu.

<PropertyGroup>
  <NuGetAuditCodes>NU1900;NU1901;NU1902;NU1903;NU1904;NU1905</NuGetAuditCodes>
  <WarningsAsErrors Condition=" '$(AuditPipeline)' == 'true' ">$(WarningsAsErrors);$(NuGetAuditCodes)</WarningsAsErrors>
  <WarningsNotAsErrors Condition=" '$(AuditPipeline)' != 'true' ">$(WarningsNotAsErrors);$(NuGetAuditCodes)</WarningsNotAsErrors>
</PropertyGroup>

Następnie w potoku uruchomisz operację przywracania określającą właściwość używaną przez warunek. Na przykład przy użyciu składni funkcji GitHub Actions:

- name: Restore with NuGet Auditing
  run: dotnet restore -p:AuditPipeline=true

Nazwa AuditPipeline właściwości jest tylko przykładem i można ją dostosować tak, jak chcesz, o ile nazwa jest taka sama zarówno w warunku MSBuild, jak i w wierszu polecenia. Program MSBuild używa również zmiennych środowiskowych podczas odczytywania właściwości, która nie została jeszcze zdefiniowana, więc zmienna środowiskowa jest alternatywą dla parametru wiersza polecenia.

Korzystając z warunków, aby selektywnie powodować niepowodzenie przywracania przez ostrzeżenia audytu NuGet, można mieć dedykowany potok do sprawdzania pakietów pod kątem znanych luk w zabezpieczeniach, zapobiegając blokowaniu poprawek błędów nowymi poradami zabezpieczeń w nieodpowiednich momentach. Utrzymywanie ostrzeżeń inspekcji NuGet włączonych dla kompilacji lokalnych umożliwia programistom uzyskanie nieblokującego powiadomienia o nowych ostrzeżeniach dotyczących bezpieczeństwa i może zachęcić do szybszej aktualizacji wersji pakietów w celu naprawy luk w zabezpieczeniach, zamiast oczekiwania na sprawdzenie stanu potoku inspekcji.

Upewnij się, że audytowane projekty są przywracane

Narzędzia NuGet w programie MSBuild 17.13 i .NET 9.0.200 dodały właściwości RestoreProjectCount, RestoreSkippedCount i RestoreProjectsAuditedCount wyjściowe w zadaniu przywracania. Może to służyć do wymuszenia, aby audyt został uruchomiony podczas przywracania. Należy pamiętać, że te właściwości wyjściowe nie są dostępne w przypadku przywracania statycznego grafu.

Ponieważ program MSBuild jest językiem skryptowym, można to osiągnąć na wiele różnych sposobów, ale także ma takie same ograniczenia, jak program MSBuild. Przykładem jest utworzenie pliku Directory.Solution.targets w tym samym katalogu co plik rozwiązania, którego zawartość ma element docelowy podobny do poniższego. Należy pamiętać, że często używany jest plik Directory.Build.props , ale jest importowany przez projekty. Jednak docelowy element przywracania i zadanie NuGet działa na poziomie rozwiązania, dlatego musi znajdować się w pliku rozszerzalności rozwiązania MSBuild, a nie w pliku projektu/kompilacji.

<Project>
    <Target Name="AssertRestoreTaskOutputProperties"
            AfterTargets="Restore"
            Condition="'$(CI)' == 'true'">
        <Error
            Condition="'$(RestoreProjectsAuditedCount)' != '$(RestoreProjectCount)'"
            Text=""Restore did not audit every project in the solution. Expected: $(RestoreProjectCount) Found: $(RestoreProjectsAuditedCount)"" />
    </Target>
</Project>

W zależności od przypadku użycia możesz użyć warunku '$(RestoreProjectCount)' != '$([MSBuild::Add($(RestoreProjectsAuditedCount), $(RestoreSkippedCount))' w komunikacie o błędzie, aby uwzględnić projekty, które zostały pominięte podczas przywracania, ponieważ były już aktualne. Podobnie pomyśl o tym, czy ten błąd ma wystąpić wszędzie lub tylko w potokach ciągłej integracji oraz o tym, jakie zmienne środowiskowe są zdefiniowane w środowisku ciągłej integracji, i uwzględnij to w warunku celu. pl-PL: Ponownie, ponieważ MSBuild jest językiem skryptowym, możesz użyć dowolnej z jego możliwości, aby dostosować repozytorium według własnych potrzeb. Wyświetlanie metaprojektów MSBuild oraz dzienników binlogów jest przydatne do opracowywania i rozwiązywania problemów z celami na poziomie rozwiązania.

dotnet list package --vulnerable

dotnet list package --vulnerable ma argument do filtrowania pakietów w oparciu o znane luki w zabezpieczeniach. Należy pamiętać, że --include-transitive nie jest to ustawienie domyślne, dlatego należy je uwzględnić.