Dependency Confusion
Run authorized dependency-confusion reviews on manifests and CI so public registries cannot override private package names during install.
Overview
Dependency Confusion is an agent skill most often used in Ship (also Build integrations, Operate infra) that guides authorized supply-chain testing when private package names may resolve to malicious public registry vers
Install
npx skills add https://github.com/yaklang/hack-skills --skill dependency-confusionWhat is this skill?
- Ecosystem playbooks for npm, pip, gem, Maven, Composer, and Docker manifest review
- Recon mental model: internal names, public squats, and semver winning over private feeds
- CI and lockfile drift signals when installs are not pinned to private metadata
- Non-destructive PoC patterns emphasizing callbacks instead of data exfiltration
- Defensive controls paired with authorized red-team supply-chain methodology
- Covers npm, pip, gem, Maven, Composer, and Docker manifest review contexts
Adoption & trust: 1.1k installs on skills.sh; 980 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You rely on private package names in manifests but cannot prove whether public registries or loose version ranges could win installs in CI or developer machines.
Who is it for?
Builders running permitted security reviews on npm/pip/gem/Maven/Composer/Docker pipelines where internal naming conventions might leak to public registries.
Skip if: Unauthorized testing, casual dependency bumps without a security program, or teams with no private packages and fully pinned public-only lockfiles.
When should I use this skill?
Supply-chain testing via package-manager dependency confusion on authorized systems: npm/pip/gem/Maven/Composer/Docker manifest review and red-team supply-chain exercises.
What do I get? / Deliverables
After the skill runs, you have ecosystem-specific recon steps, PoC patterns, and defensive controls documented for manifests and pipelines you are authorized to assess.
- Manifest and lockfile findings on internal name exposure
- Documented PoC and defensive control recommendations
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Supply-chain hijacks surface at release and ops boundaries, but manifest review belongs in Ship security before production installs trust the resolver. The playbook targets attacker-controlled package resolution—an application security and supply-chain control problem, not routine feature coding.
Where it fits
Review a new npm scope and internal codename dependencies before merging a feature branch manifest.
Assess whether CI install jobs can pull a higher semver from a public index than your private feed publishes.
Validate Docker and Maven repository order in build agents after migrating artifact hosting.
How it compares
Methodology for resolver abuse and registry precedence—not a generic vulnerability scanner or license compliance bot.
Common Questions / FAQ
Who is dependency-confusion for?
Solo and indie builders doing authorized appsec or red-team supply-chain work, plus small teams reviewing manifests and CI before trusting install scripts.
When should I use dependency-confusion?
In Ship security audits, during Build when reviewing new package names in manifests, and in Operate when validating CI lock enforcement and private registry locks before deploy.
Is dependency-confusion safe to install?
The skill describes offensive testing patterns that must only run on authorized programs; review the Security Audits panel on this Prism page and your legal scope before invoking it.
SKILL.md
READMESKILL.md - Dependency Confusion
# SKILL: Dependency Confusion — Supply Chain Attack Playbook > **AI LOAD INSTRUCTION**: Expert dependency-confusion methodology. Covers how private package names leak, how public registries can win version resolution, ecosystem-specific pitfalls (npm scopes, pip extra indexes, Maven repo order), recon commands, non-destructive PoC patterns (callbacks, not data exfil), and defensive controls. Pair with supply-chain recon workflows when manifests or CI caches are in scope. **Only use on systems and programs you are authorized to test.** ## 0. QUICK START **What to look for first** - **Manifests** listing package names that look **internal** (short unscoped names, org-specific tokens, product codenames) without a **hard-private registry lock**. - Evidence the **same name** might exist—or be **squattable**—on a **public** registry with a **higher semver** than the private feed publishes. - **Lockfiles** missing, stale, or not enforced in CI so `install`/`build` can drift toward public metadata. **Fast mental model**: *If the resolver can see both private and public indexes, and version ranges allow it, the “newest” matching version may be the attacker’s.* Routing note: if the task comes from supply-chain, repository exposure, or CI-build recon, first use `recon-for-sec` to list internal package names and possible public-registry collisions. --- ## 1. CORE CONCEPT 1. **Private packages**: An organization ships libraries only on an internal registry (or under conventions that imply “ours”), e.g. a scoped name like `@org-scope/internal-utils` or an **unscoped** name such as `acme-billing-sdk`. 2. **Attacker squats the name**: The same package name is published on a **public** registry (npmjs, PyPI, RubyGems, etc.). 3. **Resolver preference**: Many setups resolve **highest matching version** across **all configured indexes** (or merge metadata), so a public `9.9.9` can beat a private `1.2.3` if ranges allow. 4. **Execution**: Package managers run **lifecycle scripts** (npm `preinstall`/`postinstall`, setuptools entry points, etc.) → **attacker code runs** on developer laptops, CI, or production image builds. This is a **supply-chain** class issue: impact is often **broad** (many consumers) and **silent** until build or runtime hooks fire. --- ## 2. AFFECTED ECOSYSTEMS | Ecosystem | Typical manifest | Confusion angle | |-----------|------------------|-----------------| | **npm** | `package.json` | **Scoped** packages (`@scope/pkg`) are **safer** when the scope is **owned** on the registry; **unscoped** private-style names are **high risk**. Multiple registries / `.npmrc` `registry` vs per-scope `@scope:registry=` misconfiguration increases risk. | | **pip** | `requirements.txt`, `pyproject.toml`, `setup.py` | `pip install -i` / **`--extra-index-url`** merges indexes; a public index can serve a **higher version** for the same distribution name. | | **RubyGems** | `Gemfile` | **`source`** order and additional sources; ambiguous gem names reachable from rubygems.org. | | **Maven** | `pom.xml` | **Repository** declaration **order** and **mirror** settings; a public repo publishing the same `groupId:artifactId` under a higher version can win if policy allows. | | **Composer** | `composer.json` | **Packagist** is default; private packages without **`repositories`**/`canonical` discipline may collide with public names. | | **Docker** | `FROM`, image tags | **Typosquatting** on container registries (e.g. public hub) for images with names similar to internal base images. | --- ## 3. RECONNAISSANCE **Where internal names leak** - Committed **`package.json`**, **`requirements.txt`**,