Workflow · Opinione
Perché fissare ogni dipendenza a una versione esatta, soprattutto con gli agenti
npm scrive ^ davanti a ogni dipendenza nuova, e un range accetta versioni che nessuno ha ancora visto. eslint-scope 3.7.2 e debug 4.4.2 erano patch malevole che un range accettava. Con un agente che installa pacchetti da solo, la versione esatta è il modo più semplice di vedere cosa entra.
Quando scrivi npm install astro, npm salva in package.json qualcosa come "astro": "^5.4.0". Quel ^ non l’hai scelto tu: è il valore di default di save-prefix, e per node-semver ^1.2.3 significa >=1.2.3 <2.0.0-0, cioè ogni minor e ogni patch che verrà pubblicata. L’8 settembre 2025 l’account npm del maintainer di debug è stato preso con un phishing ed è uscita la 4.4.2: secondo l’advisory GitHub, “funzionalmente identica” alla patch precedente, più un payload che dirottava transazioni di criptovalute nel browser. Per qualunque range ^4.x era un aggiornamento legittimo. Secondo me in un’applicazione ogni dipendenza diretta va fissata a una versione esatta, e quando un agente aggiunge pacchetti da solo diventa una questione di sicurezza.
Cosa accetta davvero un range
Le regole sono nel README di node-semver, la libreria che npm usa per risolvere le versioni. Il caret “permette modifiche che non toccano il primo elemento diverso da zero” della tupla [major, minor, patch]; la tilde permette solo patch se la minor è indicata:
^1.2.3 := >=1.2.3 <2.0.0-0
^0.2.3 := >=0.2.3 <0.3.0-0
~1.2.3 := >=1.2.3 <1.3.0-0
La tilde sembra prudente, ma la release malevola tipica è proprio una patch, come debug 4.4.2 ed eslint-scope 3.7.2, e un ~ le accetta quanto un ^. Il default di save-exact è false; secondo la documentazione di npm, con il flag attivo le dipendenze vengono salvate “con una versione esatta invece di usare l’operatore di range di default di npm”.
Cosa il lockfile non copre
L’obiezione più comune è che c’è package-lock.json. Secondo la documentazione npm il lockfile “descrive l’albero esatto che è stato generato”, così che le installazioni successive producano alberi identici. La pagina di npm install però precisa le condizioni: se le versioni del lock soddisfano i range di package.json, vince il lock; se non li soddisfano, npm risolve versioni nuove e riscrive il lock. “package.json è la fonte di verità per i range accettabili.”
Il lock quindi non decide la versione quando aggiungi un pacchetto: npm install <nome> installa, “nella maggior parte dei casi”, quella con il tag latest in quel momento. Non la decide nemmeno quando il lock viene rigenerato, per esempio perché qualcuno lo cancella per risolvere un conflitto, né con npm update, che si muove liberamente dentro i range. In CI c’è già npm ci: richiede un lock, esce con errore se lock e package.json non coincidono e “non scrive mai su package.json né sui lock: le installazioni sono di fatto congelate”. Quei tre casi però succedono prima che il lock arrivi in CI, quindi npm ci non li vede.
Le release che un range ha accettato
Gli incidenti documentati dai diretti interessati hanno la stessa forma: una versione nuova, compatibile per semver, pubblicata da qualcuno che non era il maintainer.
- eslint-scope 3.7.2, 12 luglio 2018. Secondo il postmortem di ESLint è rimasta sul registro dalle 10:40 alle 12:37 UTC; un
postinstallscaricava codice da pastebin e inviava all’attaccante il.npmrcdell’utente, che “tipicamente contiene token di accesso”. La causa: password riusata, nessuna 2FA. Tra le raccomandazioni finali: usare un lockfile “per evitare l’installazione automatica di pacchetti nuovi” ed essere cauti con i servizi che fanno auto-merge degli aggiornamenti. - event-stream 3.3.6, settembre-novembre 2018. Secondo il blog di npm un nuovo maintainer, ottenuto con social engineering, ha aggiunto la dipendenza
flatmap-stream0.1.1, che cercava chiavi private nei portafogli Copay. - ua-parser-js 0.7.29, 0.8.0 e 1.0.0, 22 ottobre 2021. L’advisory GHSA-pjwm-rvh2-c87w dice che ogni computer con il pacchetto installato “va considerato completamente compromesso”. Il maintainer se n’è accorto perché la sua casella email si è riempita di spam.
- debug 4.4.2 e chalk 5.6.1, 8 settembre 2025, parte dello stesso furto di account secondo il tracking issue del maintainer di
debug. npm ha rimosso le versioni nel corso della giornata; il 13 settembre sono uscite patch pulite per svuotare le cache dei registri privati.
Perché con un agente conta di più
L’incidente più vicino a chi lavora con un coding agent è quello di Nx. Il 26 agosto 2025, con un token npm rubato attraverso un workflow GitHub Actions vulnerabile, sono state pubblicate otto versioni malevole di nx, fra la 20.9.0 e la 21.8.0, più alcuni pacchetti @nx/*, rimaste online circa quattro ore secondo il postmortem. Il postinstall cercava credenziali e, scrive Nx, “ha tentato di usare gli strumenti AI locali (come Claude e Gemini)”, con un prompt che comincia con “You are a file-search agent”. I risultati finivano in un repository pubblico s1ngularity-repository sull’account GitHub della vittima.
L’advisory di Nx ricorda che oltre a npm install ci sono “molti modi meno ovvi” in cui un pacchetto viene installato, e il primo elenco è “dipendenze transitive, agenti AI, editor, altre estensioni”. Il caso concreto era l’estensione Nx Console, dalla 18.6.30 alla 18.65.1, che installava nx@latest per controllarne la versione: bastava aprire l’editor nella finestra sbagliata.
Un agente che risolve un errore di import lancia npm install su un nome, prende latest, e npm scrive il caret. Nella diff compare una riga "pacchetto": "^x.y.z" che dice poco su quello che girerà la prossima volta che il lock verrà rigenerato. Con la versione esatta la riga dice quale versione gira, e per cambiarla serve una diff che qualcuno deve approvare.
La configurazione
Per npm basta un .npmrc nella root del progetto, committato, così vale per chiunque lavori sul repo, agenti compresi:
save-exact=true
min-release-age=3
min-release-age, aggiunto in npm 11.10.0 (11 febbraio 2026), installa solo versioni disponibili “da più del numero di giorni indicato”; se nessuna versione lo soddisfa, il comando fallisce. Le due impostazioni coprono buchi diversi: la versione esatta impedisce che entri qualcosa senza diff, l’età minima impedisce di fissare una release pubblicata un’ora fa. Da npm 12.0.0 (8 luglio 2026), inoltre, gli script di lifecycle delle dipendenze sono bloccati di default salvo approvazione con npm install-scripts approve: avrebbe fermato i postinstall di eslint-scope e nx, non il codice di debug, che stava nei sorgenti del pacchetto e finiva nei bundle per il browser.
Gli altri package manager hanno le stesse leve. In pnpm saveExact è false di default e va in pnpm-workspace.yaml; da pnpm 11.0.0 minimumReleaseAge vale già 1440 minuti, cioè un giorno. Yarn usa .yarnrc.yml:
defaultSemverRangePrefix: ""
npmMinimalAgeGate: "1w"
Aggiornare senza range
Con le versioni fisse si aggiorna lo stesso, con una pull request per ogni cambio. In Renovate rangeStrategy: "pin" converte i range in versioni esatte (^1.0.0 → 1.1.0), e il preset :pinAllExceptPeerDependencies lo applica a tutto tranne engines, devEngines e peerDependencies. Il preset security:minimumReleaseAgeNpm, incluso in config:best-practices, aspetta tre giorni prima di proporre una versione npm, per dare tempo a ricercatori e scanner di trovare comportamenti malevoli:
{
"extends": ["config:best-practices", ":pinAllExceptPeerDependencies"]
}
Dependabot, per le applicazioni, usa di default la strategia increase, che alza il requisito alla nuova versione: con una versione esatta, una PR che cambia quel numero; su github.com applica anche un cooldown di 3 giorni alle version update, configurabile:
cooldown:
default-days: 5
semver-major-days: 30
semver-minor-days: 7
semver-patch-days: 3
Cosa la versione esatta non risolve
Il pin in package.json copre solo le dipendenze dirette. Se debug arriva come dipendenza transitiva con ^4.3.0, a decidere sono il lockfile e, alla rigenerazione, l’età minima: per questo le due regole vanno insieme. Il pin non aiuta nemmeno se fissi tu la versione sbagliata, come un bot in auto-merge che la propone dieci minuti dopo la pubblicazione. E per una libreria pubblicata il discorso cambia, almeno per le peerDependencies, che anche il preset di Renovate lascia fuori dal pin: lì la versione la sceglie l’applicazione che installa la libreria.
Per un’applicazione, però, non vedo un argomento a favore del caret che regga. Il range fa risparmiare una pull request di aggiornamento ogni tanto; in cambio lascia al registro, nel momento esatto in cui qualcuno, persona o agente, lancia un install, la scelta di cosa eseguire sulla tua macchina.
Altro in Workflow
AI Hero · Approfondimento
The Home Repo Pattern: una repo con skill e AGENTS.md che punta a tutte le altre▶ 018