You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: How to audit package dependencies for security vulnerabilities and acting on security audit reports.
4
4
author: JonDouglas
5
5
ms.author: jodou
6
-
ms.date: 10/11/2023
6
+
ms.date: 07/19/2024
7
7
ms.topic: conceptual
8
8
---
9
9
@@ -16,24 +16,107 @@ This involves identifying vulnerabilities, evaluating risks, and making recommen
16
16
The audit can include a review of the packages themselves, as well as any dependencies and their associated risks.
17
17
The goal of the audit is to identify and mitigate any security vulnerabilities that could be exploited by attackers, such as code injection or cross-site scripting attacks.
18
18
19
-
| Project Type | NuGet | .NET SDK | Visual Studio |
We also have a [blog post](https://devblogs.microsoft.com/nuget/nugetaudit-2-0-elevating-security-and-trust-in-package-management/) which discusses our recommended method for taking action when a package with a known vulnerability is found to be used by your project, and tools to help get more information.
| 6.8 | .NET 8 SDK (8.0.100) | Visual Studio 2022 17.8 |[NuGetAudit](#running-a-security-audit-with-restore) for PackageReference |
27
+
| 6.10 | N/A | Visual Studio 2022 17.10 |[NuGetAudit](#running-a-security-audit-with-restore) for packages.config|
28
+
| 6.11 | .NET 8 SDK (8.0.400) | Visual Studio 2022 17.11 |[NuGetAuditSuppress](#excluding-advisories) for PackageReference |
29
+
| 6.12 | .NET 9 SDK (9.0.100) | Visual Studio 2022 17.12 |[Audit sources](#audit-sources). [NuGetAuditSuppress](#excluding-advisories) for packages.config. |
23
30
24
31
## Running a security audit with `restore`
25
32
26
33
The `restore` command automatically runs when you do a common package operation such as loading a project for the first time, adding a new package, updating a package version, or removing a package from your project in your favorite IDE.
27
-
A description of your dependencies is checked against a report of known vulnerabilities on the [GitHub Advisory Database](https://github.com/advisories?query=type%3Areviewed+ecosystem%3Anuget).
28
-
29
-
> [!IMPORTANT]
30
-
> For Audit to check packages, a package source that provides a vulnerability database must be used.
31
-
> NuGet.org's V3 URL is one such example (https://api.nuget.org/v3/index.json), but note that NuGet.org's V2 endpoint does not.
34
+
Your dependencies are checked against a list of known vulnerabilities provided by your [audit sources](#audit-sources).
32
35
33
36
1. On the command line, navigate to your project or solution directory.
34
37
1. Run `restore` using your preferred tooling (i.e. dotnet, MSBuild, NuGet.exe, VisualStudio etc).
35
38
1. Review the warnings and address the known security vulnerabilities.
36
39
40
+
### Configuring NuGet Audit
41
+
42
+
Audit can be configured via MSBuild properties in a `.csproj` or MSBuild file being evaluated as part of your project.
43
+
We recommend that audit is configured at a repository level.
| NuGetAuditMode | all (1) |`direct` and `all`| If you'd like to audit both top-level and transitive dependencies, you can set the value to `all`. NuGetAuditMode is not applicable for packages.config projects |
48
+
| NuGetAuditLevel | low |`low`, `moderate`, `high`, and `critical`| The minimum severity level to report. If you'd like to see `moderate`, `high`, and `critical` advisories (exclude `low`), set the value to `moderate`|
49
+
| NuGetAudit | true |`true` and `false`| If you wish to not receive security audit reports, you can opt-out of the experience entirely by setting the value to `false`|
50
+
51
+
(1) NuGetAuditMode defaulted to `direct` when it was introduced in the .NET 8.0.100 SDK and VS 17.8. In .NET 9.0.100 SDK and VS 17.12 the default changed to `all`.
52
+
53
+
#### Audit Sources
54
+
55
+
Restore downloads a server's [`VulnerabilityInfo` resource](../api/vulnerability-info.md) to check against the list of packages each project is using.
56
+
The list of sources are defined by [the `auditSources` element in NuGet.Config](../reference/nuget-config-file.md#auditsources), and [warning NU1905](#warning-codes) is raised if any of the audit sources do not provide any vulnerability info.
57
+
If `auditSources` is not defined or is cleared without adding any sources, then `packageSources` will be used and warning NU1905 is suppressed.
58
+
59
+
Since a common mitigation for package substitution attacks is [to use a single package source that upstreams from nuget.org, so that NuGet is not configured to use nuget.org as a package source](Security-Best-Practices.md#nuget-feeds), audit sources can be used to use nuget.org (or any other source that provides vulnerability information) without also using it as a package source.
60
+
61
+
The data source for nuget.org's vulnerability database is [GitHub Advisory Database](https://github.com/advisories?query=type%3Areviewed+ecosystem%3Anuget).
62
+
Note that the [V2 protocol is deprecated](../nuget-org/overview-nuget-org.md#api-endpoint-for-nugetorg), so if your nuget.config is still using the V2 endpoint, you must migrate to the V3 endpoint.
Similar to the other NuGet audit configuration properties, `NuGetAuditSuppress` items can be defined at the project or repository level.
89
+
90
+
`NuGetAuditSuppress` is available for PackageReference projects starting from NuGet 6.11, Visual Studio 17.11, and the .NET 8.0.400 SDK.
91
+
It is available for packages.config with Visual Studio 17.12 and NuGet 6.12.
92
+
93
+
### Warning codes
94
+
95
+
| Warning Code | Reason |
96
+
|--------------|----------|
97
+
|[NU1900](../reference/errors-and-warnings/NU1900.md)| Error communicating with package source, while getting vulnerability information. |
98
+
|[NU1901](../reference/errors-and-warnings/NU1901-NU1904.md)| Package with low severity detected |
99
+
|[NU1902](../reference/errors-and-warnings/NU1901-NU1904.md)| Package with moderate severity detected |
100
+
|[NU1903](../reference/errors-and-warnings/NU1901-NU1904.md)| Package with high severity detected |
101
+
|[NU1904](../reference/errors-and-warnings/NU1901-NU1904.md)| Package with critical severity detected |
102
+
|[NU1905](../reference/errors-and-warnings/NU1905.md)| An audit source does not provide a vulnerability database |
103
+
104
+
You can customize your build to treat these warnings as errors to [treat warnings as errors, or treat warnings not as errors](/dotnet/csharp/language-reference/compiler-options/errors-warnings#warningsaserrors-and-warningsnotaserrors).
105
+
For example, if you're already using `<TreatWarningsAsErrors>` to treat all (C#, NuGet, MSBuild, etc) warnings as errors, you can use `<WarningsNotAsErrors>NU1901;NU1902;NU1903;NU1904</WarningsNotAsErrors>` to prevent vulnerabilities discovered in the future from breaking your build.
106
+
Alternatively, if you want to keep low and moderate vulnerabilities as warnings, but treat high and critical vulnerabilities as errors, and you're not using `TreatWarningsAsErrors`, you can use `<WarningsAsErrors>NU1903;NU1904</WarningsAsErrors>`.
107
+
108
+
> [!NOTE]
109
+
> MSBuild properties for message severity such as `NoWarn` and `TreatWarningsAsErrors` are not supported for packages.config projects.
110
+
111
+
## `dotnet list package --vulnerable`
112
+
113
+
Once a project is successfully restored, [`dotnet list package`](/dotnet/core/tools/dotnet-list-package) has a `--vulnerable` argument to filter the packages based on which packages have known vulnerabilities.
114
+
Note that `--include-transitive` is not default, so should be included
115
+
116
+
## Actions when packages with known vulnerabilities are reported
117
+
118
+
We also have a [blog post](https://devblogs.microsoft.com/nuget/nugetaudit-2-0-elevating-security-and-trust-in-package-management/) which discusses our recommended method for taking action when a package with a known vulnerability is found to be used by your project, and tools to help get more information.
119
+
37
120
### Security vulnerabilities found with updates
38
121
39
122
If security vulnerabilities are found and updates are available for the package, you can either:
@@ -74,53 +157,6 @@ On NuGet.org, you can navigate to the package details page and click `Report pac
74
157
If no security vulnerabilities are found, this means that packages with known vulnerabilities were not found in your package graph at the present moment of time you checked.
75
158
Since the advisory database can be updated at any time, we recommend regularly checking your `dotnet restore` output and ensuring the same in your continuous integration process.
76
159
77
-
### Configuring NuGet audit
78
-
79
-
Audit can be configured via MSBuild properties in a `.csproj` or MSBuild file being evaluated as part of your project.
80
-
We recommend that audit is configured at a repository level.
| NuGetAuditMode | direct |`direct` and `all`| If you'd like to audit both top-level and transitive dependencies, you can set the value to `all`. NuGetAuditMode is not applicable for packages.config projects |
85
-
| NuGetAuditLevel | low |`low`, `moderate`, `high`, and `critical`| If you'd like to see `moderate`, `high`, and `critical` advisories, set the value to `moderate`|
86
-
| NuGetAudit | true |`true` and `false`| If you wish to not receive security audit reports, you can opt-out of the experience entirely by setting the value to `false`|
87
-
88
-
### Excluding advisories
89
-
90
-
You can choose to exclude specific advisories from the audit report by adding a new `NuGetAuditSuppress` MSBuild item for each advisory.
91
-
Define a `NuGetAuditSuppress` item with the `Include=` metadata set to the advisory URL you wish to suppress.
Similar to the other NuGet audit configuration properties, `NuGetAuditSuppress` items can be defined at the project or repository level.
100
-
101
-
`NuGetAuditSuppress` is available for PackageReference projects starting from NuGet 6.11, Visual Studio 17.11, and the .NET 8.0.400 SDK.
102
-
It is not currently available for packages.config projects.
103
-
104
-
Additionally, you have the option to suppress warnings based on their severity.
105
-
You can use `<NoWarn>` to suppress `NU1901`-`NU1904` warnings or use the `<NuGetAuditLevel>` functionality to ensure your audit reports are useful to your workflow.
106
-
107
-
### Warning codes
108
-
109
-
| Warning Code | Reason |
110
-
|--------------|----------|
111
-
| NU1900 | Error communicating with package source, while getting vulnerability information. |
112
-
| NU1901 | Package with low severity detected |
113
-
| NU1902 | Package with moderate severity detected |
114
-
| NU1903 | Package with high severity detected |
115
-
| NU1904 | Package with critical severity detected |
116
-
117
-
You can customize your build to treat these warnings as errors to [treat warnings as errors, or treat warnings not as errors](/dotnet/csharp/language-reference/compiler-options/errors-warnings#warningsaserrors-and-warningsnotaserrors).
118
-
For example, if you're already using `<TreatWarningsAsErrors>` to treat all (C#, NuGet, MSBuild, etc) warnings as errors, you can use `<WarningsNotAsErrors>NU1901;NU1902;NU1903;NU1904</WarningsNotAsErrors>` to prevent vulnerabilities discovered in the future from breaking your build.
119
-
Alternatively, if you want to keep low and moderate vulnerabilities as warnings, but treat high and critical vulnerabilities as errors, and you're not using `TreatWarningsAsErrors`, you can use `<WarningsAsErrors>NU1903;NU1904</WarningsAsErrors>`.
120
-
121
-
> [!NOTE]
122
-
> MSBuild properties for message severity such as `NoWarn` and `TreatWarningsAsErrors` are not supported for packages.config projects.
123
-
124
160
## Summary
125
161
126
162
Security auditing features are crucial for maintaining the security and integrity of software projects.
Copy file name to clipboardExpand all lines: docs/concepts/Security-Best-Practices.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -117,7 +117,7 @@ For more information about Dependabot alerts & security updates, [see the follow
117
117
118
118
**📦 Package Consumer**
119
119
120
-
When using multiple public & private NuGet source feeds, a package can be downloaded from any of the feeds. To ensure your build is predictable and secure from known attacks such as [Dependency Confusion](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610), knowing what specific feed(s) your packages are coming from is a best practice. You can use a single feed or private feed with upstreaming capabilities for protection.
120
+
Use package sources that you trust. When using multiple public & private NuGet source feeds, a package can be downloaded from any of the feeds. To ensure your build is predictable and secure from known attacks such as [Dependency Confusion](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610), knowing what specific feed(s) your packages are coming from is a best practice. You can use a single feed or private feed with upstreaming capabilities for protection.
121
121
122
122
For more information to secure your package feeds, see [3 Ways to Mitigate Risk When Using Private Package Feeds](https://azure.microsoft.com/resources/3-ways-to-mitigate-risk-using-private-package-feeds/en-us/).
Copy file name to clipboardExpand all lines: docs/consume-packages/consuming-packages-authenticated-feeds.md
+6-2Lines changed: 6 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,10 @@ ms.topic: conceptual
10
10
# Consuming packages from authenticated feeds
11
11
12
12
Many NuGet operations, such as restore and install, require communication with one or more package sources, which [can be configured in *nuget.config* files](../reference/nuget-config-file.md#packagesources).
13
+
14
+
> [!NOTE]
15
+
> Use package sources that you trust.
16
+
13
17
For HTTP feeds, NuGet will make an unauthenticated request, and if the server responds with an HTTP 401 response, NuGet will search for credentials in the following order:
@@ -37,11 +41,11 @@ This approach provides an extra layer of security by storing the credentials in
37
41
For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files).
38
42
39
43
> [!NOTE]
40
-
> Be aware that encrypted passwords are only supported on Windows.
44
+
> Be aware that encrypted passwords are only supported on Windows.
41
45
> Moreover, they can only be decrypted on the same machine and by the same user who originally encrypted them.
42
46
43
47
1.**Using Environment Variable Macros in nuget.config**: If using encrypted credentials is not possible, consider storing the credentials in the *nuget.config* file with environment variable macros.
44
-
This approach allows you to reference environment variables that contain the actual credentials.
48
+
This approach allows you to reference environment variables that contain the actual credentials.
45
49
It enhances transparency and helps end users understand how their credentials are configured.
46
50
For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files).
0 commit comments