Setup npm Proxy with DevGuard Dependency Proxy
Supply chain attacks through npm are a growing threat. In 2025, attackers published malicious packages impersonating the popular TanStack library, targeting developers who mistyped the package name or were misled by search results. Incidents like this — where a single npm install can silently compromise a developer machine or CI environment — highlight why every package download should be screened before it executes on your systems.
The DevGuard dependency proxy sits between your developers and the public npm registry. Every package request is checked against the OSV dataset before it reaches your machine, blocking known malicious packages automatically.
- Registry URL:
<your-devguard-url>/api/v1/dependency-proxy/<secret>/npm
Replace <secret> with the dependency proxy secret of your organization, project or repository. The complete proxy URLs are shown in its Dependency Proxy Settings in DevGuard.
Configuration
Point npm at the DevGuard proxy by adding a registry entry to your .npmrc. This file can live at the project level (./.npmrc) to scope only that project, or at the user level (~/.npmrc) to apply globally.
Once set, all npm install and npm ci invocations route through DevGuard transparently. No changes to your package.json or CI scripts are required.
Set strict-ssl=false only for local testing against a self-signed certificate. Always use true in production.
On startup, the proxy blocks all requests until the malicious package database is fully loaded. This initialization period prevents cache poisoning. See Cache Management for details.
Testing
DevGuard ships a test package that is permanently flagged as malicious for all versions. Use it to verify the proxy is working before relying on it in production:
Run npm install. lodash installs successfully while fake-malicious-npm-package is rejected with a 403 Forbidden. If you see both results, your proxy is configured correctly.
npm audit and npm audit signatures keep working behind the proxy: DevGuard forwards the audit requests, the registry signing keys and the provenance attestations to the npm registry.
npm audit signatures prints Fetching verification keys using TUF failed. Fetching directly from <registry>. when run against the proxy. This is expected: npm first looks up the signing keys of the configured registry in the Sigstore TUF repository, which only contains the keys of public registries such as registry.npmjs.org. Therefore tuf cant be used to fetch the signatures. npm itself will fallback to fetch the keys from the proxy, which forwards the official keys of the npm registry, and verifies the signatures with them.
The same check as a script, installing each package separately so the failure of the malicious one is visible:
Testing version normalization (semver)
Semver equality is not textual: 1.0.0 and v1.0.0 denote the same version, and nothing requires a downloaded tarball's filename to repeat the exact spelling a rule was written against - so a proxy that string-compares versions instead of parsing them can be bypassed by a tarball whose filename uses a different, equivalent spelling of a flagged version.
DevGuard ships a second test package, fake-malicious-npm-package-versioned, flagged at the specific version v1.0.0 rather than for all versions, so it can prove version comparison itself is correct. The proxy checks a tarball download against the malicious package database before ever fetching it from upstream, so the file below does not need to exist for this check:
Testing a minimum release age rule
A minimum release age rule is configured per repository and only applies to requests using the repository's proxy URL, which contains a secret. To verify it, temporarily add a rule that denies everything released in the last 87600 hours (10 years). lodash@4.17.21 was published in February 2021, so the proxy must reject it, while a version range still resolves to an older version:
npm 11 has its own client-side minimum release age (min-release-age in .npmrc, in days). If it is set, npm hides recent versions itself and reports errors like No matching version found for lodash@4.17.21 with a date before … — independent of the proxy. The script passes --min-release-age=0 so that only the proxy decides which versions are available. Both settings can be combined in practice; the proxy enforces the minimum age centrally, even for clients that do not support or configure it.