Dependency Confusion Vs Dependency Substitution

📅 October 4, 2026  |  🏷 General  |  Cyber Security, Information Security, Threat Management

A single malicious package uploaded to a public registry brought down internal builds at dozens of Fortune 500 companies simultaneously — not through a zero-day exploit, but through a naming trick so elegant it bordered on artistry. That was the February 2021 Alex Birsan supply chain attack, which successfully breached Microsoft, Apple, Shopify, PayPal, Netflix, and Tesla by exploiting a fundamental flaw in how package managers resolve dependencies. Five years later, the attack surface has evolved, the terminology has matured, and the confusion between two critically distinct attack classes — dependency confusion and dependency substitution — continues to cost enterprises millions in breach costs and remediation overhead.

Understanding the precise distinction between these two attack vectors is not semantic pedantry. It is operationally critical. The defensive controls that neutralize one do almost nothing to protect against the other. Security teams that conflate them deploy the wrong mitigations, leaving visible gaps that sophisticated threat actors actively probe. This post draws a clean technical line between the two, examines real-world exploitation patterns, and provides a layered defensive architecture that addresses both attack classes simultaneously.

Defining the Attack Surface: How Software Supply Chains Became a Battleground

Modern enterprise applications are not monolithic constructs. They are assemblages — thousands of third-party packages, open-source libraries, and internal components stitched together by build pipelines that developers rarely scrutinize at depth. The average enterprise application now contains 528 open-source dependencies, according to Synopsys’s 2025 Open Source Security and Risk Analysis report. Each of those dependencies is a potential injection point for adversarial code.

Package managers like npm, PyPI, Maven, NuGet, and RubyGems were designed for developer convenience, not adversarial environments. Their resolution logic — the algorithm that decides which package gets installed when a name is requested — became the attack surface. Both dependency confusion and dependency substitution exploit this resolution logic, but they do so through fundamentally different mechanisms.

The Resolution Logic Vulnerability

Most enterprise environments operate a hybrid package architecture: a public registry (e.g., npmjs.com) and a private internal registry (e.g., Artifactory, Nexus, Azure Artifacts). When a developer requests a package named internal-auth-utils, the package manager must decide: internal registry first, or public registry first? In many default configurations, public registries take precedence when a higher version number is present. That single architectural assumption is the root cause of dependency confusion attacks.

Dependency Confusion: The Namespace Hijack

Dependency confusion is an unsolicited namespace collision attack. The attacker does not need to know your internal package names with certainty — though reconnaissance helps. The attack works by registering a package on a public registry using the same name as an internal package, then publishing it with an artificially inflated version number. When the build pipeline runs, the package manager sees a “newer” version on the public registry and pulls the malicious package instead of the trusted internal one.

Birsan’s 2021 demonstration was methodologically precise: he identified internal package names by examining package.json files in public GitHub repositories, npm scoped package errors in public CI/CD logs, and JavaScript bundle metadata. He then registered those package names on npmjs.com with version 9.9.9 — safely above any version number a legitimate internal package would use — embedded a harmless DNS ping-back payload, and waited. Within 48 hours, his payload executed inside build environments at 35 major organizations.

Attack Mechanics in Detail

The attack chain for dependency confusion follows a predictable sequence:

1. Reconnaissance: Identify internal package names through public code repositories, leaked CI/CD logs, JavaScript source maps, or error messages in publicly accessible interfaces.
2. Registration: Claim the same package name on the public registry. Because public registries are open to registration on a first-come, first-served basis, this requires no special access.
3. Version Inflation: Publish the malicious package with a version number significantly higher than any realistic internal version (e.g., 99.0.0).
4. Passive Wait: Build pipelines that lack proper registry scoping will automatically pull the public package on next dependency resolution.
5. Execution: Malicious code in postinstall scripts or the package entry point runs with the privileges of the build agent — often with broad access to source code, secrets, and cloud credentials.

The critical characteristic of dependency confusion: the attacker never touches the target’s internal systems or supply chain directly. The victim’s own tooling pulls the malicious package autonomously.

Dependency Substitution: The Deliberate Counterfeit

Where dependency confusion is opportunistic namespace squatting, dependency substitution is a targeted, surgical attack. Also called package substitution or typosquatting in its more common form, this class of attack involves replacing or impersonating a legitimate public dependency that your application genuinely uses with a malicious counterfeit.

The substitution can occur at multiple points in the supply chain:

• Typosquatting: Registering reqeusts instead of requests, or lodahs instead of lodash, to catch developer typing errors or automated scripts with misspelled package names.
• Dependency hijacking: Taking control of a legitimate package through account compromise, maintainer abandonment, or social engineering — and publishing a backdoored version under the original name.
• Mirror poisoning: Compromising a private registry that mirrors public packages, injecting malicious versions into the cached mirror.
• Dependency chain attacks: Compromising a transitive dependency — a package your direct dependency depends on — rather than attacking the direct dependency itself.

High-Profile Substitution Cases

The 2021 ua-parser-js incident illustrates dependency hijacking with precision. The npm package — downloaded 7 million times per week and used in projects maintained by Facebook, Microsoft, and Amazon — had its maintainer’s npm account compromised. Attackers published three malicious versions containing a cryptocurrency miner and a credential-stealing trojan. The malicious versions were live for approximately four hours before detection. That four-hour window was sufficient for the payload to execute across thousands of automated build pipelines worldwide.

In 2022, the PyPI “ctx” and “phpass” packages were hijacked through expired domain registration on maintainer email accounts. Attackers reset the npm/PyPI credentials using the expired domain, then published backdoored versions that exfiltrated AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to an attacker-controlled server. The attack required no vulnerability exploitation — only expired domains and lax account recovery policies on public registries.

The Critical Distinction: Why Your Defenses Cannot Be Identical

This is where security teams consistently make costly strategic errors. Dependency confusion and dependency substitution require structurally different mitigations, despite their surface similarity as “supply chain attacks.”

A team that deploys only lockfile pinning addresses substitution risk but remains exposed to confusion attacks if their registry routing is misconfigured. Conversely, a team that only implements namespace reservation on public registries does nothing to protect against a compromised transitive dependency.

The False Comfort of Lockfiles

Lockfiles (package-lock.json, Pipfile.lock, yarn.lock) are frequently cited as the solution to both attack classes. They are valuable — but not sufficient in isolation. Lockfiles pin specific package versions, but they do not inherently verify the content integrity of those versions. A compromised registry that serves a malicious package at a pinned version number will still deliver its payload to a build system relying solely on version locking. Cryptographic hash verification (integrity fields in npm lockfiles, --require-hashes in pip) must accompany version pinning for meaningful protection against substitution.

Layered Defensive Architecture: A Practitioner’s Framework

Effective defense against both attack classes requires a defense-in-depth approach across four operational layers: configuration hardening, artifact integrity verification, continuous software composition analysis, and behavioral detection at runtime.

Layer 1: Registry Scoping and Namespace Reservation

The most direct mitigation for dependency confusion is eliminating the ambiguity that enables it. Configure your package manager and private registry to enforce explicit registry routing:

• In npm, use scoped packages (e.g., @yourcompany/internal-auth-utils) and configure .npmrc with a scoped registry directive: @yourcompany:registry=https://your-private-registry.example.com. This ensures scoped packages are never resolved against the public registry.
• In Python/pip, configure --index-url to point to your private mirror and disable fallback to PyPI using --no-index for known-internal packages.
• Claim your internal package names on public registries as “dummy” packages. This is not about publishing functional code — it is about occupying the namespace so an attacker cannot. Several organizations publish empty packages with a clear warning message. This is a lightweight but highly effective control.
• Configure Artifactory or Nexus to use “virtual repository” aggregation with explicit priority ordering that places internal repositories above public proxies for all package resolution.

Layer 2: Integrity Verification and SBOM Generation

Software Bill of Materials (SBOM) generation — now mandated for U.S. federal contractors under Executive Order 14028 and its subsequent OMB guidance — provides the inventory foundation for integrity verification. Generate SBOMs in SPDX or CycloneDX format at build time, capturing cryptographic hashes (SHA-256 minimum) for every direct and transitive dependency.

Integrate hash verification into CI/CD pipelines using tools such as:

• Sigstore/Cosign for container image and artifact signing with transparency log verification
• in-toto attestations for supply chain provenance
• pip-audit and npm audit for known vulnerability scanning against advisory databases
• SLSA (Supply-chain Levels for Software Artifacts) framework compliance, targeting SLSA Level 3 for high-criticality build environments

According to the 2025 State of Software Supply Chain report by Sonatype, organizations that implemented automated SBOM generation with hash verification reduced mean time to detect supply chain compromises by 62% compared to those relying on advisory-feed-only scanning.

Layer 3: Runtime Behavioral Analysis

Static controls are necessary but insufficient. Malicious packages frequently execute their payloads in postinstall scripts — during the installation phase, before any static analysis tool has flagged the package as malicious. Runtime controls must therefore operate at the build agent level:

• Sandbox build environments using network egress controls. A legitimate dependency should not initiate outbound DNS or HTTP connections during installation. Monitoring for unexpected network activity during npm install or pip install is a high-fidelity detection signal.
• Deploy eBPF-based behavioral monitoring (tools like Falco or Tetragon) on build agents to detect anomalous syscall patterns: unexpected file reads targeting ~/.aws/credentials, /etc/passwd, or environment variable enumeration.
• Enforce ephemeral, immutable build environments. Each build runs in a fresh container with no persistent credentials. Even if a malicious package executes, it finds no long-lived secrets to exfiltrate.

Organizational and Governance Controls

Technical controls without governance frameworks degrade over time as configurations drift, exceptions accumulate, and new services are onboarded without security review. The 2024 Verizon Data Breach Investigations Report found that 15% of all breaches involved a supply chain component, up from 9% in 2022 — a trajectory driven largely by governance failures rather than technical control gaps.

Implementing a Dependency Security Policy

A formal dependency security policy should codify:

• Approved registry list: Define which registries build pipelines may resolve from. Any resolution from an unlisted registry triggers a build failure and security alert.
• Package approval workflow: New direct dependencies undergo security review — including maintainer reputation assessment, download velocity analysis, and code review of postinstall scripts — before being permitted in production builds.
• Namespace reservation schedule: Quarterly audit of internal package names against public registry availability. Any internal name available for public registration is immediately claimed.
• Incident response playbook: Documented procedures for responding to a suspected dependency compromise, including build pipeline isolation, forensic artifact preservation, and stakeholder communication chains.
• Developer training: Security awareness specific to supply chain risks, including how to verify package provenance before adding dependencies and how to recognize social engineering targeting open-source maintainers.

Key Takeaways

• Dependency confusion and dependency substitution are mechanistically distinct attacks requiring separate — though complementary — defensive controls. Conflating them produces dangerous coverage gaps.
• Registry scoping and public namespace reservation are the highest-leverage controls against dependency confusion and can be implemented in hours with minimal operational disruption.
• Cryptographic hash verification coupled with SBOM generation is the foundational control for dependency substitution defense — version pinning alone is insufficient against compromised registries.
• Runtime behavioral monitoring of build environments, particularly network egress analysis during package installation, provides detection capability that static analysis cannot replicate.
• Governance frameworks and developer education are force multipliers for
  

  ---

  💡 Enjoyed this article?

  Subscribe for more expert insights delivered to your inbox.

  Follow us or subscribe below xe2x80x94 free, no spam.