Stop dependency confusion and typosquatting at install time

Dependency confusion is a resolution bug, not a code bug. When your build asks for a package by name, the installer looks for that name across every source it knows and then picks a "best" candidate, usually the highest version. If the same name also exists on a public registry, and nothing tells the installer that this name is private, the public copy can win. An attacker who learns an internal package name (from a leaked manifest, an error message, a public fork or a job posting) publishes that name on npmjs.com or PyPI with a very high version number and waits for a build to pull it. MITRE files this under CWE-427, Uncontrolled Search Path Element, whose alternate term is literally "dependency confusion" or "substitution attack."

Typosquatting is the related trick aimed at the human rather than the resolver: the attacker registers a name one keystroke from a real one (crossenv for cross-env, or a hyphen/underscore swap) and waits for a mistype. The 2017 crossenv packages wrapped the real module so installs looked normal while the install script shipped environment variables to the attacker. Slopsquatting is the newest variant and aims at AI coding assistants: models invent plausible but non-existent package names, and an attacker pre-registers them. A 2025 study generated 576,000 code samples across 16 models and found 19.7% of recommended packages did not exist, with 205,474 unique hallucinated names, many of them repeatable enough to squat profitably.

All three share one fix shape. Decide in advance exactly which name may come from which source, install only the bytes you reviewed, and give yourself time and a human gate before brand-new code runs on a build machine. The rest of this guide is that shape, per ecosystem, with the current flags.

The strongest npm control is a scoped name bound to a registry. Publish internal packages under an organization scope such as @acme, and in a committed .npmrc map @acme to your private registry while leaving the default registry public. A scope you own cannot be claimed by anyone else on the public registry, so @acme/ledger simply does not exist there to confuse the resolver. Keep the auth token in an environment variable rather than in the file. The unscoped case is weaker: a bare name like acme-ledger lives in the same namespace as the public registry, so if your private registry is reached through a repository-manager group that also proxies the public one, the higher public version can still win. Prefer scopes for anything internal.

pnpm reads the same .npmrc registry mapping. Both npm 12 and pnpm v10+ also changed a dangerous default: dependency install scripts no longer run automatically. In npm 12 the install skips preinstall/install/postinstall for any dependency not listed in the package.json allowScripts field, prints the blocked packages, and lets you approve or deny them; pnpm 11 and later fail the install (strictDepBuilds defaults to true since v11) until you list trusted packages in allowBuilds. That matters here because the first thing a malicious package wants is code execution at install time, before you ever import it; /domains/supply-chain/dependencies/package-attack-response/ covers the response when one already ran.

; .npmrc at the repository root, committed with the code
@acme:registry=https://npm.acme.example/
//npm.acme.example/:_authToken=${NPM_TOKEN}
registry=https://registry.npmjs.org/
min-release-age=3
min-release-age-exclude=@acme/*

Treat the install-script allowlist as a reviewed artifact. Run the install once, read what npm blocked, and approve only packages whose build step you understand (native modules such as those with a binding.gyp are the common legitimate case). An approval written by npm install-scripts approve is pinned to the exact version you reviewed, for example "@acme/native@2.0.0": true; a denial is name-only, for example "acme-telemetry": false, so it holds for every future version. In CI, add --strict-allow-scripts so an unreviewed script fails the build loudly instead of being skipped with a warning. The pre-12 escape hatch --ignore-scripts still works for a blunt "run nothing" policy.

npm 12 also flipped allow-git and allow-remote to none, so a transitive git: or tarball-URL dependency no longer resolves unless you opt in; tarballs on the configured registry's own host still install. That removes a common way for a malicious transitive edge to pull code from outside the registry entirely.

# npm 12: dependency install scripts are skipped, then listed at the end.
npm install
npm install-scripts ls                      # what was blocked, and the command it wanted to run
npm install-scripts approve @acme/native    # writes "@acme/native@2.0.0": true to allowScripts
npm install-scripts deny acme-telemetry     # writes "acme-telemetry": false
npm rebuild                                 # runs the scripts that are now approved

pip has no notion of index priority. It searches --index-url and every --extra-index-url together and installs the highest compatible version, wherever it lives. That is exactly how the 2022 PyTorch nightly compromise worked: a package named torchtriton on PyPI shadowed the one on PyTorch's own index because "the PyPI index takes precedence." So do not use --extra-index-url to reach a private index for internal names. Point --index-url at a single private index that proxies or mirrors PyPI, and resolve everything through it, so there is one ordered source and no merge step.

uv is safer by default: its first-index strategy only considers the first index that contains a given name, so an internal package found on your index is never also fetched from PyPI. Pin a package to a named index with [tool.uv.index] marked explicit = true plus a [tool.uv.sources] entry, and uv will refuse to take that name from anywhere else. Avoid the unsafe-best-match strategy, which restores pip-style merging and reintroduces the confusion risk.

# Vulnerable: pip merges candidates from both indexes and installs the
# highest version it can find. A public "acme-billing 99.0.0" beats the
# internal 1.4.2, so the attacker's package wins.
pip install --index-url https://pypi.acme.example/simple \
    --extra-index-url https://pypi.org/simple \
    acme-billing

The fixed uv configuration below binds acme-billing to an internal index and marks that index explicit, so no other package drifts onto it and acme-billing is never resolved from PyPI. This is the uv analogue of an npm scope map: the name and its source are decided in the project file, not by whichever index happens to answer first.

For the classic pip workflow, keep the same discipline with requirements and constraints files that pin exact versions, and lean on hash checking (next section) so the resolved bytes are fixed even if an index is swapped.

# pyproject.toml: acme-billing may come only from the internal index.
# "explicit = true" keeps every other package off that index, and the
# tool.uv.sources pin keeps acme-billing off PyPI.
[[tool.uv.index]]
name = "acme"
url = "https://pypi.acme.example/simple"
explicit = true

[tool.uv.sources]
acme-billing = { index = "acme" }

Pinning a version range is not enough, because the same version can be served as different bytes by a different source. Pin the bytes. npm ci installs strictly from package-lock.json and fails with an integrity error if a downloaded tarball does not match the recorded sha512; it also refuses to run if the lockfile and package.json disagree. For pip, hash-checking mode (--require-hashes) requires every requirement to be pinned with == and requires a hash for every dependency, transitive ones included, so an unpinned or unexpected package is rejected before download. Add --only-binary :all: when you want to refuse source distributions, which run arbitrary code at build time.

Go one step further in CI and check the source, not just the hash. The lockfile records where each package came from, so a short jq (or equivalent) check can fail the build when any internal name resolves from a public host. The snippet below combines strict install, hash-checked pip, and a host allowlist over the npm lockfile. It catches the case where someone's local install quietly repointed a dependency at an unexpected registry.

# CI: install exactly what the lockfiles record, or fail.
npm ci --strict-allow-scripts
pip install --require-hashes --only-binary :all: -r requirements.txt

# Fail the build if any npm package resolves from a host that is not one of
# the two approved registries.
bad=$(jq -r '.packages | to_entries[]
  | select(.value.resolved and (.value.resolved
      | test("^https://(npm\\.acme\\.example|registry\\.npmjs\\.org)/") | not))
  | "\(.key) \(.value.resolved)"' package-lock.json)
[ -z "$bad" ] || { printf 'Unexpected package source:\n%s\n' "$bad"; exit 1; }

Most malicious versions are caught and pulled within hours to days. A release-age cooldown turns that window to your advantage by refusing to install a version until it has existed for a few days. npm has min-release-age (a day count in .npmrc, added in 11.10.0) with min-release-age-exclude for packages you control; pnpm has minimumReleaseAge (minutes; default 1440 since v11) with minimumReleaseAgeExclude; Yarn has npmMinimalAgeGate; bun has minimumReleaseAge in bunfig.toml. Exclude your own internal scope so your freshly published internal versions are not delayed. The four hours in 2021 when ua-parser-js served malware (/domains/supply-chain/dependencies/case-study-event-stream/) are the kind of window a cooldown closes.

If a bot opens your dependency updates, set the cooldown there too. Renovate ships a security:minimumReleaseAgeNpm preset that waits three days (it also notes npm's own 72-hour unpublish window), and in 2026 Dependabot made a three-day cooldown the default for version updates while still opening security updates immediately. A cooldown is a delay, not a scanner, so keep it alongside hashes and an allowlist rather than in place of them.

# pnpm-workspace.yaml (pnpm 11 or later)
minimumReleaseAge: 4320        # minutes (3 days); the default since v11 is 1440
minimumReleaseAgeExclude:
  - '@acme/*'                  # internal packages are not delayed
allowBuilds:
  '@acme/native': true         # only this dependency may run a build script
strictDepBuilds: true          # the default: an unreviewed build script fails the install

The JVM and .NET ecosystems have the same resolution model and the same fix. For Maven, route everything through one repository manager with a settings.xml mirror whose mirrorOf is *, and configure the manager so your internal groupId (com.acme) is served only from the hosted repository and never proxied to Central. With a single mirror, a repository declared inside a project POM is not even contacted. Maven's resolver also supports remote repository filtering (prefix and groupId filters under the local repository's .remoteRepositoryFilters directory) to assert which groupIds a given remote may answer for. Gradle expresses the same intent with exclusiveContent, which ties a group to one repository so Gradle searches nowhere else for it. Reserving your groupId on Maven Central (via DNS TXT verification, or the io.github.<user> namespace) stops anyone else publishing under it.

For NuGet, packageSourceMapping makes the mapping explicit and strict: map Acme.* to your private feed and * to nuget.org, and every package, including transitive ones, must match a pattern or restore fails with NU1101 instead of silently falling back. Start the config with <clear /> so no inherited source sneaks in, and set a repository-local globalPackagesFolder so a package cached earlier from another source is not reused. Reserve your ID prefix on nuget.org so the public registry rejects a look-alike under Acme.*. The two snippets below are a working settings.xml mirror and a NuGet config; the Gradle exclusiveContent form is in the exercise.

<!-- ~/.m2/settings.xml, or the file your CI passes with -s -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
  <mirrors>
    <mirror>
      <id>acme-repo-manager</id>
      <name>All repository traffic goes through the repository manager</name>
      <url>https://maven.acme.example/repository/all/</url>
      <mirrorOf>*</mirrorOf>
    </mirror>
  </mirrors>
</settings>

This nuget.config restricts Acme.* to the private feed and sends everything else to nuget.org. Because mapping is enforced during restore, an attacker's Acme.Billing 99.0.0 on nuget.org is never considered: the pattern says that name comes from the acme source only. If the private feed does not have it, restore fails rather than reaching for the public copy, which is the behaviour you want. Package source mapping does not yet cover every metadata command (for example dotnet list package --outdated still queries all sources), so treat it as a resolution control, not a secrecy guarantee for the name.

Across every ecosystem the artifact-repository layer (Artifactory priority resolution, Nexus routing rules, or the exclude-pattern approach) is where you enforce this centrally: a routing or priority rule says an internal namespace is served only from the hosted repository and is never requested from an upstream proxy, so the internal name never leaks to the public index and a public look-alike is never fetched.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <config>
    <!-- Repo-local cache: a package cached earlier from another source is
         not silently reused when a mapping would send it elsewhere. -->
    <add key="globalPackagesFolder" value=".nuget/packages" />
  </config>
  <packageSources>
    <clear />
    <add key="acme" value="https://nuget.acme.example/v3/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="acme">
      <package pattern="Acme.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

The controls above assume the name you asked for is the name you meant. Typosquatting and slopsquatting break that assumption. For human error, lean on lockfiles and the cooldown, let your SCA tool flag low-reputation packages, and let OpenSSF Scorecard's Pinned-Dependencies check flag unpinned build dependencies. For AI-suggested code, add one habit: before you add a package a model recommended, confirm it actually exists, is the one you intended, and has a plausible history (age, downloads, repository, maintainers); /domains/ai-emerging/agent-security/ai-assisted-development/ includes a check that blocks names that do not exist or are too new. OWASP's LLM Top 10 for 2026 treats registering hallucinated names as a supply-chain vector under LLM04. A cheap gate is to run installs with a cooldown and a curated allowlist so a brand-new, never-before-seen name cannot be pulled on the first build that mentions it.

None of these controls is sufficient alone. Scope or source mapping decides where a name may come from; a lockfile with hashes fixes the bytes; disabled install scripts remove the install-time execution path; a cooldown buys detection time; name verification covers the human and the model. Deploy them together and dependency confusion stops being a single missing flag away. In the OpenSSF S2C2F, binding names to sources is requirement ENF-1 at Level 2 and enforcing a curated feed is ENF-2 at Level 3; /domains/supply-chain/dependencies/s2c2f-adoption/ places them in a staged plan.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. MITRE CWE-427: Uncontrolled Search Path Element (dependency confusion alternate term). CWE 4.20.
2. OWASP Top 10:2025 A03 Software Supply Chain Failures
3. OWASP ASVS 5.0 V15 Secure Coding and Architecture (15.2.4 dependency confusion). Version 5.0.0.
4. npm docs: npm install-scripts and the allowScripts policy (npm 12). npm v12.
5. npm CLI CHANGELOG: v12.0.0 breaking changes (install scripts, allow-git/allow-remote). 12.0.0 entry (8 July 2026).
6. pip docs: pip install (index options) and secure installs (hash-checking mode). pip 26.2.1.
7. uv docs: package indexes and index strategy
8. pnpm docs: dependency-resolution (minimumReleaseAge, trustPolicy) and build settings
9. NuGet docs: package source mapping
10. Spracklen et al., package hallucination study (arXiv 2406.10279, USENIX Security 2025). v3 (March 2025).
11. OWASP Top 10 CI/CD Security Risks: CICD-SEC-3 Dependency Chain Abuse. v1.0 (2022).
12. CISA, NSA and ODNI (Enduring Security Framework): Securing the Software Supply Chain, Recommended Practices Guide for Developers, section 2.3 Verify Third-Party Components. August 2022.

Reference information

Tags

Dependency managementSupply chain attacksAI-assisted developmentJavaScript and Node.jsPython

SDLC phase

Development

Role

DevelopersAppSec engineersPlatform engineers and SREs

ASVS 5.0.0 requirements

v5.0.0-15.2.4 · v5.0.0-15.1.2

CAPEC attack patterns

• CAPEC-471 at MITRE
• CAPEC-538 at MITRE

Download this guide as Markdown

Continue exploring