detecting-dependency-confusion

name	detecting-dependency-confusion
description	Detect and prevent dependency confusion (public-over-private package name resolution) in npm, PyPI, and Maven by enumerating claimable internal package names with tools like `confused` and OWASP `dep-scan`, then enforcing source restrictions via `.npmrc`, `pip.conf`/`pyproject.toml`, and Maven `settings.xml`. Use when onboarding a repo to a supply-chain security program, auditing lockfiles/manifests for confusable dependencies, or after an incident that may have leaked internal package names.
domain	cybersecurity
subdomain	supply-chain-security
tags	["supply-chain-security","dependency-confusion","npm","pypi","maven","package-management","devsecops","namespace-hijacking"]
version	1.0
author	mahipal
license	Apache-2.0
nist_csf	["ID.RA-09"]
mitre_attack	["T1195.001"]

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, , , or files for confusable dependencies.