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

3. RECONNAISSANCE

Where internal names leak

• Committed package.json, requirements.txt, Gemfile, pom.xml, composer.json in repos or forks.
• JavaScript source maps, bundled assets, or error stack traces referencing package paths.
• .npmrc, .pypirc, CI logs showing install URLs or mirror endpoints.
• Issue trackers, gist snippets, and dependency graphs from SBOM exports.

Check public squatting / claimability (read-only)

# npm — metadata for a name (unscoped)
npm view some-internal-package-name version
 
# npm — scoped (requires scope to exist / be readable)
npm view @some-scope/internal-lib versions

Routing note: after package-name enumeration, consider PoC only in authorized environments; public registry lookups themselves are usually passive recon.

4. EXPLOITATION

Authorized testing pattern

1. Register (or use a controlled namespace) the same package name on the public registry your target resolver can reach.
2. Publish a higher semver than the legitimate internal line within the victim’s declared range (e.g. ^1.0.0 → publish 9.9.9).
3. Add lifecycle hooks that prove execution without harming hosts—prefer DNS/HTTP callback to a collaborator you control, no destructive writes.

npm package.json — minimal callback-style PoC (illustrative)

npm package.json — shell + curl fallback (illustrative)

pip — setup hook pattern (illustrative; use only in authorized lab packages)

Reference implementation (study / lab): community PoC layout and workflow similar to 0xsapra/dependency-confusion-exploit — automate version bump, publish, and callback confirmation only where you have written permission.

5. TOOLS

Run these only against your manifests or authorized engagements; do not use to squat names for unrelated third parties.

6. DEFENSE

• npm: Prefer scoped packages (@org-scope/pkg) with org-owned scopes; set .npmrc so private scopes map to private registry and default registry is not accidentally public for internal names.
• Pinning: Exact versions + lockfiles (package-lock.json, poetry.lock, Gemfile.lock, composer.lock) enforced in CI.
• pip: Avoid careless --extra-index-url; prefer single private index with mirroring, or explicit --index-url policies in CI.
• Maven / Gradle: Control repository order, use internal mirrors, and block unexpected groupIds on release pipelines.
• Composer: Use repositories with canonical: true for private packages; verify Packagist is not introducing unexpected vendors.
• Defensive registration: Reserve internal names on public registries (squat your own names) where policy allows.
• Monitoring: Tools such as Socket.dev, Snyk, or similar SBOM/supply-chain scanners to alert on new publishers or version jumps for critical packages.

7. DECISION TREE

Related routing

• From recon-for-sec: When doing supply-chain reconnaissance, cross-link leaked manifests and internal package identifiers with the checks in Section 3 and the decision tree in Section 7 before proposing any publish/PoC steps.