Migrating a .NET project to Chainguard Libraries

Chainguard Libraries for .NET provides a registry of NuGet packages that have been scanned for malware and are subject to configurable policies. Switching an existing project requires only a registry configuration change – no changes to your application code or dependency versions.

This guide walks through migrating an existing .NET project to Chainguard Libraries, covering the two most common setups:

• Direct access: Your build tool connects directly to libraries.cgr.dev. This option is faster for initial evaluation and smaller-scale setups.
• Repository manager: Your build tool connects to a repository manager, which proxies requests to Chainguard Libraries. This option is recommended for teams and organizations.

Prerequisites

Before getting started, you need:

• A .NET project with a .csproj file
• The .NET SDK
  • If you are using macOS, install the .NET SDK with Homebrew: brew install --cask dotnet-sdk
• chainctl installed and authenticated
• An entitlement to Chainguard Libraries for .NET
• A pull token for Chainguard Libraries for .NET

Create an entitlement

To create an entitlement to Chainguard Libraries for .NET, run:

chainctl libraries entitlements create --ecosystems=DOTNET

You do not need to manually enable upstream fallback for .NET; the entitlement for .NET automatically includes Chainguard protections for upstream artifacts.

You can also configure a cooldown policy after you create the entitlement. For example, to create and enforce a policy for a 14-day cooldown:

chainctl libraries policy create --name=dotnet-cooldown-14d --cooldown-days=14
chainctl libraries policy enable dotnet-cooldown-14d --ecosystem=DOTNET --mode=ENFORCE

It can take up to 30 minutes for configured policies to take effect. Learn more about cooldown and other policies in the Libraries policies documentation.

Create a pull token

Create a pull token for the .NET repository:

chainctl auth pull-token --repository=dotnet --ttl=8670h

The command returns a username and password. Use these values to authenticate NuGet to Chainguard Libraries.

Note: Do not commit the credentials to source control. Keep nuget.config out of the repository when it contains literal credentials, or generate it at build time from secrets stored in your CI/CD system. For shared environments, use a dedicated machine identity or service account instead of a personal token when available.

Step 1: Configure authentication and registry

Choose the setup that matches your organization. With direct access, your build tool connects to libraries.cgr.dev. With a repository manager, your build tool connects to a proxy that you configure to fetch from Chainguard Libraries.

dotnet nuget list source

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="chainguard" value="https://libraries.cgr.dev/dotnet/v3/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <chainguard>
      <add key="Username" value="REPLACE WITH USERNAME FROM pull-token" />
      <add key="ClearTextPassword" value="REPLACE WITH PASSWORD FROM pull-token" />
    </chainguard>
  </packageSourceCredentials>
</configuration>

dotnet nuget list source

Registered Sources:
  1.  chainguard [Enabled]
      https://libraries.cgr.dev/dotnet/v3/index.json

dotnet new nugetconfig

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="organization" value="https://repo.example.com/nuget/dotnet" />
  </packageSources>
  <packageSourceCredentials>
    <organization>
      <add key="Username" value="REPLACE WITH REPOSITORY MANAGER USERNAME" />
      <add key="ClearTextPassword" value="REPLACE WITH REPOSITORY MANAGER PASSWORD" />
    </organization>
  </packageSourceCredentials>
</configuration>

dotnet nuget list source

Registered Sources:
  1.  organization [Enabled]
      https://repo.example.com/nuget/dotnet

Step 2: Clear caches, restore, and build

Because packages have previously been served from upstream, you must clear the NuGet HTTP cache and restore:

dotnet nuget locals http-cache --clear
dotnet restore --force --no-cache --verbosity normal

The output should include requests to the Chainguard endpoint. If you configured access through a repository manager, the output shows your repository manager URL instead. If the URL or credentials are incorrect, restore fails instead of using a cached package. Common errors include NU1301, NU1101, and HTTP 401 responses.

After restoring, build your project:

dotnet build

Step 3: Verify your libraries

Inspect the project assets file to confirm that your project is using Chainguard Libraries:

dotnet nuget list source

The expected output includes the Chainguard endpoint:

      "sources": {
        "https://libraries.cgr.dev/dotnet/v3/index.json": {}

If you configured access through a repository manager, the sources entry shows your repository manager URL instead of libraries.cgr.dev, and must not contain nuget.org.