Get the free coreGet core

Dependency confusion: how a public package replaces your private one

Updated 6 min readSection 05 / Threats
SHORT ANSWER

Dependency confusion is an attack where a package manager installs an attacker's public package in place of a private one with the same name. An index is a server that hands out packages. pip looks in the public one, PyPI, and in any extra index you add, treats them equally, and takes the best version, so a public package with a high version number can win. npm can be hit too. First step: look up each private name without a scope on the public registry with npm view <name> --registry=https://registry.npmjs.org/; if it answers with package data, that name is taken in public. The fix is to bind each private name to a single source.

Your company, or your own project, may have an internal package that is not on the public registries. If the install command can look in a public place for the same name, someone else can put a package there first. Dependency confusion is that gap. This page shows how the attack runs, what the original research did and how to close it.

01What dependency confusion means

A package manager is the tool that downloads libraries for your project: npm for JavaScript, pip for Python. A registry or index is the server it downloads from. Most projects use the public one, and some also use a private one for internal code.

Dependency confusion is the case where the manager, asked for an internal name, gets a public package with that name instead. The attacker needs no access to your systems. They only need to know the name and publish under it.

02How the attack works

The usual sequence, as the original research ran it:

1. Your project depends on a private package, say "acme-billing".
2. The name exists only on your private registry.
3. The attacker finds the name and publishes "acme-billing" on a public registry, with a high version number.
4. Your install looks in more than one place and picks the best version.
5. The attacker's package is installed.

Step 4 depends on the client, as the next section shows.

03Why pip and npm behave differently

ClientHow it picks a source
pipSearches PyPI and any extra locations given with --find-links or --extra-index-url, with no priority; the best version wins
pip option --index-urlSets the base URL of the package index
pip option --extra-index-urlAdds more indexes to search
npmSends each name to exactly one registry

pip pools every configured source by design. With an extra index set, a public package and a private package of the same name compete on version.

npm sends each name to exactly one registry, but that does not make it safe: the research published same-named packages to npm, and the code got distributed automatically into companies' internal applications. What matters is which registry your private names go to. If it is the public one, a public package with that name is what installs.

Scopes help here. A scope lets you create a package with the same name as another user's package without conflict. Every user or organization is given a scope that matches its name, so a name under your scope is tied to your account or organization.

04The original research

In February 2021 the security researcher Alex Birsan named the attack and demonstrated it. He breached over 35 major companies' internal systems and earned well over $130,000 in bug bounties. A bug bounty is a payment a company makes to someone who reports a flaw.

He first needed the names of internal packages. He found them in manifest files, the files that list what a project depends on, in companies' public GitHub repositories and on their content delivery networks, which are servers that distribute files to users. He looked for names that did not exist in any public registry. He also took names from package.json contents that build tools had embedded in companies' public JavaScript bundles, the packed files a website sends to browsers.

He then published same-named packages to npm, PyPI and RubyGems with high version numbers, and had them report back over DNS, the internet's address lookup system. The test packages carried a disclaimer that they were security research and contained no useful code. An attacker would not add one.

05How to check if you are exposed

  1. List your private names. Write down the packages that only your private registry serves. Include the ones listed in manifest files that are public, such as a package.json in an open repository, because that is where names were found.
  2. Look each name up publicly. For each name without a scope, run npm view with the name. It shows data about a package and prints it to the terminal. The --registry option sets the registry npm asks, so this asks the public one, not your private registry:
npm view <your-private-package-name> --registry=https://registry.npmjs.org/

Put your package name where the placeholder is, with no angle brackets. If npm shows package data rather than a not-found error, a public package with your name exists. Do the same on the PyPI website for Python names.

  1. Read your install settings. For pip, look for --extra-index-url and --find-links in the command you run, because with them pip searches several places with no priority. For npm, check which registry each private name goes to.
  2. Read the lockfile diff. A lockfile (package-lock.json for npm) describes the exact tree of packages that was installed, and npm audit needs it. A version that jumped, or a private name that now resolves somewhere new, needs an answer.

06How to close the gap

The core rule: bind each private name to a single source, then scan what still gets through. In practice:

npm config set @myco:registry=https://your-private-registry.example.com

Replace @myco and the address with your own. After that, installs of @myco/… packages ask only that registry.

07Where this meets other name attacks

Dependency confusion does not need a typo and does not need a model. It needs a private name that leaks and a client that looks in too many places. The lookalike version is typosquatting, and the version that starts from an AI model's invented name is slopsquatting. The wider picture is on npm supply chain attack, the checks before an install are on check an npm package for malware, and Python is on PyPI malware. If a package already ran on your Mac, start from npm malware.

08The rule to remember

Each private name comes from a single source, and the install tool is not allowed to look anywhere else for it. Check your names once, set scopes and index settings, then watch the lockfile. That is how you keep dependency confusion out of your projects.

If you want to see when a package script or a new program starts on your Mac, the free, open-source core of Artificial Immunity watches program starts and reports what it finds.

FAQ

What is dependency confusion?

It is an attack where a package manager installs an attacker's public package in place of a private package with the same name.

Does pip prefer the private index?

No. pip searches PyPI and any extra locations you give it through --find-links or --extra-index-url, and there is no priority among them. Some clients, pip among them, pool every source and pick the best version.

Does npm have the same problem?

It can. The research published same-named packages to npm as well. npm sends each name to exactly one registry, so the question is which registry that is for your private names: if it is the public one, a public package with that name is what you get. Check each private name without a scope against the public registry with npm view <name> --registry=https://registry.npmjs.org/ to see whether a public package already uses it.

What is an npm scope?

A scope lets you publish a package with the same name as another user's package without conflict. Every user and organization gets a scope that matches its name, so a name under your scope is tied to you.

How do I find out if my private package name exists publicly?

Run npm view with the name and --registry=https://registry.npmjs.org/, so the question goes to the public npm registry. It shows data about a package. If it shows package data rather than a not-found error, someone has published that name there.

What is the main fix?

Bind each private name to a single source, then scan what still gets through.

Sources

  1. Socket glossary, dependency confusion
  2. BleepingComputer, researcher hacks over 35 tech firms
  3. pip docs, pip install
  4. npm docs, about scopes
  5. npm docs, npm view
  6. npm docs, verifying registry signatures
  7. npm docs, npm audit
  8. Artificial Immunity
Packages come from many places. Artificial Immunity watches the Mac where your agents work.Get the free core