Audit de plugin Claude Code : valider ne suffit pas
La validation officielle ne prouve ni le bon fonctionnement ni la sécurité d’un plugin Claude Code. Découvrez comment auditer ses manifestes avant installation.
Plugin Claude Code : pourquoi la validation ne suffit pas
Un plugin Claude Code peut passer la validation officielle et rester défectueux, trompeur ou risqué à installer. Ce n'est pas forcément un bug du validateur : il vérifie surtout que la structure du plugin est acceptable, pas que toutes les options déclarées sont réellement prises en charge, ni que le code correspond à ce que dit le manifeste.
La nuance compte. Dans un projet réel, une commande peut sembler correctement configurée, puis retomber silencieusement sur une valeur par défaut parce qu'un paramètre est ignoré. Et parfois, le manifeste lui-même est incomplet : il minore les capacités du plugin ou n'indique pas des scripts présents sur le disque. Résultat : un statut vert ne répond pas vraiment à la question essentielle - ce que ce code fait concrètement une fois installé.
Voici comment comprendre cette limite, auditer un plugin avec frontmatter-guard, et intégrer ce contrôle à votre processus sans le transformer en audit de sécurité complet. L'idée n'est pas de remplacer la validation officielle, mais de vérifier une autre dimension : la cohérence entre ce qui est annoncé et ce qui se trouve dans le dépôt.
Ce que la validation officielle vérifie - et ce qu'elle ne vérifie pas
La commande claude plugin validate est utile. Elle contrôle la structure du plugin et aide à repérer des erreurs qui peuvent empêcher son chargement. Mais c'est une validation de format et de compatibilité : ce n'est pas une preuve du comportement réel du code.
Le problème vient souvent du signal binaire. La commande s'exécute, affiche un succès, renvoie zéro en code de sortie : dans une chaîne d'intégration continue, ça ressemble à un feu vert général. En pratique, ça veut juste dire que les vérifications effectuées n'ont pas échoué. Ça ne prouve ni que tous les champs sont appliqués, ni que le plugin fait ce que son auteur promet, ni que ses scripts sont inoffensifs.
Un champ accepté peut être ignoré
frontmatter-guard décrit un cas concret : un champ effort: high est ajouté au frontmatter d'une commande. La validation passe, mais ce paramètre correspond à un concept utilisé par Codex et ignoré par Claude Code. Le comportement attendu n'est donc pas appliqué : le système repasse sur des réglages de session.
C'est un défaut pénible, parce que tout « a l'air » correct. Le fichier reste lisible, l'outil ne dit rien, et les tests peuvent ne pas couvrir l'écart de configuration. Pourtant, en production, ce n'est pas le résultat qu'on a demandé.
frontmatter-guard cible précisément ce type de problèmes. L'outil analyse les champs du frontmatter et signale notamment :
- les clés inconnues, avec des suggestions de correction quand c'est pertinent ;
- les noms d'événements de hooks mal orthographiés, qui ne se déclencheraient jamais ;
- les champs obligatoires manquants ;
- les versions mal formées et les types de données incorrects.
Cette analyse sémantique complète la validation de structure. Elle ne remplace pas des tests fonctionnels : elle sert surtout à attirer l'attention sur des déclarations qui « passent » sans être réellement comprises par l'outil visé.
Le succès d'une validation n'est pas une garantie de sécurité
Il faut distinguer trois questions : le plugin respecte-t-il le format attendu ? Ses déclarations correspondent-elles aux fichiers et aux capacités réelles ? Son code est-il sûr dans votre environnement ? La commande officielle répond surtout à la première. Un audit du manifeste aide plutôt à la deuxième. La troisième demande une analyse plus large.
Cette séparation évite deux mauvaises habitudes. La première, c'est de traiter le statut vert comme une certification de sécurité. La seconde, c'est de jeter le validateur parce qu'il « ne suffit pas ». En pratique, le mieux est d'empiler des contrôles complémentaires plutôt que d'attendre d'une seule commande qu'elle règle tout.
Pourquoi le manifeste mérite un audit distinct
Un plugin ne se limite pas à son frontmatter. Le manifeste, souvent situé dans .claude-plugin/plugin.json, fournit des infos sur le plugin et peut déclarer certaines capacités. Il y a donc un autre angle mort : vérifier si ces déclarations collent à ce qui se trouve réellement dans le dépôt.
Un plugin peut, par exemple, utiliser un nom qui emprunte l'autorité d'un éditeur officiel, contenir des scripts de hooks que le manifeste n'indique pas, ou annoncer des capacités sans déclarer les permissions associées. À l'inverse, il peut aussi déclarer des permissions que son code n'utilise pas. Ces écarts ne prouvent pas automatiquement une intention malveillante, mais ils méritent d'être expliqués avant installation.
Six contrôles pour comparer les déclarations à la réalité
La version 0.2 de frontmatter-guard ajoute un audit du manifeste et produit un verdict - pass, review ou fail - avec des constats et des pistes de correction. Les règles décrites ici couvrent plusieurs risques :
| Règle | Niveau | Ce qu'elle signale |
|---|---|---|
impersonating-name |
Erreur | Un nom qui emprunte une apparence officielle, par exemple avec des préfixes comme official- ou anthropic- |
typosquat-name |
Avertissement | Un nom très proche d'un nom officiel, susceptible de créer une confusion |
undeclared-hooks |
Erreur | Des scripts de hooks présents sur le disque alors qu'aucun hook n'est déclaré dans le manifeste |
undeclared-capability |
Erreur | Des capacités détectées, comme l'exécution de commandes ou l'accès réseau, sans permission correspondante déclarée |
over-declared-permissions |
Avertissement | Des permissions annoncées sans code correspondant repéré |
missing-provenance |
Avertissement | L'absence d'informations de provenance, comme l'auteur, le dépôt, la licence ou la page d'accueil |
Le niveau de sévérité aide à prioriser, mais il ne faut pas le lire comme un jugement sur l'intention. Un nom « suspect » peut avoir une explication. Une permission manquante peut refléter une règle différente de celle que l'analyse attend. Le but du contrôle, c'est de rendre l'écart visible et de demander une vérification, pas de remplacer le jugement technique.
Pourquoi les hooks et les permissions changent l'évaluation
Les hooks comptent parce qu'ils peuvent déclencher des commandes à des moments précis du cycle d'utilisation. Si des scripts existent mais ne figurent pas dans les déclarations du manifeste, le lecteur ne dispose pas d'une description complète de ce qu'il installe. Même chose pour les capacités : une capacité réseau ou d'exécution de commandes change le niveau de prudence. Un plugin qui contacte un service externe ou lance un processus mérite plus d'attention qu'un ensemble d'instructions purement statiques.
Le contrôle des permissions joue dans les deux sens. Une capacité réelle non déclarée est un écart préoccupant. Une permission annoncée sans code correspondant peut aussi indiquer un manifeste mal entretenu, une configuration trop large, ou une implémentation qui a changé. Dans les deux cas, la question pratique reste la même : est-ce que vous pouvez expliquer l'écart avant de faire confiance ?
La provenance aide aussi. Une licence, un dépôt public et un auteur identifié ne garantissent pas la qualité du code. Mais leur absence réduit la capacité à comprendre l'origine du plugin, suivre ses changements et demander des comptes. C'est un signal contextuel, pas une preuve de malveillance.
Auditer un plugin avec frontmatter-guard
L'outil est pensé pour être simple à lancer localement ou en chaîne d'intégration continue. D'après les informations fournies pour la version 0.2, frontmatter-guard s'installe via PyPI, ne nécessite pas de dépendances externes, et fonctionne avec Python 3.9 ou plus.
Installation et première analyse
Dans un environnement Python adapté, installez le paquet puis lancez l'analyse sur le répertoire du plugin :
pip install frontmatter-guard
frontmatter-guard check ./mon-plugin
Remplacez ./mon-plugin par le chemin réel de votre dépôt (ou de la copie) à inspecter. Le point important : analyser les fichiers qui seront effectivement installés, pas une version intermédiaire ou un extrait incomplet.
L'outil peut remonter plusieurs constats en une seule exécution. Voici un exemple typique de sortie pour un plugin présentant des problèmes :
mon-plugin/.claude-plugin/plugin.json:1: error [impersonating-name]
Le nom du plugin « official-superpowers » emprunte le préfixe « official ».
correction : choisissez un nom qui ne laisse pas croire à un statut officiel.
mon-plugin/.claude-plugin/plugin.json:1: error [undeclared-hooks]
Des scripts de hooks existent, mais aucun hook n'est déclaré dans le manifeste.
correction : déclarez les hooks ou retirez les fichiers concernés.
mon-plugin/.claude-plugin/plugin.json:1: error [undeclared-capability]
Le plugin peut utiliser le réseau et exécuter des commandes sans permission correspondante.
correction : déclarez les capacités nécessaires ou retirez le code qui les utilise.
Verdict du manifeste : fail
Un verdict fail signifie qu'au moins un constat de niveau erreur a été trouvé, et peut faire échouer un contrôle automatisé. Un résultat review demande une vérification humaine. pass, lui, veut seulement dire que les règles de cet audit n'ont pas détecté de problème bloquant - pas que le plugin est « sûr » dans l'absolu.
Pour l'automatisation, --format json produit une sortie structurée exploitable par un script ou par votre CI. Consultez la documentation du projet sur GitHub pour les options disponibles dans la version que vous installez. Le paquet est aussi publié sur PyPI.
Comment traiter les résultats
Un audit utile ne consiste pas à supprimer les avertissements jusqu'à obtenir du vert. Pour chaque constat, faites simple et actionnable :
- Localisez le fichier concerné. Vérifiez la version réellement présente dans le dépôt et celle qui sera distribuée.
- Comprenez la règle déclenchée. Un nom qui ressemble à un nom officiel et une permission trop large ne se corrigent pas de la même façon.
- Comparez le manifeste au code. Vérifiez les hooks, les commandes et les serveurs MCP déclarés ou détectés.
- Corrigez ou documentez l'écart. Si c'est un faux positif, gardez une justification claire pour celles et ceux qui reliront plus tard.
- Relancez l'analyse et faites des tests fonctionnels. Corriger le manifeste ne prouve pas que le comportement du plugin est bon.
Cette approche évite deux réflexes peu fiables : accepter sans regarder parce que « ça passe », ou désactiver une règle juste parce qu'elle bloque la livraison. Le but est de rendre les décisions explicites et reproductibles.
Intégrer le contrôle sans en faire une fausse garantie
Pour un plugin que vous développez, ce contrôle a sa place dans le processus de livraison : après les tests de base, avant la publication. En CI, la sortie JSON peut faciliter l'archivage des résultats ou leur envoi à un outil interne. Mais il faut définir clairement quels constats bloquent une livraison, et lesquels déclenchent seulement une revue.
Une politique raisonnable peut traiter les erreurs comme bloquantes, tout en demandant une validation humaine sur les avertissements. Les règles de nommage et de provenance sont utiles, mais leur gravité dépend du contexte. À l'inverse, un hook non déclaré ou une capacité réelle non annoncée devrait généralement être corrigé avant distribution : ce sont des signaux directement liés à la compréhension du comportement.
Pour les équipes qui installent des plugins tiers
Si vous installez des plugins hors de votre périmètre direct, analysez-les avant installation, idéalement à partir d'une copie locale ou d'un environnement de test. Ensuite, vérifiez le code lui-même en fonction des résultats : hooks, commandes, accès réseau, et serveurs MCP. Le rapport vous donne une liste de points à vérifier, il ne remplace pas l'inspection.
Dans une entreprise française ou européenne, ça peut s'intégrer à une démarche plus large de maîtrise des dépendances et de la chaîne logicielle. Ça ne remplace ni les règles internes de sécurité, ni une revue adaptée à la sensibilité des données. Si un plugin peut accéder à des données personnelles, à des dépôts privés ou à des systèmes internes, le niveau d'examen doit être proportionné aux impacts possibles.
Ce que l'outil ne démontre pas
frontmatter-guard est un linter et un auditeur de cohérence selon des règles définies. Il ne prouve pas qu'un plugin ne contient aucun code malveillant. Il ne garantit pas non plus que toutes les capacités seront détectées, que les permissions seront interprétées de la même manière dans tous les environnements, ou que le comportement sera exactement celui attendu à l'exécution.
Du coup, gardez plusieurs couches : validation officielle, analyse du frontmatter et du manifeste, lecture ciblée des scripts, tests en environnement isolé, et application du moindre privilège. Tout dépend du risque. Pour un plugin interne sans accès sensible, une revue proportionnée peut suffire. Pour un plugin tiers ayant accès à des données ou à des outils de développement importants, un verdict automatique seul serait une erreur de méthode.
Enfin, les caractéristiques annoncées par le projet - version, compatibilité Python, nombre de tests - peuvent évoluer. Vérifiez la documentation et les versions au moment où vous l'intégrez. Un outil de contrôle doit lui aussi être maintenu et adapté à la plateforme qu'il analyse.
Conclusion
Une validation réussie répond à une question limitée : le plugin passe-t-il les contrôles effectués par ce validateur ? Elle ne prouve ni que les paramètres produisent l'effet attendu, ni que le manifeste est fidèle, ni que le code est sûr.
Pour réduire l'angle mort, combinez la validation officielle avec un audit des déclarations et une revue proportionnée du code. Si vous développez un plugin, ajoutez ce contrôle à votre CI et traitez les erreurs avant publication. Si vous en installez un, lancez l'analyse et vérifiez les hooks et capacités signalés avant de lui accorder des accès.
Vous pouvez commencer par consulter frontmatter-guard sur GitHub, vérifier la version disponible sur PyPI et l'essayer sur une copie du plugin. Le bon réflexe n'est pas de chercher un feu vert de plus : c'est de comprendre exactement ce que chaque feu vert recouvre.