Sommaire

• Pour commencer — de zéro à installé en environ cinq minutes
• Ce qu'il fait
• Ce qui le déclenche
• Contenu de ce dépôt
• Écosystèmes pris en charge
• Installation
  • Configuration
  • Modification de la période de refroidissement
• Niveaux d'avertissement
• Comment ça fonctionne
  • Mode normal (manuel)
  • Mode interception (automatique)
  • Mode pré-installation (hook Bash)
  • Mode post-installation (hook Bash)
  • Mode post-agent (paire de hooks Agent)
• Journal d'audit
• Prérequis
• FAQ

Pour commencer

GETTING-STARTED.md vous fait passer de zéro à une installation fonctionnelle en environ cinq minutes — prérequis, installation interactive et vérification. Pour la référence complète d'installation (installations globales/projet/manuelles, spécificités Windows, la liste blanche des autorisations, la mise à jour et la désinstallation), consultez INSTALLATION.md.

Utilisation quotidienne : une fois les hooks installés, il n'y a rien à exécuter — safer-dependencies fonctionne automatiquement en arrière-plan. Lorsque Claude ajoute ou installe des paquets, il signale les dépendances risquées et met à niveau les versions vulnérables vers une version sûre sur place — et bloque une installation connue comme vulnérable avant même qu'elle ne s'exécute — afin que les paquets non sûrs soient détectés et corrigés sans que vous ayez à le demander. Vous pouvez toujours l'invoquer directement à tout moment : « est-ce que [email protected] est sûr ? », « vérifier la configuration de safer-dependencies », ou « afficher les statistiques de safer-dependencies ».

Ce qu'il fait

Lorsque Claude s'apprête à ajouter un paquet à votre projet, safer-dependencies intercepte et exécute 5 contrôles :

1. Provenance — registre officiel, détection de typosquatting (npm/PyPI/RubyGems/Maven/crates.io), ancienneté du paquet
2. Ancienneté de version — sélectionne la version stable la plus récente publiée il y a plus de 7 jours (fenêtre de refroidissement)
3. Analyse des vulnérabilités — API OSV, avec les outils natifs de l'écosystème (npm audit, pip-audit, bundle audit) lorsqu'ils sont disponibles
4. Intégrité des épingles de hachage — pour les lignes PyPI requirements.txt avec des épingles --hash=sha256:..., le hachage déclaré est validé par rapport aux hachages publiés par PyPI ; une discordance émet un AVERTISSEMENT
5. Paquets abandonnés et obsolètes — les paquets connus comme abandonnés (par ex. paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) sont bloqués immédiatement avec un remplacement suggéré ; les paquets sans version stable depuis plus de 2 ans reçoivent un avertissement consultatif STALE:. Les paquets bloqués sont retirés du manifeste et Claude demandera comment procéder ; les paquets uniquement obsolètes sont laissés en place.

Si des problèmes sont détectés, Claude émet des avertissements et peut revenir à une version plus sûre. Tous les contrôles sont journalisés dans ~/.claude/safer-dependencies-audit-YYYY-MM.log (un fichier par mois calendaire).

Ce qui le déclenche

La compétence se déclenche automatiquement lorsque Claude :

Opérations sur les manifestes / installations

• Ajoute ou met à jour un paquet dans package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod ou tout autre manifeste pris en charge
• Écrit un import, require ou use pour un paquet non encore déclaré dans le manifeste
• Génère ou met à jour un fichier de verrouillage (vérifie uniquement les entrées nouvelles/modifiées)
• Exécute une installation via le gestionnaire de paquets en Bash (npm install, bundle install, poetry install, uv sync, go mod tidy, etc.) — la pré-installation audite les arguments de la commande, la post-installation audite le fichier de verrouillage résultant
• Écrit un Dockerfile ou un workflow CI (.github/workflows/*.yml, etc.) qui intègre des étapes d'installation épinglées du gestionnaire de paquets

Questions de sélection et de recommandation

• Comparaisons de bibliothèques/frameworks : « devrais-je utiliser axios ou node-fetch ? », « moment vs dayjs ? », « lequel est meilleur X ou Y ? »
• Demandes de recommandation : « quel est un bon client HTTP pour Python ? », « recommande une bibliothèque de journalisation pour Go », « quel paquet gère le CSV dans Node ? »
• Sélection de version : « quelle version de Django devrais-je utiliser ? », « dernier Flask stable ? »

Expressions d'intention d'utilisation (pré-ajout)

• « Je veux utiliser FastAPI pour ça », « je pense à ajouter Celery », « nous envisageons Prisma comme ORM », « utilisons Tailwind »

Questions sur la santé et la fiabilité des paquets

• « moment.js est-il toujours maintenu ? », « cette gemme est-elle toujours active ? », « X est-il abandonné ? », « X est-il en fin de vie ? », « puis-je faire confiance à ce paquet ? », « quand faker a-t-il été mis à jour pour la dernière fois ? »

Commandes de génération de projet

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, « initialiser un nouveau projet FastAPI »

Ajouts implicites de paquets (demandes de fonctionnalités impliquant une nouvelle dépendance)

• « Ajouter la mise en cache Redis à l'application », « se connecter à Postgres », « ajouter l'authentification JWT », « écrire du code pour envoyer des e-mails » — se déclenche lorsqu'aucun paquet pour cette capacité n'est déjà dans le manifeste

Migration et portage

• « Migrer de requests vers httpx », « passer de CRA à Vite », « porter de moment vers date-fns » — audite le paquet entrant

Il ne se déclenche pas pour :

• Les imports de la bibliothèque standard (os, fs, java.util.*, etc.)
• Les dépendances déjà déclarées qui ne sont pas modifiées
• Les discussions académiques sur le fonctionnement interne d'un paquet (« expliquer le reconciler de React », « comment fonctionne la résolution de modules de webpack ? ») — les questions de comparaison et de sélection déclenchent toujours l'outil
• L'installation d'applications au niveau du système, de runtimes ou d'extensions IDE (Python lui-même, Docker, Homebrew, extensions VS Code)

Contenu de ce dépôt

Il s'agit d'un ensemble compétence + hooks, pas d'un simple fichier de compétence. Une installation complète déploie ces éléments :

Le fichier de compétence seul ne suffit pas — sans hooks, l'invocation automatique dépend de la décision de Claude d'utiliser la compétence. Installez les cinq éléments pour une couverture complète ; de nombreuses compétences et commandes slash répartissent des sous-agents en interne, donc la paire post-agent est importante même si vous n'en générez jamais explicitement un. (Voir FAQ.md pour savoir pourquoi une compétence seule ne peut pas garantir la couverture.)

Écosystèmes pris en charge

Installation

Nouveau sur le projet ? Commencez par GETTING-STARTED.md. La version courte :```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

Les mêmes verbes fonctionnent en dehors d’une session Claude :```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

L'agent parent utilise ces signaux pour identifier le code affecté et le refactoriser si nécessaire.

Mode Pré-installation (Hook Bash)

Configurez .claude/settings.json avec un hook PreToolUse:Bash pour activer l'audit pré-vol des commandes d'installation de gestionnaires de paquets. Cela complète (ne remplace pas) le Mode Interception — ensemble, ils forment une défense en couches.

1. Claude tente un appel d'outil Bash (par ex. npm install [email protected])
2. Le hook PreToolUse se déclenche avant l'exécution de l'appel et invoque safer-dependencies-pretooluse-bash.sh
3. Un filtre précoce en bash pur court-circuite les commandes non-PM en ~115 ms (sans invocation Python), donc git status / ls / npm test ne paient qu'un coût négligeable sur le chemin critique
4. Pour les installations reconnues de gestionnaires de paquets (npm/pnpm/yarn install/i/add), l'assistant tokenise via shlex, extrait chaque argument pkg@version, et les POSTe vers OSV
5. Toute épingle concrète vulnérable → le hook renvoie permissionDecision: "deny" avec un ID GHSA par constatation + CVSS + résumé, plus une indication pour invoquer la compétence safer-dependencies
6. L'installation ne s'exécute jamais — aucun téléchargement réseau, aucun script postinstall

Pourquoi cela existe en plus du Mode Interception : le shim post-écriture est aveugle à Bash. npm install [email protected] s'exécute jusqu'au bout (et les scripts postinstall s'exécutent) avant qu'un audit ne se déclenche ; npm install -g typosquat-pkg n'écrit aucun manifeste de projet du tout. Le Mode Pré-installation comble ces lacunes structurellement.

Le Mode Pré-installation ne voit que ce que l'utilisateur a saisi (arguments pkg@version sur la ligne de commande). Il ne peut pas voir l'arbre transitif que le résolveur va réellement installer. Le Mode Post-installation (ci-dessous) audite le fichier de verrouillage une fois l'installation terminée — les deux modes sont complémentaires, pas redondants.

Portée : les CLI de gestionnaires de paquets couverts ici s'étendent sur cinq écosystèmes (npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo), plus Maven via le Mode Interception (les dépendances Maven sont généralement déclarées dans pom.xml/build.gradle, pas ajoutées via un verbe CLI).

Lacune connue : la CLI Maven prend en charge les téléchargements directs via mvn dependency:get -Dartifact=group:art:version et mvn dependency:copy. Ce hook ne reconnaît pas encore ces invocations. Si vous les utilisez régulièrement, le shim post-écriture existant capture toujours ce qui atterrit dans votre manifeste, mais la protection pré-récupération ne s'applique qu'aux écosystèmes listés ci-dessus. Suivi en cours.

Syntaxe reconnue par écosystème :

Les épingles de plage (npm ^4.17, pip >=, poetry ^/~, Go @latest) et les versions non spécifiées passent au Mode Interception après l'installation — le shim post-écriture audite ce que le résolveur choisit. La réécriture automatique vers une version sûre est planifiée comme suivi.

Mode de défaillance : fail-open. Toute erreur (Python manquant, coupure réseau, entrée malformée) se termine avec le code 0 et sans sortie, permettant à bash de continuer. Le Mode Interception s'exécute toujours après l'installation, donc un pré-vol échoué se dégrade élégamment vers la protection existante.

Exemple de refus :``` 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.

Mode Post-Agent (Paire de Hooks d'Agent)

Les quatre modes ci-dessus ne se déclenchent que pour les appels d'outils de la session racine. Lorsque la session racine délègue un sous-agent (via l'outil Agent — de nombreuses compétences et commandes slash le font en interne), les appels Write/Edit/Bash du sous-agent contournent tous ces modes. Le Mode Post-Agent est le filet de sécurité réactif pour cette lacune.

1. Un hook PreToolUse:Agent (safer-dependencies-pretooluse-agent.sh) s'exécute immédiatement avant chaque envoi d'Agent et touche un fichier sentinelle à /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel (avec repli sur un nom basé uniquement sur le PPID lorsqu'aucun identifiant de session n'est disponible)
2. Le sous-agent s'exécute et peut écrire des manifests ou des lockfiles
3. Un hook PostToolUse:Agent (safer-dependencies-posttooluse-agent.sh) s'exécute après le retour de l'appel Agent, find chaque manifest et lockfile plus récent que la sentinelle, et audite chacun via le même chemin de shim
4. Les résultats apparaissent comme additionalContext au tour suivant de la session racine ; la sentinelle est supprimée

Les sous-agents imbriqués sont couverts automatiquement — le PostToolUse:Agent de la racine ne se déclenche qu'après que tout le travail de l'agent externe (y compris tout ce qu'il a délégué) soit sur disque. La seule lacune est une installation globale qui n'écrit aucun manifest ni lockfile (npm install -g …) : il n'y a rien à analyser. Comme les autres hooks, il échoue ouvertement — toute erreur (sentinelle manquante, shim manquant, payload illisible) se termine par 0 en silence. La justification complète du design se trouve dans skills/safer-dependencies.md.

Journal d'audit

Chaque vérification est journalisée dans ~/.claude/safer-dependencies-audit-YYYY-MM.log (un fichier par mois calendaire, où YYYY-MM est le mois-année UTC) sous forme d'une seule ligne JSON. Remplacez le chemin complet avec la variable d'environnement SAFE_DEP_AUDIT_LOG (lorsqu'elle est définie, le suffixe de date n'est pas ajouté). Les fichiers sont également soumis à une rotation par taille lorsqu'ils dépassent SAFE_DEP_LOG_MAX_BYTES (10 Mio par défaut ; définissez à 0 pour désactiver). Définissez SAFE_DEP_MODEL pour remplacer la valeur du modèle écrite dans source.model de chaque entrée — utile pour les comparaisons A/B entre versions de modèles.

Les cinq modes ajoutent au même fichier. Chaque entrée porte un bloc source (schéma 2.2) identifiant quel composant l'a écrite :

source.model enregistre le modèle Claude Code actif dans la session (par ex. "claude-sonnet-4-6"). Présent dans le schéma 2.1+ ; les entrées écrites par des installations plus anciennes omettent le champ. La commande de statistiques se dégrade gracieusement en "unknown" lorsqu'il est absent.

Filtrez par source.component avec 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

Ceci fournit des résumés lisibles par un humain de l’activité, de l’impact sur la sécurité et des métriques de performance extraits de ces journaux d’audit.

Formes d’entrées (schéma 2.2). Trois formes distinctes partagent le même en-tête ts / schema / source :

Entrées d’audit : le mode Interception exécute le pipeline complet (provenance, ancienneté de version, OSV, abandonné/obsolète, typosquat, signatures), donc tous les tableaux peuvent être remplis. Le mode Pré-installation n’exécute aujourd’hui que OSV, donc abandoned / stale / typosquat / signatures sont toujours vides. La répartition post-installation (audit de lockfile) écrit sous shim.posttooluse avec findings rempli par les chaînes WARNING: provenant des auditeurs de lockfile. Le tableau notes transporte les signaux informatifs NOTE: (par exemple, manifeste ignoré car non épinglé).

Le schéma 2.2 a ajouté — de manière additive — quatre champs aux entrées d’audit de lockfile : lockfile, manifest_ref, relation_summary (une classification directe/transitive/inconnue de chaque paquet signalé par rapport au manifeste frère), et un bloc policy enregistrant le niveau transitive en vigueur. Cette mise à niveau est rétrocompatible : les lecteurs des entrées 2.1 tolèrent les nouveaux champs, et le champ source.model reste présent à partir de la version 2.1.```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 (Post-Install Bash hook called with no shim adjacent — broken install):```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" } }