Contenuti

• Per iniziare — da zero a installato in circa cinque minuti
• Cosa fa
• Cosa lo attiva
• Cosa c'è in questo repository
• Ecosistemi supportati
• Installazione
  • Configurazione
  • Modifica del periodo di attesa
• Livelli di avviso
• Come funziona
  • Modalità Normale (Manuale)
  • Modalità Intercettazione (Automatica)
  • Modalità Pre-Installazione (Hook Bash)
  • Modalità Post-Installazione (Hook Bash)
  • Modalità Post-Agente (Coppia di Hook Agente)
• Registro di controllo
• Requisiti
• FAQ

Per iniziare

GETTING-STARTED.md ti porta da zero a un'installazione funzionante in circa cinque minuti — prerequisiti, installazione interattiva e verifica. Per il riferimento completo all'installazione (installazioni globali/progetto/manuali, specifiche Windows, la allowlist dei permessi, aggiornamento e disinstallazione), vedi INSTALLATION.md.

Uso quotidiano: una volta installati gli hook, non c'è nulla da eseguire — safer-dependencies funziona automaticamente in background. Quando Claude aggiunge o installa pacchetti, segnala le dipendenze rischiose e aggiorna le versioni vulnerabili a una sicura sul posto — e blocca un'installazione nota come vulnerabile prima ancora che venga eseguita — così i pacchetti non sicuri vengono individuati e corretti senza che tu debba chiederlo. Puoi comunque invocarlo direttamente in qualsiasi momento: "è sicuro [email protected]?", "verifica la configurazione di safer-dependencies", o "mostra le statistiche di safer-dependencies".

Cosa fa

Quando Claude sta per aggiungere un pacchetto al tuo progetto, safer-dependencies intercetta ed esegue 5 controlli:

1. Provenienza -- registro ufficiale, rilevamento typosquatting (npm/PyPI/RubyGems/Maven/crates.io), età del pacchetto
2. Età della versione -- seleziona la versione stabile più recente pubblicata 7+ giorni fa (finestra di attesa)
3. Scansione vulnerabilità -- API OSV, con strumenti nativi dell'ecosistema (npm audit, pip-audit, bundle audit) quando disponibili
4. Integrità hash-pin -- per le righe di requirements.txt PyPI con pin --hash=sha256:..., l'hash dichiarato viene validato rispetto agli hash pubblicati da PyPI; una discrepanza genera un AVVISO
5. Pacchetti abbandonati e obsoleti -- i pacchetti noti come abbandonati (es. paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) vengono bloccati immediatamente con un sostituto suggerito; i pacchetti senza release stabile da 2+ anni ricevono un avviso consultivo STALE:. I pacchetti bloccati vengono rimossi dal manifest e Claude chiederà come procedere; i pacchetti solo obsoleti vengono lasciati al loro posto.

Se vengono rilevati problemi, Claude emette avvisi e può fare un passo indietro verso una versione più sicura. Tutti i controlli vengono registrati in ~/.claude/safer-dependencies-audit-YYYY-MM.log (un file per mese di calendario).

Cosa lo attiva

La skill si attiva automaticamente quando Claude:

Operazioni su manifest / installazione

• Aggiunge o aggiorna un pacchetto in package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod o qualsiasi altro manifest supportato
• Scrive un import, require o use per un pacchetto non già dichiarato nel manifest
• Genera o aggiorna un file di lock (controlla solo le voci nuove/modificate)
• Esegue un'installazione del package manager tramite Bash (npm install, bundle install, poetry install, uv sync, go mod tidy, ecc.) — Pre-Install controlla gli argomenti del comando, Post-Install controlla il lockfile risultante
• Scrive un Dockerfile o un workflow CI (.github/workflows/*.yml, ecc.) che incorpora passaggi di installazione del package manager con versioni pinnate

Domande di selezione e raccomandazione

• Confronti librerie/framework: "dovrei usare axios o node-fetch?", "moment vs dayjs?", "quale è meglio X o Y?"
• Richieste di raccomandazione: "qual è un buon client HTTP per Python?", "raccomanda una libreria di logging per Go", "quale pacchetto gestisce CSV in Node?"
• Selezione della versione: "quale versione di Django dovrei usare?", "ultima Flask stabile?"

Espressioni di intenzione d'uso (pre-aggiunta)

• "Voglio usare FastAPI per questo", "sto pensando di aggiungere Celery", "stiamo valutando Prisma come ORM", "usiamo Tailwind"

Domande su salute e affidabilità dei pacchetti

• "moment.js è ancora mantenuto?", "questa gemma è ancora attiva?", "X è abbandonato?", "X è EOL?", "posso fidarmi di questo pacchetto?", "quando è stato aggiornato l'ultima volta faker?"

Comandi di scaffolding

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, "bootstrap di un nuovo progetto FastAPI"

Aggiunte implicite di pacchetti (richieste di funzionalità che implicano una nuova dipendenza)

• "Aggiungi caching Redis all'app", "connettiti a Postgres", "aggiungi autenticazione JWT", "scrivi codice per inviare email" — si attiva quando nessun pacchetto per quella funzionalità è già nel manifest

Migrazione e porting

• "Migra da requests a httpx", "passa da CRA a Vite", "porta da moment a date-fns" — controlla il pacchetto in arrivo

Non si attiva non per:

• Import di librerie standard (os, fs, java.util.*, ecc.)
• Dipendenze già dichiarate che non vengono modificate
• Discussioni accademiche su come funziona internamente un pacchetto ("spiega il reconciler di React", "come funziona la risoluzione dei moduli di webpack?") — le domande di confronto e selezione attivano comunque la skill
• Installazione di app a livello di sistema operativo, runtime o estensioni IDE (Python stesso, Docker, Homebrew, estensioni VS Code)

Cosa c'è in questo repository

Questo è un bundle skill + hook, non un singolo file di skill. Un'installazione completa distribuisce questi componenti:

Il solo file di skill non è sufficiente — senza hook, l'invocazione automatica dipende dalla decisione di Claude di ricorrere alla skill. Installa tutti e cinque i componenti per una copertura completa; molte skill e slash command distribuiscono subagent internamente, quindi la coppia Post-Agente è importante anche se non ne generi mai esplicitamente uno. (Vedi FAQ.md per capire perché una skill da sola non può garantire la copertura.)

Ecosistemi supportati

Installazione

Nuovo al progetto? Inizia con GETTING-STARTED.md. La versione breve:```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

Gli stessi verbi funzionano anche al di fuori di una sessione Claude:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

L'agente genitore usa questi segnali per identificare il codice interessato e rifattorizzarlo secondo necessità.

Modalità Pre-Install (Hook Bash)

Configura .claude/settings.json con un hook PreToolUse:Bash per abilitare il controllo pre-volo dei comandi di installazione dei gestori di pacchetti. Questo integra (non sostituisce) la Modalità Intercept — insieme formano una difesa a strati.

1. Claude tenta una chiamata allo strumento Bash (es. npm install [email protected])
2. L'hook PreToolUse scatta prima che la chiamata venga eseguita e invoca safer-dependencies-pretooluse-bash.sh
3. Un filtro rapido in puro bash cortocircuita i comandi non-PM in ~115 ms (senza invocazione di Python), quindi git status / ls / npm test pagano un costo trascurabile sul percorso critico
4. Per le installazioni riconosciute dei gestori di pacchetti (npm/pnpm/yarn install/i/add), l'helper tokenizza tramite shlex, estrae ogni argomento pkg@version e lo invia a OSV
5. Qualsiasi pin concreto vulnerabile → l'hook restituisce permissionDecision: "deny" con un GHSA-id per-finding + CVSS + riepilogo, più un suggerimento per invocare la skill safer-dependencies
6. L'installazione non viene mai eseguita — nessun fetch di rete, nessuno script postinstall

Perché esiste in aggiunta alla Modalità Intercept: lo shim post-write è cieco a Bash. npm install [email protected] viene eseguito fino in fondo (e gli script postinstall vengono eseguiti) prima che qualsiasi audit scatti; npm install -g typosquat-pkg non scrive alcun manifest di progetto. La Modalità Pre-Install colma queste lacune strutturalmente.

La Modalità Pre-Install vede solo ciò che l'utente ha digitato (argomenti pkg@version sulla riga di comando). Non può vedere l'albero transitivo che il resolver installerà effettivamente. La Modalità Post-Install (sotto) controlla il lockfile una volta che l'installazione è completata — le due modalità sono complementari, non ridondanti.

Ambito: le CLI dei gestori di pacchetti qui coperte abbracciano cinque ecosistemi (npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo), più Maven tramite la Modalità Intercept (le dipendenze Maven sono tipicamente dichiarate in pom.xml/build.gradle, non aggiunte tramite un verbo CLI).

Lacuna nota: la CLI Maven supporta download diretti tramite mvn dependency:get -Dartifact=group:art:version e mvn dependency:copy. Questo hook non riconosce ancora tali invocazioni. Se le usi regolarmente, lo shim post-write esistente cattura comunque tutto ciò che finisce nel tuo manifest, ma la protezione pre-fetch si applica solo agli ecosistemi elencati sopra. Tracciato come follow-up.

Sintassi riconosciuta per ecosistema:

I pin di intervallo (npm ^4.17, pip >=, poetry ^/~, Go @latest) e le versioni non specificate passano alla Modalità Intercept dopo l'installazione — lo shim post-write controlla ciò che il resolver sceglie. La riscrittura automatica a una versione sicura è in coda come follow-up.

Modalità di errore: fail-open. Qualsiasi errore (Python mancante, problema di rete, input malformato) esce con 0 e nessun output, consentendo a bash di procedere. La Modalità Intercept viene comunque eseguita dopo l'installazione, quindi un pre-flight fallito degrada con garbo verso la protezione esistente.

Esempio di deny:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:

• [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash Re-run with a patched version, or invoke the safer-dependencies skill for a recommended pin.

Modalità Post-Agent (Coppia di Hook Agent)

Le quattro modalità sopra si attivano solo per le chiamate di strumenti della sessione root. Quando la sessione root invia un subagent (tramite lo strumento Agent — molte skill e comandi slash lo fanno internamente), le chiamate Write/Edit/Bash del subagent bypassano tutte queste modalità. La Modalità Post-Agent è la rete di sicurezza reattiva per questa lacuna.

1. Un hook PreToolUse:Agent (safer-dependencies-pretooluse-agent.sh) viene eseguito immediatamente prima di ogni invio di Agent e tocca un file sentinella in /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel (con fallback a un nome basato solo sul PPID quando non è disponibile un session id)
2. Il subagent viene eseguito e può scrivere manifest o lockfile
3. Un hook PostToolUse:Agent (safer-dependencies-posttooluse-agent.sh) viene eseguito dopo che la chiamata Agent restituisce il controllo, esegue find su ogni manifest e lockfile più recente della sentinella e li controlla tramite lo stesso percorso shim
4. I risultati emergono come additionalContext nel turno successivo della sessione root; la sentinella viene rimossa

I subagent annidati sono coperti automaticamente — il PostToolUse:Agent della root si attiva solo dopo che tutto il lavoro dell'agente esterno (incluso qualsiasi cosa esso abbia inviato) è su disco. L'unica lacuna è un'installazione globale che non scrive alcun manifest o lockfile (npm install -g …): non c'è nulla da scansionare. Come gli altri hook, fallisce in modalità aperta — qualsiasi errore (sentinella mancante, shim mancante, payload illeggibile) esce con 0 in silenzio. La logica progettuale completa è in skills/safer-dependencies.md.

Registro di controllo

Ogni controllo viene registrato in ~/.claude/safer-dependencies-audit-YYYY-MM.log (un file per mese di calendario, dove YYYY-MM è il mese-anno UTC) come singola riga JSON. È possibile sovrascrivere il percorso completo con la variabile d'ambiente SAFE_DEP_AUDIT_LOG (quando impostata, il suffisso della data non viene aggiunto). I file vengono anche ruotati per dimensione quando superano SAFE_DEP_LOG_MAX_BYTES (default 10 MiB; impostare a 0 per disabilitare). Impostare SAFE_DEP_MODEL per sovrascrivere il valore del modello scritto in source.model in ogni voce — utile per confronti A/B tra versioni di modelli.

Tutte e cinque le modalità aggiungono allo stesso file. Ogni voce include un blocco source (schema 2.2) che identifica quale componente l'ha scritta:

source.model registra il modello Claude Code attivo nella sessione (es. "claude-sonnet-4-6"). Presente nello schema 2.1+; le voci scritte da installazioni precedenti omettono il campo. Il comando stats degrada con grazia a "unknown" quando è assente.

Filtra per source.component con jq:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

Questo fornisce riepiloghi leggibili dall’uomo delle attività, dell’impatto sulla sicurezza e delle metriche di prestazione estratte da questi log di audit.

Forme delle voci (schema 2.2). Tre forme distinte condividono la stessa intestazione ts / schema / source:

Voci di audit: la Modalità Intercettazione esegue l’intera pipeline (provenienza, età della versione, OSV, abbandonati/obsoleti, typosquat, firme), quindi tutti gli array possono essere popolati. La Modalità Pre-Installazione oggi esegue solo OSV, quindi abandoned / stale / typosquat / signatures sono sempre vuoti. L’invio Post-Installazione (audit del lockfile) scrive sotto shim.posttooluse con findings popolato dalle stringhe WARNING: dei revisori del lockfile. L’array notes trasporta segnali informativi NOTE: (ad es. manifest-saltato-perché-non-pinnato).

Lo schema 2.2 ha aggiunto — in modo additivo — quattro campi alle voci di audit del lockfile: lockfile, manifest_ref, relation_summary (una classificazione diretta/transitiva/sconosciuta di ciascun pacchetto segnalato rispetto al manifest correlato) e un blocco policy che registra il livello transitive in vigore. L’aggiornamento è retrocompatibile: i lettori delle voci 2.1 tollerano i nuovi campi, e il campo source.model rimane presente dalla 2.1 in poi.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

Fail-open Mode example (hook Bash Post-installazione chiamato senza shim adiacente — installazione non riuscita):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }