Cybersecurity glossary
What is Dependency Confusion?
Learn what dependency confusion is, how public packages can override private names, real-world impact patterns, and defenses like namespaces, pinning, and registry controls.
Definition
Dependency confusion is a software supply-chain attack technique where an adversary publishes a public package that shares the name of an internal dependency, tricking build tools into installing the attacker-controlled package instead of the intended private one.
Why dependency confusion matters
Internal package names are often predictable: company-auth, payments-lib, mobile-core. If those names are resolvable from a public registry, attackers do not need to phish developers—they only need your installer to prefer the wrong feed.
Dependency confusion turns routine package resolution into a silent substitution attack that can execute during install scripts, tests, or runtime.
How the attack succeeds
Name collision
A public package reuses an internal dependency name that was never reserved externally.
Version bait
Attackers publish very high versions so naive resolvers treat them as newer.
Mixed registries
Clients search private and public sources without a strict internal-only policy.
Trust inheritance
Build systems install the substitute with the same trust as legitimate dependencies.
Typical dependency confusion sequence
Internal name exists
A private package is used widely across repos but is not claimed on public registries.
Attacker publishes collide
A malicious package with the same name appears on a public ecosystem registry.
Resolver prefers public/higher
CI or developer machines fetch the attacker package due to priority or version rules.
Payload runs
Install hooks or imported code exfiltrate tokens, implant backdoors, or poison builds.
Trust spreads
Compromised artifacts may be republished downstream if detection is slow.
Controls that stop confusion
| Control | What it does | Limit |
|---|---|---|
| Scoped / namespaced packages | Ties internal libs to an org scope you control | Requires ecosystem support and migration |
| Registry routing rules | Internal names resolve only to private feeds | Misconfiguration reopens public fallback |
| Public placeholder packages | Reserves names so attackers cannot claim them | Operational overhead for many packages |
| Allowlists + checksums | Blocks unexpected sources and digests in CI | Needs maintenance as deps evolve |
Dependency confusion defense checklist
- Inventory internal package names and verify they cannot be resolved publicly.
- Configure package managers to never fall back to public registries for private scopes.
- Prefer organization scopes/namespaces for all first-party libraries.
- Commit lockfiles and verify integrity hashes in CI.
- Block install scripts where your ecosystem allows safer alternatives.
- Alert on new public packages matching internal naming patterns.
- Use short-lived CI credentials so a confused install steals less.
- Educate developers not to publish or request unscoped internal names.
The practical takeaway
Dependency confusion exploits ambiguous package resolution between private and public registries. The attacker does not break cryptography—they win the name.
Claim your namespaces, pin sources, and make internal resolution impossible to override from the public internet. If your installer can be tricked by a higher version number alone, your supply chain is already negotiable.
Related security terms
Namespace Confusion
Closely related naming ambiguity across package namespaces and scopes.
Malicious Package
Attacker-published packages designed to execute harmful code on install or runtime.
Dependency Pinning
Locking versions and sources so installs cannot silently switch origins.
Package Repository
Where public and private packages are hosted and resolved.
Software Supply Chain Attack
The broader category of attacks abusing software delivery trust.
Frequently asked questions
What is dependency confusion in simple terms?
Your build expects a private library named acme-utils. An attacker publishes acme-utils on a public registry with a higher version. The installer grabs the public malware instead.
How is dependency confusion different from typosquatting?
Typosquatting mimics popular public names with misspellings. Dependency confusion targets exact internal names that were never claimed publicly.
Which ecosystems are affected?
Any system that can resolve both private and public feeds—npm, PyPI, NuGet, Maven, RubyGems, and others—when configuration prefers the wrong source.
Why do installers pick the malicious package?
Many clients choose the highest version across configured registries, or fall back to public registries when private lookup fails.
How do you prevent dependency confusion?
Use scoped namespaces, private-only resolution for internal names, claim public placeholders, pin exact sources, and block unexpected public substitutes in CI.
Are lockfiles enough?
They help for already-resolved graphs, but new dependency additions and misconfigured registry priority can still introduce confusion. Combine lockfiles with registry policy.
What should incident response look like after a hit?
Rotate secrets exposed to the build, audit installs of the confusing name, rebuild from known-good sources, and search for persistence left by install scripts.
References
Explore authoritative guidance and frameworks related to dependency confusion.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.