Dependency confusion: when a public package shadows a private one

If a build can pull from public and private registries, a public package with your internal name and a higher version may win. How resolution goes wrong in npm, pip, and NuGet, and how scopes and single-source mirrors prevent it.

Lesson 17 of 26 · 10 min read · practice only with authorization

Diagram

How the wrong package wins

Follow the path. One example at a time.

Step 1 of 4

Internal

Your private registry hosts acme-utils 1.4.0.

Illustration: Internal
# Internal
# Your private registry hosts acme-utils 1.4.0.

The example on the open step is one illustration, or the fix you can paste into an application you own.

What this page is made of

3 pieces. Each one says what fails, who is affected, what you would notice, and what you change.

  1. Mixed sources

    What fails
    Clients that consult multiple registries can pick public over private.
    Who is affected
    Every build using the internal name.
    What you would notice
    --extra-index-url, multiple npm registries, or NuGet sources without mapping.
    What you change
    Use one proxying index or explicit source mapping.
  2. Unscoped names

    What fails
    Internal npm packages without a scope can be claimed publicly.
    Who is affected
    Projects depending on them.
    What you would notice
    Internal package names that are free on npmjs.com.
    What you change
    Use a scope you own and register it publicly.
  3. Detection

    What fails
    Builds that suddenly pull a huge version jump.
    Who is affected
    Build hosts and their secrets.
    What you would notice
    Lockfile diffs jumping to 99.x versions.
    What you change
    Review lockfile diffs and alert on new public sources.

Checking your exposure

List internal package names, then check whether each name exists on the public registry. Any that do not exist should be reserved or moved under a scope you own.

$ for p in acme-utils acme-auth acme-logger; do printf "%s " "$p"; npm view "$p" version 2>/dev/null || echo "(not on npmjs.com)"; done
acme-utils (not on npmjs.com)
acme-auth 0.0.1-security
acme-logger (not on npmjs.com)

Check yourself

Recognition and the fix. Nothing here is a procedure.

1 / 3

pip used --extra-index-url and installed a public 99.0.0 of an internal name. Why?

Sibling techniques

Pages at the same depth, plus a lab and a glossary card for this one.

  1. MapBuild pipelines and the software supply chainThe build is an environment with production rights.
  1. 01Pull requests from outside the trust boundaryCode from a fork or an untrusted branch is not your code yet.
  2. 02Software supply-chain compromise: where builds get tampered withSupply-chain attacks target the path from source to shipped artifact: repositories, dependencies, build systems, and registries.
  3. 03Typosquatted packages: one wrong letter in an install commandTyposquats copy popular package names with small changes to catch mistyped installs.

Practice

  1. LabTerminal mission: Version 99 of an internal packageA build installed an internal Python package from the public index instead of the company one. Read pip.conf, the requirements, and the install log to see how and why.

Glossary

  1. CardDependency confusionA package manager pulls a public package whose name matches a private one, and the install runs that code.