Deprecate packages

• Status: Incubation
• Author(s): Anand Gaurav (@adgrv)

Issue

Deprecate obsolete, vulnerable or legacy packages #2867

Problem

1. There are certain cases when a package author should be able to let the package consumers know that a certain package (version) should no longer be used i.e. deprecated. As summarized in one of the comments on the issue, following are the most important cases for package deprecation:

• Vulnerable: When the package version contains a security vulnerability and the author recommends not using the package and instead a newer patched version is recommended.
  • Authors should optionally be able to provide CVE number(s) and other vulnerability metrics.
• Legacy: When the package is no longer maintained by the author and author may have published another package (ID) instead.
• Other: (other reasons like performance, critical bugs, etc.) When a version of the package is deprecated by the author and the author recommends either not using the package+version or using a newer non-deprecated version.

Today, package authors can un-list a package but there is no explicit feedback to the package consumers that a certain package version should no longer be used once its already in the project's list of packages (direct or full closure including transitive packages).

2. In addition to the above, there is no mechanism for the package authors to suggest a new package or a new version to the package consumers where the issue (due to which the package was deprecated) has been fixed.

Evidence

Being able to flag the security vulnerabilities in the packages is the primary reason behind taking up this feature. GitHub already flags the repos that depend on vulnerable packages. Today this is not enabled for NuGet packages as we do not have this feature. Similarly, npm also has the ability to flag vulnerable packages.

Solution

Marking a package as vulnerable (Server)

Package publishers should be able to mark a given package (and version) as deprecated with one of the 3 reasons:

• Vulnerable
• Legacy
• Other

and optionally provide additional information like CVE#(vulnerable packages), recommended package and version.

Out of scope

• Ability to show consumers all vulnerable packages by scanning all CVEs - This will be a useful feature. However, out of scope for this feature.
• Ability to let package authors know if the package might be vulnerable - While we are exploring this option, but is out of scope for this feature.
• A command to audit all packages in a project/solution and produce vulnerability report - out of scope for this feature.

Publisher experience

NuGet.org

1. Package authors goes to the Manage package page and expands the Deprecation section.

   Note that all the package related management is on one page now.

   

2. Is prompted to select version(s):

   By default, the version from the package version page which led to this page, is selected. Authors can choose one or many versions.

   

3. Select reason(s):

   By default, hide package checkbox is checked i.e. upon Save, the package will be deprecated as well as hidden.

   

4. Reason = Vulnerable. Provides the optional details like CVE#, CWE text, CVSS score and any custom message for consumers.

   

5. Reason = Legacy.

   Warning if All current versions not selected. Authors can choose to ignore this warning and continue with a subset of available versions.

   

   While selecting alternate recommended package, there would be auto-complete and verification built-in for existing packages. If a non-existent package ID is entered, the save button will be disabled and error message printed.

   

6. Reason = Misc./other: When package has some issues where a newer package version must be used.

   

Additional scenarios

• Selecting multiple reasons

  • If package author chooses both legacy and vulnerable reasons for the package versions to be deprecated, then both the security details and alternate package options open up for the author to provide.

• Selecting multiple versions with different deprecation states - i.e. wither some of the selected versions were already deprecated or all the versions were deprecated but due to different reasons.

  • The version list should show the deprecation and listing status in the drop-down:

    

  • If multiple versions with different deprecation states are selected (either some are deprecated and others are not OR all are deprecated with different reasons), an error is shown and Save is blocked:

    

  • If versions in the same deprecation state are selected, the deprecation reason is populated. The additional details like Security details or alternate package details are shown if they happen to be exactly same across selected versions, else the following info message is shown:

    The selected versions have been deprecated with different details and hence cannot be shown here. If you want to modify additional details, please select the versions one by one.

  • Authors can now either clear existing reasons or add more reasons to the already deprecated packages.

CLI command experience

There is no client command required for the MVP.

Consumer experience

NuGet.org

This experience is being iterated upon actively and hence may change a lot over coming days.

1. Deprecated due to security vulnerability

   

   Package author should be able to navigate to deprecate settings by clicking on the deprecated link.

   

2. Deprecated due to legacy

   

3. Deprecated due to misc./other reasons

   

Visual Studio

1. Flagged on the package listing

   

2. Flagged during/after restore:

   

3. Flagged during browse if the latest package is deprecated but not unlisted. Or if the deprecated package is selected in the drop-down before installing

   

CLI

1. Flagged on the package listing The list command should be able to output deprecated packages with --deprecated option

// dotnet list command should output the deprecated packages with --deprecated option
> dotnet list package --deprecated
Run ‘dotnet audit’ 
The following sources were used:
   nuget.org - https://api.nuget.org/v3/index.json
   Local - C:\Play\NuGet\NuGetLocal

Project `ProjectB` uses the following deprecated packages
   [netcoreapp2.0]:
   Top-level Package      Resolved	Reason		Recommendation		
   > My.Demo.Package         2.0.0 	vulnerable (High Risk)	Use version 3.2.0 (potential breaking changes)
   > My.Legacy.Package	1.1.0	legacy 		Use My.Awesome.Package 3.0.0 (latest version

To see all packages including transitive package, additional option --include-transitive can be used.

1. Flagged during/after restore: During restore, NuGet should warn with the same text as shown in the VS UI.

Restore warnings

• By default, all the warnings should have a warning ID (NUxxxx) and the text. And these warnings can either be suppressed or elevated as an error like other NuGet warnings.
• Each of the following need to have separate warning IDs and text
  • Warning when deprecated due to vulnerability
    • Low Risk

      NUxxxx: <text TBD>
      

    • Moderate Risk

      NUxxxx: <text TBD>
      

    • High Risk

      NUxxxx: <text TBD>
      

    • Critical Risk

      NUxxxx: <text TBD>
      

  • Warning when deprecated due to legacy

    NUxxxx: <text TBD>
    

  • Warning when deprecated due to misc./legacy

    NUxxxx: <text TBD>
    

• Restore warnings should show upon every full restore run, except when it NoOps i.e. when all packages were already restored and no further action was needed. This implies that even when the packages were already in Global packages folder, the deprecation warning should be shown.
• Search/Browse and List experiences should be able to always show the deprecation information from multiple sources if multiple repositories referenced have same/different deprecation states. TBD: the storyboard/screen.
• Out of scope:
  • Showing deprecation warning if the package is served from a repository that does not support deprecation.
  • Ability to show deprecation warnings for packages served from file/UNC based repositories.
  • NuGet restore showing warning consistently when the same package is hosted on more than 1 repository where one repository has deprecated the package but others have not. This is because restore picks up the package from the source that responds the fastest. Note: This information should be shown on package listing (VS package manager or CLI) i.e. even if one of the sources has the deprecation information.
  • Showing deprecation warning if package is sourced from a repository that does not have deprecation information even if it hosts packages from another repository, supporting deprecation functionality, as upstream or offline copy.