Menu

Individual skill

detecting-dependency-confusion

0upvotes

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.

skills/detecting-dependency-confusion/SKILL.md

Read pinned source

Source commit 54a798831d2266a3ca61ce68a7acb80b81160d57

What was checked

Matches the observed repository HEAD
Yes
Scanner rules are current
Yes
Repository scan complete
No
Skill scan complete
No
Observed behavior
Network or broad shell
Last checked
Nov 9, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings)
35,926
Repository last updated
Aug 31, 2026
License
Apache-2.0

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files
Read excerpt
# 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).
Back to top