Skip to content

Commit

Permalink
Merge pull request #9992 from NuGet/dev-drewgil-update-dotnet-cli-spec
Browse files Browse the repository at this point in the history 
Update dotnet cli vulnerable spec following spec review
  • Loading branch information
@drewgillies
drewgillies committed Sep 16, 2020
2 parents 25cd8b9 + bbd1b62 commit 756e168
Showing 1 changed file with 60 additions and 88 deletions.
148 changes: 60 additions & 88 deletions designs/PackageVulnerability/DotnetListPackageVulnerable.md
View file
@@ -1,7 +1,7 @@
# Package Vulnerability Support in DotNet CLI

* Status: **Reviewing**
* Authors: [Xavier Decoster](https://github.com/xavierdecoster)
* Authors: [Xavier Decoster](https://github.com/xavierdecoster), [Drew Gillies](https://github.com/drewgillies)

## Issue

Expand All @@ -11,7 +11,7 @@

Developers take dependency on a set of packages directly or indirectly (through transitive dependencies) and have no way to understand if any of their dependencies bring in any known vulnerabilities.

NuGet should be able to flag vulnerable packages used in projects/solutions. To support this capability from the commandline, a new `dotnet.exe` CLI option will be introduced.
NuGet should be able to flag vulnerable packages used in projects/solutions. To support this capability from the command line, a new `dotnet.exe` CLI option will be introduced.

This CLI command provides a way to verify *already installed* (direct and indirect) dependencies against known vulnerabilities.

Expand All @@ -34,13 +34,12 @@ Combining the `--vulnerable` command option with the following flags will not be

* `--outdated`
* `--deprecated`
* `--offline`

The following flags will be ignored (but not error) when combined with the `--vulnerable` command option:
The following flags will are only relevant to the `--outdated` command option. They will continue to be ignored, without erroring, when using the `--deprecated` option, which is existing behavior. They will now also be ignored without erroring when using the `--vulnerable` option:

* `--include-prerelease` (currently requires `--outdated` option)
* `--highest-minor` (currently requires `--outdated` option)
* `--highest-patch` (currently requires `--outdated` option)
* `--include-prerelease`
* `--highest-minor`
* `--highest-patch`

An informational message will be printed when the ignored command options are used:

Expand All @@ -53,31 +52,27 @@ The command option(s) '--include-prerelease', '--highest-minor', and '--highest-
We'll introduce a new `--vulnerable` command option to the existing `dotnet list package` command.
This command option will offer a detailed view of already installed packages with known vulnerabilities.

The default behavior for `dotnet list package` will be to add a marker next to the packages that have known vulnerabilities (as well as those that are known to be deprecated or outdated). This is a change in behavior, as the default `dotnet list package` command will now try to reach servers online to get additional metadata.

To continue supporting the old behavior, a new `--offline` command option will be introduced.
The default behavior for `dotnet list package` will be unchanged.

### DotNet CLI

The `dotnet` CLI repository must be updated to:

* forward the `--vulnerable` command option for the `dotnet list package` command,
* forward the `--offline` command option for the `dotnet list package` command,
* handle the invalid combinations of command options, such as `--vulnerable --outdated`, `--vulnerable --deprecated`, and any combination of the new `--offline` option with either `--outdated`, `--deprecated`, or `--vulnerable` options.
* handle the invalid combinations of command options, such as `--vulnerable --outdated`, `--vulnerable --deprecated`, and `--outdated --deprecated` (this last case is existing behavior).

### NuGet xplat CLI

The `nuget` xplat CLI code must be updated to:

* handle the `--vulnerable` command option for the `dotnet list package` command,
* handle the `--offline` command option for the `dotnet list package` command,
* handle the invalid combinations of command options, such as `--vulnerable --outdated`, `--vulnerable --deprecated`, and any combination of the new `--offline` option with either `--outdated`, `--deprecated`, or `--vulnerable` options.
* handle the invalid combinations of command options, such as `--vulnerable --outdated`, `--vulnerable --deprecated`, and `--outdated --deprecated` (this last case is existing behavior).

### Command Output

#### Help

The `--help` output must be updated to include the new `--vulnerable` and `--offline` options. Other existing options should refer to the `--vulnerable` and `--offline` options as needed.
The `--help` output must be updated to include the new `--vulnerable` option. Other existing options should refer to the `--vulnerable` option as needed.

```shell
Usage: dotnet list <PROJECT | SOLUTION> package [options]
Expand All @@ -87,10 +82,9 @@ Arguments:

Options:
-h, --help Show command line help.
--outdated Lists packages that have newer versions. Cannot be combined with `--deprecated`, `--vulnerable`, or `--offline` options.
--deprecated Lists packages that are deprecated. Cannot be combined with `--outdated`, `--vulnerable`, or `--offline` options.
--vulnerable Lists packages that have known vulnerabilities. Cannot be combined with `--outdated`, `--deprecated`, or `--offline` options.
--offline Prevents online resources to be queried for information about newer package versions, deprecation metadata, or known vulnerabilities. Cannot be combined with `--outdated`, `--deprecated`, or `--vulnerable` options.
--outdated Lists packages that have newer versions. Cannot be combined with `--deprecated` or `--vulnerable` options.
--deprecated Lists packages that are deprecated. Cannot be combined with `--outdated` or `--vulnerable` options.
--vulnerable Lists packages that have known vulnerabilities. Cannot be combined with `--outdated` or `--deprecated` options.
--framework <FRAMEWORK | FRAMEWORK\RID> Chooses a framework to show its packages. Use the option multiple times for multiple frameworks.
--include-transitive Lists transitive and top-level packages.
--include-prerelease Consider packages with prerelease versions when searching for newer packages. Requires the '--outdated' option.
Expand All @@ -102,7 +96,7 @@ Options:

#### List

The default behavior for `dotnet list package` will be to reach out to the configured online sources to retrieve information about newer package version, deprecation metadata, and known package vulnerabilities. The output will be updated to include markers for each.
The default behavior for `dotnet list package` will be unchanged.

```shell
dotnet list package
Expand All @@ -113,23 +107,16 @@ Lists the package references for a project or solution.
```shell
> dotnet list package

The following sources were used:
nuget.org - https://api.nuget.org/v3/index.json
Local - C:\NuGet\NuGetLocal

Project 'MySampleProject' has the following package references
[netcoreapp2.1]:
Top-level Package Requested Resolved
> Microsoft.ML 0.11.0 0.11.0
> Microsoft.NETCore.App (A) [2.1.0, ) 2.1.0
> My.Outdated.Package 0.1.0 0.1.0 (O)
> My.Deprecated.Package 1.0.0 1.0.0 (D)
> My.Vulnerable.Package 1.0.1 1.0.1 (V)
> My.Outdated.Package 0.1.0 0.1.0
> My.Deprecated.Package 1.0.0 1.0.0
> My.Vulnerable.Package 1.0.1 1.0.1

(A): Auto-referenced package(s).
(O): Outdated package(s). Use 'dotnet list package --outdated' for more info.
(D): Deprecated package(s). Use 'dotnet list package --deprecated' for more info.
(V): Vulnerable package(s). Use 'dotnet list package --vulnerable' for more info.
```
#### Outdated
Expand All @@ -140,19 +127,6 @@ dotnet list package --outdated
Lists which installed packages have newer versions available.
If any of the outdated packages is vulnerable, a `(V)` marker is printed next to the version indicating the package version is known to be vulnerable.
*Combining the `--vulnerable` option with the `--outdated` option is (currently) not supported. When doing so, the following error message will be presented:*
```shell
> dotnet list package --outdated --vulnerable

Invalid command. Combining '--outdated' and '--vulnerable' options is not supported.
```
**Important! Installed packages that are vulnerable but not outdated will not be part of this command's output.**
A description is printed to the console explaining what the `(V)` marker means.
```shell
> dotnet list package --outdated
Expand All @@ -161,46 +135,42 @@ The following sources were used:
nuget.org - https://api.nuget.org/v3/index.json
Local - C:\NuGet\NuGetLocal

3 packages need your attention - 2 outdated, 1 deprecated, 1 vulnerable.
Project `ClassLibrary1` has the following updates to its packages
[netcoreapp2.0]:
Top-level Package Requested Resolved Latest
> EntityFramework 6.1.2 6.1.2 6.2.0
> NUnit 2.4.0 2.6.4 3.8.1
> My.Sample.Pkg 2.1.3 4.1.0 4.1.0
```
Package Requested Resolved Latest
EntityFramework 6.1.2 6.1.2 6.2.0
NUnit 2.4.0 (D) 2.6.4 3.8.1
My.Sample.Pkg 2.1.3 (V) 4.1.0 4.1.0
Notes:
* *Important! Installed packages that are vulnerable or deprecated but not outdated will not be part of this command's output.*
(D): Deprecated package(s). Use 'dotnet list package --deprecated' for more info.
(V): Vulnerable package(s). Use 'dotnet list package --vulnerable' for more info.
```
- The `(D)` marker will be removed from this report.
*Combining the `--outdated` option with the `--offline` options is not supported. When doing so, the following error message will be presented:*
*Combining the `--vulnerable` option with the `--outdated` option is (currently) not supported. When doing so, the following error message will be presented:*
```shell
> dotnet list package --outdated --offline
> dotnet list package --outdated --vulnerable
Invalid command. Combining the '--outdated' and '--offline' options is not supported.
Invalid command. Combining '--outdated' and '--vulnerable' options is not supported.
```
#### Deprecated
*Combining the `--outdated` option with the `--deprecated` option is (currently) not supported. When doing so, the following error message will be presented:*
```shell
dotnet list package --deprecated
```
> dotnet list package --outdated --deprecated
Lists which installed packages have been deprecated.
If any of the deprecated packages is vulnerable, a `(V)` marker is printed next to the version indicating the package version is known to be vulnerable.
Invalid command. Combining '--outdated' and '--deprecated' options is not supported.
```
*Combining the `--deprecated` option with the `--vulnerable` option is (currently) not supported. When doing so, the following error message will be presented:*
#### Deprecated
```shell
> dotnet list package --deprecated --vulnerable
Invalid command. Combining '--deprecated' and '--vulnerable' options is not supported.
dotnet list package --deprecated
```
**Important! Installed packages that are vulnerable but not deprecated will not be part of this command's output.**
A description is printed to the console explaining what the `(V)` marker means.
Lists which installed packages have been deprecated.
```shell
> dotnet list package --deprecated
Expand All @@ -215,20 +185,28 @@ Project `ClassLibrary1` uses the following deprecated packages
> My.Legacy.Package 2.0.0 2.0.0 Legacy My.Awesome.Package >= 3.0.0
> My.Buggy.Package 1.1.0 1.1.0 Critical Bugs My.NotBuggy.Package >= 2.0.0
> My.Deprecated.Package 3.2.1 3.2.1 Other My.NotBuggy.Package >= 2.0.0
> My.CompletelyBroken.Package 0.9.0 (V) 0.9.0 Legacy, Critical Bugs My.Awesome.Package >= 1.0.0

> To see all packages including transitive packages, additional option `--include-transitive` can be used.
(V): Vulnerable package(s). Use 'dotnet list package --vulnerable' for more info.
> My.CompletelyBroken.Package 0.9.0 0.9.0 Legacy, Critical Bugs My.Awesome.Package >= 1.0.0
```
The table output for `--deprecated` should also include a new `Requested` column to improve clarity and for consistency with `--outdated` and `--vulnerable` commands.
Notes:
* *Important! Installed packages that are vulnerable or outdated but not deprecated will not be part of this command's output.*
* The table output for `--deprecated` should also include a new `Requested` column to improve clarity and for consistency with `--outdated` and `--vulnerable` commands.
*Combining the `--deprecated` option with the `--offline` options is not supported. When doing so, the following error message will be presented:*
*Combining the `--deprecated` option with the `--vulnerable` option is (currently) not supported. When doing so, the following error message will be presented:*
```shell
> dotnet list package --deprecated --vulnerable

Invalid command. Combining '--deprecated' and '--vulnerable' options is not supported.
```
*Combining the `--deprecated` option with the `--outdated` option is (currently) not supported. When doing so, the following error message will be presented:*
```shell
> dotnet list package --deprecated --offline
> dotnet list package --deprecated --outdated

Invalid command. Combining the '--deprecated' and '--offline' options is not supported.
Invalid command. Combining '--deprecated' and '--outdated' options is not supported.
```
#### Vulnerable
Expand All @@ -248,21 +226,15 @@ The following sources were used:

Project `ClassLibrary1` uses the following vulnerable packages
[netcoreapp2.0]:
Top-level Package Requested Resolved Vulnerability
> My.Vulnerable.Package 2.0.0 2.0.0 https://URL-to-vuln-details
> My.Fixed.Package 1.1.0 1.1.0 https://URL-to-vuln-details

> To see transitive packages, add the `--include-transitive` option.
> To see prerelease packages, add the `--include-prerelease` option.
Top-level Package Requested Resolved Severity Vulnerability
> My.Vulnerable.Package 2.0.0 2.0.0 Low https://URL-to-vuln-details
> My.Fixed.Package 1.1.0 1.1.0 Critical https://URL-to-vuln-details
```
*Combining the `--vulnerable` option with the `--offline` options is not supported. When doing so, the following error message will be presented:*
Notes:
* *Important! Installed packages that are deprecated or outdated but not vulnerable will not be part of this command's output.*
```shell
> dotnet list package --vulnerable --offline

Invalid command. Combining the '--vulnerable' and '--offline' options is not supported.
```
* The Severity values will be colored default for Low, yellow for Moderate, and red for High and Critical (note that we can't represent this in GitHub markdown above).
*Combining the `--vulnerable` option with the `--deprecated` option is (currently) not supported. When doing so, the following error message will be presented:*
Expand All @@ -282,7 +254,7 @@ Invalid command. Combining '--vulnerable' and '--outdated' options is not suppor
#### Flagged during/after restore
This is out of scope for the MVP of this feature, but is on the roadmap for a future iteration.
This is out of scope for the MVP of this feature.
#### Examples
Expand Down

0 comments on commit 756e168

Please sign in to comment.