Detecting Dependency Confusion

Legal Notice: This skill is for authorized security testing, defensive engineering, and educational purposes only. Registering or claiming package namespaces you do not own, or testing build pipelines without written authorization, may be illegal and may violate the terms of service of public registries. Only run namespace-claiming or resolution-testing activities against names and infrastructure you control or are explicitly authorized to assess.

Overview

Dependency confusion (also called a substitution or namespace-shadowing attack) was popularized by Alex Birsan in 2021 when he forced malicious code into the internal build systems of Apple, Microsoft, PayPal, and dozens of others. The root cause is that many package managers, when configured to resolve from both an internal/private registry and a public one, will prefer whichever copy has the higher version number rather than honoring the source. An attacker who learns the name of a private package (@acme/internal-utils, acme-billing-sdk) can publish a malicious package of the same name to the public registry (npmjs.com, PyPI, Maven Central) with a very high version (e.g. 99.0.0). When the victim's CI/CD runner or a developer machine resolves dependencies, it pulls the attacker's public package, executes its install scripts, and the supply chain is compromised.

This skill covers both halves of the problem: detection — enumerating internal package names that are not registered (squatted defensively) on public registries and are therefore claimable, using confused and OWASP dep-scan — and prevention — pinning scopes/namespaces to private registries, registering placeholder packages, and enforcing source restrictions in .npmrc, pip.conf/pyproject.toml, and Maven settings.xml. Internal package names leak constantly: in committed lockfiles, sourcemaps, public JS bundles, Docker layers, and error stack traces, so this is treated as an attack-surface management problem, not a one-time check.

When to Use

• When onboarding a repository or organization to a supply-chain security program and you need to baseline which internal packages are claimable on public registries.
• When CI/CD pipelines resolve dependencies from both private and public registries (mixed/hybrid feeds).
• After any incident where internal package names may have been exposed (leaked source, public bundle, breached repo).
• When auditing package.json, requirements.txt, pom.xml, composer.json, or Gemfile.lock files for confusable dependencies.
• As a recurring scheduled control to detect newly added internal packages that have not yet been defensively registered.

Prerequisites

• Go 1.20+ to install confused:

  go install github.com/visma-prodsec/confused@latest
  # binary lands in $(go env GOPATH)/bin/confused
  

• Python 3.10+ for OWASP dep-scan:

  pip install owasp-depscan
  # or container: docker pull ghcr.io/owasp-dep-scan/dep-scan
  

• Node.js + npm (for .npmrc and npm config remediation) and access to your private registry (Artifactory, Nexus, Azure Artifacts, GitHub Packages, AWS CodeArtifact).
• Read access to the repositories / lockfiles being assessed and write access to your private registry for defensive registration.

Objectives

• Enumerate every internal dependency declared in project manifests across npm, PyPI, Maven, Composer, and RubyGems.
• Determine which internal names are not present on the corresponding public registry and are therefore claimable.
• Distinguish true exposure from false positives (scoped packages, already-mirrored names).
• Apply registry-pinning and scope-restriction controls that make public substitution impossible.
• Defensively register placeholder packages for unclaimed internal names.
• Establish a recurring detection control in CI to catch newly introduced confusable dependencies.

MITRE ATT&CK Mapping

…