Package restore is a security decision made thousands of times in a large .NET build. NuGet normally searches every configured source for a package. If a public feed and a private feed can both supply the same package ID, the result depends on source order and content rather than an explicit policy. Package Source Mapping lets a project state which source may satisfy each package pattern.

How source selection becomes a trust issue

Microsoft describes Package Source Mapping as a supply-chain control for projects that mix public and private feeds. With mapping enabled, NuGet filters the configured sources per package during restore, install, and update. The mapping is written under packageSourceMapping, with a source key and one or more package patterns beneath it.

The important design point is that the repository owns the rule. A machine-level feed can be convenient, but a mapping that exists only on one developer laptop does not protect CI or another workstation. Keep the authoritative mapping in the repository-level NuGet.config, then use <clear /> where inherited sources or mappings should not leak into the build.

<packageSourceMapping>
  <clear />
  <packageSource key="company-private">
    <package pattern="Company.*" />
    <package pattern="Internal.Project.*" />
  </packageSource>
  <packageSource key="nuget.org">
    <package pattern="Microsoft.*" />
    <package pattern="System.*" />
  </packageSource>
</packageSourceMapping>

The exact patterns must match the organization's namespace. A broad public fallback can recreate the ambiguity the mapping was meant to remove. Transitive packages also need coverage. Microsoft's guidance recommends listing transitive dependencies, for example with dotnet list package --include-transitive, before freezing the source map.

Test the failure path

A mapping is only useful if an unexpected source selection fails the build. Introduce a test package ID that exists only in the private feed, then verify a clean restore on a runner that has both feeds configured. Repeat with a package that should come from the public feed. Review warnings and the effective configuration, not just the final obj directory.

The control has a documented gap. Microsoft states that Package Source Mapping currently applies to package downloads during restore, install, and update. Some metadata operations, including dotnet package add, dotnet list package, and Package Manager UI browse and update lookups, still send package IDs to all configured sources at the time of the documentation. Teams that treat package names or internal identifiers as confidential should account for that behavior separately.

Operational checks

Store feed credentials in a secret system rather than in a repository file. Review who can publish to the private feed, because source mapping selects an endpoint but does not prove that its contents are trustworthy. Pair the mapping with package signing or trusted signer policy, lock files, vulnerability review, and a controlled process for adding new package prefixes.

During incident response, export the effective NuGet configuration from the exact build environment. Compare source keys, patterns, inherited files, and environment-specific overrides. Then inspect restored package hashes and provenance. The mapping is a useful allowlist for source selection, not a replacement for artifact identity.

References