dependency-confusion

A supply-chain security playbook covering package-manager dependency confusion, where an internal package name also exists — or can be squatted — on a public registry. When a resolver can see both private and public indexes and version ranges allow it, a public release with a higher semver can win resolution, and the package manager's lifecycle scripts then execute attacker-controlled code on developer laptops, CI runners, or production image builds. Impact tends to be broad across many consumers and silent until a build or runtime hook fires.

It breaks down the confusion angle for each ecosystem — npm (scoped versus unscoped names and .npmrc registry mapping), pip (--extra-index-url merging indexes), RubyGems (source order), Maven (repository declaration order and mirrors), Composer (Packagist collisions), and Docker (image typosquatting). Reconnaissance guidance shows where internal names leak (committed manifests, JavaScript source maps, .npmrc and .pypirc, CI logs, and SBOM exports) and gives read-only claimability probes such as npm view, pip install --dry-run, and gem search --remote.

For authorized engagements it describes a non-destructive proof-of-concept pattern: register the name, publish a higher semver within the victim's declared range, and add a preinstall/postinstall or setup hook that makes a DNS/HTTP callback to a collaborator you control, avoiding data exfiltration or destructive writes. It references tooling (confused and DepFuzzer) and defensive controls — owned scoped packages with correct .npmrc mapping, exact version pinning with enforced lockfiles, avoiding careless --extra-index-url, and controlling repository order. Testing is restricted to systems and programs you are authorized to test.