Global configuration

.NET package consumption in a large organization is typically managed by a repository manager. The repository manager acts as a single point of access for developers and development tools to retrieve NuGet packages.

This page describes how to configure JFrog Artifactory and Sonatype Nexus Repository to proxy Chainguard Libraries for .NET. The instructions use Chainguard Repository’s built-in upstream fallback, which is the recommended configuration.

With upstream fallback enabled, configure Artifactory with a single remote repository that points to the Chainguard NuGet v3 service index: https://libraries.cgr.dev/dotnet/v3/index.json.

Chainguard Repository handles upstream fallback and policy enforcement. Artifactory handles local caching, access control, and the endpoint used by your NuGet clients. Do not add a direct nuget.org remote to the virtual repository used by your builds unless you intentionally want to manage fallback yourself.

Prerequisites

Before you begin, you need:

• An entitlement to Chainguard Libraries for .NET
• Administrator access to your repository manager instance
• A pull token for Chainguard Libraries for .NET

JFrog Artifactory

JFrog Artifactory supports NuGet repositories for proxying packages and virtual repositories for combining repositories behind a single endpoint.

The following configuration uses the recommended upstream-fallback approach. A remote repository that points directly to nuget.org can bypass Chainguard Repository protections. Because Artifactory resolves packages through a virtual repository, a misplaced or incorrectly ordered remote can result in an unprotected package being served without an obvious build error.

Initial configuration

Use the following steps to add Chainguard Libraries for .NET as an Artifactory remote repository:

1. Sign in to Artifactory as a user with administrator privileges.
2. Click Administration in the top navigation bar.
3. In the left navigation, click Repositories.
4. Click Create a Repository, then choose Remote.
5. Configure the remote repository with the following values:
   • Package type: NuGet
   • Repository key: dotnet-chainguard
   • URL: https://libraries.cgr.dev/dotnet/v3/index.json
   • Username: the username returned by chainctl
   • Password: the password returned by chainctl
6. Open the Advanced configuration tab and configure the following:
   • In the Network section, confirm that Lenient Host Authentication is unchecked. This prevents Artifactory from forwarding credentials across a redirect.
   • Optionally select Enable Cookie Management. JFrog recommends this for remote repositories that use redirects.
   • In the Others section, select Bypass HEAD Requests so that Artifactory retrieves package files with GET requests instead of probing with HEAD requests first.
   • In the Others section, uncheck Block Mismatching Mime Types.
   • Select Disable URL Normalization so that Artifactory does not rewrite a pre-signed redirect URL.
7. Click Create Remote Repository.

These settings are required because Chainguard Libraries stores artifacts behind redirects to pre-signed URLs. Without them, Artifactory may rewrite the redirect, forward credentials to the redirected host, or cache the redirect response instead of the NuGet package.

Create a virtual repository

Create a virtual repository to give NuGet clients a single access point:

1. Click Create a Repository, then choose Virtual.
2. Configure the virtual repository with the following values:
   • Package type: NuGet
   • Repository Key: dotnet-all
   • Repositories: add dotnet-chainguard
3. Click Create Virtual Repository.

For the recommended configuration, dotnet-chainguard should be the only external upstream in dotnet-all. You can also add approved internal NuGet repositories to the virtual repository according to your organization’s access-control requirements.

Validate the remote repository

Validate the Artifactory remote before configuring developer workstations or CI/CD systems. The Artifactory Test button is not a reliable indicator of a working Chainguard configuration; a remote can pass the test but still be misconfigured for package retrieval.

• Confirm that the remote repository URL is https://libraries.cgr.dev/dotnet/v3/index.json.
• Confirm that the remote uses the current .NET pull-token username and password. Confirm that the token is not expired and was copied correctly.
• Confirm that the Advanced configuration settings are applied.
• Clear any previously cached test content from dotnet-chainguard if the repository was configured with different settings.
• Create or use a test .NET project that references a package available from Chainguard Libraries.
• Configure the test project to use the Artifactory virtual repository, then clear the NuGet HTTP cache:

 dotnet nuget locals all --clear

• Force a network restore:

dotnet restore --force --no-cache --verbosity normal

• Inspect obj/project.assets.json. The sources entry must contain the Artifactory dotnet-all URL, and must not contain nuget.org.
• In Artifactory, confirm that the package is present in the dotnet-chainguard remote cache and that the request is available through the dotnet-all virtual repository.

Configure build tools

After validation, configure each workstation and build server that restores .NET dependencies, including CI/CD infrastructure, to use the Artifactory virtual repository.

In Artifactory, select the dotnet-all virtual repository and use Set Me Up or Generate Settings to obtain the URL and authentication instructions for your Artifactory version. The URL commonly has the following form: https://<artifactory-host>/artifactory/api/nuget/dotnet-all

See Configuring your build tool for more information.

Sonatype Nexus Repository

Sonatype Nexus Repository allows for merging multiple remote repositories as a repository group. The following instructions are based on the Nexus documentation for NuGet.

The recommended approach is to rely on Chainguard Repository’s upstream fallback, configuring a single proxy repository pointed at the Chainguard NuGet v3 service index rather than adding a separate nuget.org proxy. A proxy that points directly to nuget.org can bypass Chainguard Repository protections.

Initial configuration

The following steps create a proxy repository for Chainguard Libraries for .NET and a repository group that exposes it to your build tools.

First, log in to Sonatype Nexus as a user with administrator privileges and access the Server administration and configuration section with the gear icon in the top navigation bar.

Next, configure a proxy repository for the Chainguard Libraries for .NET repository:

1. Select Repository - Repositories in the left hand navigation.
2. Click Create repository.
3. Select the nuget (proxy) recipe.
4. Configure the following:
   • Name: dotnet-chainguard
   • Protocol Version: NuGet V3
   • Proxy - Remote storage: Add the URL https://libraries.cgr.dev/dotnet/v3/index.json.
   • HTTP - Authentication: Select Username as the Authentication type, and provide the username and password values as retrieved with chainctl.
5. Click Create repository.

Create a repository group, or add to an existing repository group:

1. Select Repository - Repositories in the left hand navigation.
2. Click Create repository.
3. Select the nuget (group) recipe.
4. Configure the following:
   • Name: dotnet-all
   • Under Group - Member repositories, move the new repository dotnet-chainguard to the right to include it in the group. Position dotnet-chainguard at the top of the list using the arrow controls.

In a typical configuration, the Chainguard repository is placed first so that packages are retrieved through Chainguard when available. If you are manually managing fallback, you can configure an additional nuget.org proxy repository and add it to the group after dotnet-chainguard.

Build tool access

NuGet v3 clients access a Nexus group through its service index, which commonly has the form https://repo.example.com/repository/dotnet-all/index.json (with repo.example.com replaced with the hostname of your repository manager).

See Configuring your build tool for information on setting the package source and authenticating to your repository manager.