Articles / SECURITY

Dependency confusion and NuGet package source mapping

How an attacker can get their package installed instead of your internal one, why it works, and the NuGet feature that closes the gap.

SecuritySupply Chain.NET
Table of contents
  1. Context
  2. The attack
  3. Package source mapping
  4. Reserve the prefix
  5. Lock files
  6. Other ecosystems
  7. Checking what you already have
  8. Conclusion
  9. References

Most supply chain attacks need a victim to do something wrong: install a typo-squatted package, trust a compromised maintainer. Dependency confusion needs none of that. It exploits a configuration that looks completely normal.

This post explains why it works and what NuGet gives us to stop it.

Context

A typical company has two kinds of packages. Public ones come from nuget.org. Internal ones, such as Contoso.Billing.Client, come from a private feed.

Both feeds are configured in the same NuGet.config, and the restore process asks all of them.

Nothing about the internal package name is secret in practice. It leaks through build logs, public repositories that reference it, stack traces, assembly names in shipped binaries, and error messages.

The attack

The attacker registers the same package ID on nuget.org, with a very high version number.

From that point, whether the build picks the internal package or the attacker's depends on how the version range is written and how the client chooses among sources. NuGet queries every configured source, and when the same ID exists in more than one, there is no guarantee that the private one wins. With floating versions, such as 1.*, the highest version is selected, and the highest version is exactly what the attacker controls.

The package's install scripts and build targets then run on a build agent with access to secrets and deployment credentials.

Alex Birsan's 2021 research demonstrated this against dozens of large companies, across npm, PyPI and RubyGems. NuGet has the same shape of problem.

Package source mapping

NuGet's answer is to make the mapping explicit. Instead of "ask every source", you declare which source is allowed to provide which package IDs:

xml
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso-private" value="https://pkgs.contoso.example/nuget/v3/index.json" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="contoso-private">
      <package pattern="Contoso.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

When a package ID matches more than one pattern, the most specific pattern wins. Contoso.Billing.Client matches Contoso.* and *, and the longer prefix takes it. NuGet will only look at the private feed for it, and the attacker's package on nuget.org is never considered.

Two details are easy to forget:

  • <clear /> matters. Without it, machine-wide or user-level sources can still be consulted.
  • Source mapping is only as good as your naming discipline. A consistent prefix, such as Contoso., makes the whole rule one line.

Reserve the prefix

Mapping protects your builds. It does not stop an attacker from publishing Contoso.Whatever on nuget.org, which can still confuse a developer who is adding a package by hand.

nuget.org supports ID prefix reservation. Once your prefix is reserved, only your owners can publish packages that start with it, and the packages show a reserved indicator. It costs nothing and removes the squatting option entirely.

Lock files

Source mapping decides where packages may come from. A lock file decides which exact packages a build may use.

xml
<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

In CI, restore in locked mode:

bash
dotnet restore --locked-mode

Now a restore fails if the resolved graph differs from the committed lock file, and the lock file records content hashes. A surprise version bump from an unexpected source stops being silent and becomes a failing build.

Other ecosystems

The same ambiguity exists wherever one client can read from more than one registry.

  • npm resolves by name across whatever registries are configured, so internal packages should live under a scope, such as @contoso/billing, and that scope should be mapped to the private registry in .npmrc. Reserving the scope on the public registry removes the squatting option.
  • pip is the hardest case, since --extra-index-url merges the indexes and picks the highest version. Prefer a single index that proxies the public one, instead of two.
  • Maven and Gradle resolve in repository order, so listing the private repository first, and restricting which groups each repository may serve, achieves the same effect as source mapping.

Checking what you already have

Before changing anything, find out whether you are exposed today. List the package IDs your private feed serves, and search the public registry for each of them. Any name that already exists publicly under a different owner is either a coincidence or a warning, and both deserve a look at the build history of the feed. Doing it periodically is cheap, and it catches the new names that teams publish every month.

Conclusion

Dependency confusion is not about a clever exploit. It is about an ambiguity: two sources, one namespace, and a client that has to guess.

The fix is to remove the guess. Declare who owns which names, reserve what you own, and lock what you resolve. None of these steps is difficult, and together they remove a class of attack that otherwise relies on nothing more than a public package registry and a leaked name.

References