Skip to content

Commit 1829394

Browse files
committed
Add info about data.nuget.org
1 parent 2c1b10d commit 1829394

6 files changed

Lines changed: 33 additions & 1 deletion

File tree

docs/api/implementation-guide.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,10 @@ NuGet does not require that resources in the [service index](./service-index.md)
112112
However, there are several reasons why some companies choose to block nuget.org at the firewall, or have on-prem feeds on a disconnected network.
113113
To avoid connectivity issues, we recommend serving vulnerability data from your own web app, so that NuGet clients only make HTTP connections to the host the feed is installed on.
114114

115+
As an alternative to caching or proxying, users can ask their network administrator to allow access to `https://data.nuget.org/v3/index.json` and configure it as an [audit source](../concepts/Auditing-Packages.md#audit-sources).
116+
This endpoint only serves vulnerability data, not packages, so it might be allowed even when `api.nuget.org` is blocked.
117+
When users configure `data.nuget.org` as an audit source, your feed may not need to implement the `VulnerabilityInfo` resource.
118+
115119
✔️ DO cache or proxy the vulnerability pages in your own web app
116120

117121
❌ DO NOT advertise api.nuget.org in your service index or vulnerability index without a configuration to turn this off.

docs/concepts/Auditing-Packages.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,11 +62,19 @@ Since a common mitigation for package substitution attacks is [to use a single p
6262
The data source for nuget.org's vulnerability database is [GitHub Advisory Database](https://github.com/advisories?query=type%3Areviewed+ecosystem%3Anuget).
6363
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.
6464

65+
nuget.org provides two service index endpoints that can be used as an audit source:
66+
67+
- `https://api.nuget.org/v3/index.json` — The full nuget.org service index, which includes all NuGet resources (package download, search, vulnerability data, and more).
68+
- `https://data.nuget.org/v3/index.json` — A vulnerability-data-only service index that doesn't include package content or other resources.
69+
70+
The `data.nuget.org` endpoint is useful for organizations that block access to `api.nuget.org` at the network level.
71+
Because this endpoint only serves vulnerability data and not packages, network administrators who block `api.nuget.org` to prevent package downloads might be willing to allow `data.nuget.org` if asked.
72+
6573
```xml
6674
<configuration>
6775
<auditSources>
6876
<clear />
69-
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
77+
<add key="nuget.org" value="https://data.nuget.org/v3/index.json" />
7078
</auditSources>
7179
</configuration>
7280
```

docs/concepts/Security-Best-Practices.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,10 @@ For example:
175175
</configuration>
176176
```
177177

178+
> [!TIP]
179+
> If your organization blocks access to `api.nuget.org`, consider asking the network administrator to allow `https://data.nuget.org/v3/index.json` and configure it as an [audit source](Auditing-Packages.md#audit-sources) for [NuGet Audit](Auditing-Packages.md).
180+
> This endpoint only serves vulnerability data, not packages, so it might be allowed even when `api.nuget.org` is blocked.
181+
178182
### NuGet feeds
179183

180184
**📦 Package Consumer**

docs/nuget-org/overview-nuget-org.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,11 @@ To use NuGet.org as a package repository with NuGet clients, you should use the
5050
Older clients can still use the V2 protocol to reach NuGet.org. However, please note, NuGet clients 3.0 or later will have slower and less reliable service using the V2 protocol:
5151

5252
`https://www.nuget.org/api/v2` (**The V2 protocol is deprecated!**)
53+
54+
nuget.org also provides a vulnerability-data-only endpoint:
55+
56+
`https://data.nuget.org/v3/index.json`
57+
58+
This service index only contains the [`VulnerabilityInfo`](../api/vulnerability-info.md) resource and doesn't serve packages.
59+
It's designed for use as an [audit source](../concepts/Auditing-Packages.md#audit-sources) in environments where access to `api.nuget.org` is blocked at the network level.
60+
Because this endpoint doesn't provide package content, network administrators who block `api.nuget.org` to prevent package downloads might be willing to allow `data.nuget.org` if asked.

docs/reference/errors-and-warnings/NU1905.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ Any NuGet source implementing [NuGet's V3 server API can provide vulnerability d
2525
Any source defined in a NuGet.Config `<auditSources>` element is expected to provide this resource, and this warning is raised when it is not.
2626
You can check if your package source administrators have a setting to enable vulnerability data.
2727

28+
If your audit source is nuget.org and access to `api.nuget.org` is blocked on your network, consider asking the network administrator to allow `https://data.nuget.org/v3/index.json` and use it as your audit source instead.
29+
This endpoint only serves vulnerability data, not packages, so it might be allowed even when `api.nuget.org` is blocked.
30+
2831
If you would like to treat this warning as an error, to cause build failures when vulnerability checks could not be performed, you can add `<WarningAsError>$(WarningAsError);NU1905</WarningAsError>` to your project file.
2932
If you are using `TreatWarningsAsErrors` to cause all warnings to be treated as errors, you can add `<NoWarn>$(NoWarn);NU1905</NoWarn>` to your project file to suppress this warning message, or `<WarningsNotAsErrors>NU1905</WarningsNotAsErrors>` to prevent this warning from being treated as an error.
3033

docs/reference/nuget-config-file.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,11 @@ Audit sources support the same attributes as `packageSources` (`protocolVersion`
161161
</auditSources>
162162
```
163163

164+
> [!TIP]
165+
> nuget.org also provides `https://data.nuget.org/v3/index.json`, a service index that only contains vulnerability data and doesn't serve packages.
166+
> Network administrators who block `api.nuget.org` to prevent package downloads might be willing to allow `data.nuget.org` if asked.
167+
> For more information, see [audit sources](../concepts/Auditing-Packages.md#audit-sources).
168+
164169
### packageSourceCredentials
165170

166171
Stores usernames and passwords for sources, typically specified with the `-username` and `-password` switches with `nuget sources`. Passwords are encrypted by default unless the `-storepasswordincleartext` option is also used.

0 commit comments

Comments
 (0)