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
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
| Technique ID | Technique Name | Relevance |
|---|
| T1195.001 | Supply Chain Compromise: Compromise Software Dependencies and Development Tools | Core technique — attacker substitutes a malicious public package for an internal dependency. |
| T1195.002 | Supply Chain Compromise: Compromise Software Supply Chain | Broader category covering the compromised build artifacts produced once confusion succeeds. |
| T1059.007 | Command and Scripting Interpreter: JavaScript | npm preinstall/postinstall lifecycle scripts execute attacker JavaScript on resolution. |
| T1071.001 | Application Layer Protocol: Web Protocols | Substituted package beacons stolen environment/credentials to attacker HTTP(S) endpoint. |
Workflow
1. Inventory manifests across the codebase
Locate every dependency manifest so nothing is missed.
find . -type f \( \
-name package.json -o \
-name requirements.txt -o \
-name pom.xml -o \
-name composer.json -o \
-name Gemfile.lock \
\) -not -path '*/node_modules/*' -print
2. Scan npm manifests with confused
confused reads the manifest and reports every dependency name not found on the public registry — those are candidates for confusion.
confused -l npm package.json
confused -l npm -s '@acme/*,@acme-internal/*' package.json
confused -l npm -v package.json
3. Scan PyPI, Maven, Composer, and RubyGems manifests
The -l flag selects the ecosystem; each maps to its standard manifest file.
confused -l pip requirements.txt
confused -l mvn pom.xml
confused -l composer composer.json
confused -l rubygems Gemfile.lock
4. Cross-check with OWASP dep-scan private-namespace mode
dep-scan confirms confusion exposure for declared private namespaces and folds it into a broader risk audit.
depscan --src $PWD --reports-dir ./reports \
--private-ns acme,acme_internal,@acme
depscan --src $PWD --reports-dir ./reports --risk-audit
5. Triage candidates and confirm claimability
For each flagged name, verify it is genuinely absent on the public registry (a 404 means claimable).
curl -s -o /dev/null -w "%{http_code}\n" https://registry.npmjs.org/@acme%2finternal-utils
curl -s -o /dev/null -w "%{http_code}\n" https://pypi.org/pypi/acme-billing-sdk/json
6. Remediate npm with scope-to-registry pinning
Bind every internal scope to the private registry so a public package of the same name can never be resolved.
@acme:registry=https://artifactory.example.com/api/npm/npm-internal/
//artifactory.example.com/api/npm/npm-internal/:_authToken=${NPM_TOKEN}
registry=https://artifactory.example.com/api/npm/npm-virtual/
Verify the resolution source before installing:
npm config get @acme:registry
npm install --dry-run
7. Remediate PyPI and Maven
Pin Python index resolution and Maven mirroring so public sources cannot shadow internal artifacts.
[tool.pip]
index-url = "https://artifactory.example.com/api/pypi/pypi-internal/simple/"
<mirrors>
<mirror>
<id>internal-virtual</id>
<mirrorOf>*</mirrorOf>
<url>https://artifactory.example.com/artifactory/maven-virtual</url>
</mirror>
</mirrors>
8. Defensively register placeholder packages
For names you cannot fully isolate, claim the public name yourself with an empty, non-functional placeholder so an attacker cannot.
mkdir acme-internal-utils && cd acme-internal-utils
npm init -y
npm pkg set version=0.0.1-placeholder description="Reserved internal name. Do not use."
npm publish --access public
9. Wire detection into CI
Fail the pipeline if any new confusable dependency appears.
name: dependency-confusion
on: [push, pull_request]
jobs:
confused:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with: { go-version: '1.22' }
- run: go install github.com/visma-prodsec/confused@latest
- name: Scan npm manifest
run: $(go env GOPATH)/bin/confused -l npm -s '@acme/*' package.json
10. Run the bundled helper for batch triage
Use the included agent.py to scan a tree and emit a structured report combining confused and live registry probes.
python scripts/agent.py --path . --ecosystem npm \
--secure-namespaces '@acme/*,@acme-internal/*' \
--output report.json
Tools and Resources
Validation Criteria
