Category: Software Supply Chain

Dependency Confusion

Also known as: dependency confusion attack, namespace confusion attack

Simply put

Dependency confusion is a type of software supply chain attack in which an attacker publishes a malicious package to a public registry using the same name as a private, internal package used by a target organization. When a package manager fetches dependencies, it may retrieve the attacker's public package instead of the intended private one, causing malicious code to be executed in the target environment. The attack exploits how certain package managers resolve naming conflicts between public and private registries.

Formal definition

A dependency confusion attack exploits the dependency resolution logic of package managers (such as npm, pip, or RubyGems) that, when configured to check both public and private registries, may preferentially fetch a package from the public registry if it exists there with a matching or higher version number than the internally hosted equivalent. An attacker identifies a private package name used by a target organization (typically via disclosed build artifacts, job postings, or source code) and registers a package with the same name on a public registry, often with an artificially high version number to maximize the likelihood of selection. If the victim's build environment resolves the public package before the private one, the malicious payload is pulled and executed during the build or install process. This attack is a subset of software supply chain security concerns focused on component integrity, and is distinct from typosquatting in that it uses an exact name match rather than a visually similar one.

Why it matters

Dependency confusion attacks are significant because they exploit a trusted, automated process: dependency resolution during software builds. When package managers silently fetch a malicious public package in place of a legitimate internal one, the malicious code executes in a privileged build environment, often with access to secrets, credentials, and internal infrastructure. This makes the attack particularly dangerous because it requires no direct compromise of the target organization's source code or infrastructure. The attacker merely needs to register a package on a public registry.

In 2021, security researcher Alex Birsan demonstrated the viability of dependency confusion at scale by successfully executing proof-of-concept attacks against major technology companies including Apple, Microsoft, and others, receiving significant bug bounty payouts. This disclosure drew widespread industry attention to the attack class and prompted many organizations to audit their package manager configurations and private registry setups.

The attack is difficult to detect through conventional means. Static analysis of an application's declared dependencies may not flag the issue, because the package name itself appears legitimate in configuration files. The confusion exists at the resolution layer, meaning detection typically requires runtime or build-time controls such as registry pinning, version verification, or integrity checks, rather than code review alone.

Who it's relevant to

Software Engineers and Developers

Developers who work with internal or private packages are directly exposed to this attack, particularly if their build environments are configured to resolve dependencies from both public and private registries without explicit precedence rules. Understanding how their package manager resolves naming conflicts, and verifying that private package names are not publicly discoverable, are relevant defensive considerations.

DevOps and Build Infrastructure Engineers

Engineers responsible for CI/CD pipelines and build environments are a critical line of defense against dependency confusion. Misconfigured package manager settings that allow public registries to override private ones are typically the proximate cause of successful attacks. Controls such as registry scoping, allowlisting, and pinning specific package versions with integrity hashes are typically implemented at this layer.

Application Security Engineers

AppSec teams assessing software supply chain risk need to account for dependency confusion as a distinct attack class, separate from typosquatting or direct dependency compromise. Standard static analysis of source code and dependency manifests may not surface this vulnerability, since the package names in configuration files appear correct. Effective detection typically requires auditing registry resolution configurations and monitoring for unexpected public registrations of internally used package names.

Security Operations and Threat Intelligence Teams

Teams responsible for monitoring the threat landscape should track public registries for packages whose names match internal naming conventions used by their organization. Proactive registration of internal package names on public registries, where policy permits, is one mitigation strategy. Threat intelligence on newly published packages that match internal namespaces can provide early warning of a potential targeting attempt.

Open Source and Third-Party Risk Managers

Organizations that assess third-party and open source component risk should treat dependency confusion as part of a broader software supply chain security program. Unlike vulnerabilities in a known dependency, dependency confusion exploits the resolution process itself, meaning conventional software composition analysis tools may not detect it without specific configuration to inspect registry resolution behavior and private package namespace exposure.

Inside Dependency Confusion

Namespace Collision

The condition in which an internal package name exists in both a private repository and a public registry, creating ambiguity that a misconfigured package manager may resolve in favor of the public source.

Version Precedence Exploitation

The technique of publishing a public package with a higher version number than the internal counterpart, exploiting package manager resolution logic that typically selects the highest available version when multiple sources are configured.

Typosquatting Distinction

The categorical difference between dependency confusion, which uses the exact internal package name, and typosquatting, which relies on names that visually resemble legitimate packages. Dependency confusion does not require the attacker to guess or approximate a name.

Package Manager Resolution Order

The configured or default sequence in which a package manager queries repositories when resolving a dependency. Misconfiguration of this order is the proximate technical cause of dependency confusion attacks.

Malicious Payload Delivery

The attacker-controlled code embedded in the fraudulent public package, which executes in the build, CI/CD, or runtime environment of the victim when the package is installed. Common payloads include scripts that exfiltrate environment variables or system metadata.

Internal Package Name Exposure

The precondition in which private or internal package names become discoverable by an attacker, typically through leaked package manifests, public repositories, error messages, or disclosed build artifacts.

Private Registry Bypass

The outcome in which the intended authoritative private source for an internal package is circumvented because the package manager fetches from a public registry instead, without explicit configuration preventing that behavior.

Common questions

Answers to the questions practitioners most commonly ask about Dependency Confusion.

Does using a private package registry automatically protect against dependency confusion attacks?

Not necessarily. Using a private registry reduces exposure but does not eliminate the risk on its own. If the package manager is configured to check public registries in addition to the private one, and if public registries take precedence or are checked as a fallback, an attacker can still publish a malicious package under the same name with a higher version number. Protection requires explicit configuration to ensure the private registry is given strict priority or that public registry access is blocked for internally named packages.

Is dependency confusion only a risk for packages that are publicly exposed or used in open source projects?

No. Internal or proprietary packages that are never intended for public distribution are frequently the targets of dependency confusion attacks. The attack specifically exploits the gap between a package's internal name and its absence on public registries. Packages used only within a private codebase can be just as vulnerable, or more so, because their names may never have been registered on public registries, leaving that namespace available for an attacker to claim.

How can an organization detect whether any of its internal package names are already claimable on public registries?

Organizations can audit their internal package manifests to extract all dependency names and then query public registries such as npm, PyPI, or RubyGems to determine whether those names are already registered. Names that are absent from public registries represent potential targets. Some software composition analysis tools and supply chain security platforms include automated checks for this condition as part of their scanning capabilities.

What configuration changes should be made to package managers to mitigate dependency confusion risk?

The specific steps vary by ecosystem, but common mitigations include configuring package managers to use scoped package names that are unlikely to conflict with public registry entries, setting the private registry as the sole or authoritative source for internal packages, using allowlists or blocklists to restrict which registries are consulted for specific package names, and disabling automatic fallback to public registries when a package is not found privately. Lock files that pin exact versions and checksums also reduce the window for substitution attacks.

Should organizations proactively register their internal package names on public registries as a defensive measure?

Reserving internal package names on public registries is a commonly recommended defensive tactic, sometimes called namespace squatting for defensive purposes. By publishing placeholder or stub packages under the internal names, an organization prevents attackers from claiming those names. However, this approach requires ongoing maintenance, may not be feasible at scale for organizations with many internal packages, and does not address all variants of the attack. It is typically used as one layer within a broader supply chain security strategy rather than as a standalone control.

Does a software composition analysis scan detect dependency confusion vulnerabilities in a codebase?

Software composition analysis tools vary in their coverage of dependency confusion scenarios. Some tools can flag packages that appear in a manifest but are absent from expected private registries, or that have suspicious version discrepancies between private and public sources. However, traditional SCA tools primarily analyze known vulnerability databases and license metadata, and may not specifically check for namespace availability on public registries or registry priority misconfigurations. Organizations should verify whether their SCA tooling includes explicit dependency confusion detection or whether a separate supply chain security control is needed to cover that scenario.

Common misconceptions

Dependency confusion only affects organizations that have misconfigured their package managers in an obvious way.

Many package managers query public registries by default or alongside private ones, and the default behavior of popular tools in multi-source configurations has historically favored the highest version regardless of source. Organizations with seemingly standard configurations have been affected.

Using a private registry is sufficient protection against dependency confusion.

A private registry alone does not prevent the attack if the package manager is also configured to query public registries and lacks explicit rules that restrict internal package names to the private source. Scoping, namespace reservation, and registry priority controls are required in addition to hosting packages privately.

Dependency confusion requires the attacker to have prior knowledge of the target organization's internal tooling or source code.

Internal package names are frequently exposed through public-facing artifacts such as open-source repositories, published npm lock files, error logs, or build scripts. Attackers can opportunistically discover candidate names without targeted reconnaissance.

Best practices

Configure package managers to use a single private registry that proxies or mirrors approved public packages, rather than querying both private and public registries in parallel, to eliminate ambiguous resolution paths.

Reserve or claim internal package names in relevant public registries as inert placeholder packages, preventing an attacker from publishing a malicious package under that name even if the internal name becomes known.

Apply namespace scoping where the package ecosystem supports it (such as npm organization scopes) and enforce that scoped internal packages are only resolved from the private registry through explicit registry mapping configuration.

Audit all package manifests, lock files, and build scripts before they are published or shared publicly to identify and redact internal package names that could serve as targets for dependency confusion attacks.

Integrate integrity verification into the build pipeline by pinning dependencies to specific, verified checksums or digests, so that a substituted package of any version will fail validation before execution.

Periodically scan the build environment and CI/CD pipeline logs for unexpected package sources or resolution events that indicate a dependency was fetched from an unintended registry, treating such events as security incidents.