- Empêcher les mods des utilisateurs de se charger, avec ou sans vos propres mods : Arrêter le chargement des mods installés par les utilisateurs
- Voir ce que vos utilisateurs obtiennent quand vous ne changez rien : Savoir ce qui se passe par défaut
- Laisser les mods activés avec d’autres limites : Choisir le niveau d’autorisation
Ces cas sont couverts sur d’autres pages :
- Vous n’avez jamais déployé de paramètres gérés auparavant : commencez par Déployer les paramètres gérés
- Vous souhaitez contrôler les plugins que les utilisateurs peuvent installer : voir Gérer les plugins pour votre organisation
Arrêter le chargement des mods installés par les utilisateurs
Pour empêcher chaque mod que vos utilisateurs apportent d’exécuter ses hooks, définissez l’optionallowManagedModsOnly sur le garde-fou intégré, un mod de politique que Claude Code charge avant chaque mod qu’un utilisateur installe. L’option se trouve dans les paramètres gérés sous pluginConfigs, indexée par cc-plugin-sec-default@builtin :
managed-settings.json
- Aucun mod qu’un utilisateur apporte n’exécute ses hooks : cela couvre un mod dans un plugin que l’utilisateur a installé, un mod chargé avec
--plugin-dir, et un mod que Claude a écrit pendant une session - Les mods de votre organisation s’exécutent toujours : un mod qui compte comme celui de votre organisation n’est pas vérifié. Tous les autres mods comptent comme ceux d’un utilisateur et sont refusés. Cela inclut un mod que votre organisation active pour ses membres sur claude.ai. Si aucun ne compte comme le vôtre, aucun mod installé n’exécute ses hooks.
- Les utilisateurs ne peuvent pas l’annuler : le garde-fou lit l’option uniquement à partir des paramètres gérés, donc la même entrée dans un fichier de paramètres utilisateur, projet ou local, ou dans un fichier passé avec
--settings, ne change rien - Un fichier ou une politique MDM couvre chaque fournisseur : quand vous livrez l’option sous forme de fichier ou via MDM, elle fonctionne de la même manière sur Amazon Bedrock, la plateforme Agent de Google Cloud, et Microsoft Foundry. Pour la livraison depuis la console d’administration claude.ai, voir Disponibilité de la plateforme
- Les autres personnalisations des utilisateurs continuent de fonctionner : leurs hooks dans les fichiers de paramètres et dans le fichier
hooks/hooks.jsondes plugins, les barres de statut, et/goalne sont pas affectés - Les mods intégrés continuent de s’exécuter : les mods intégrés à Claude Code, comme le support
AGENTS.md, ont chacun leur propre commutateur
--plugin-dir et le chemin d’un répertoire qui contient un mod, comme claude --plugin-dir ./first-mod. Les hooks du mod ne s’exécutent pas, et la transcription et le journal de débogage contiennent le message du garde-fou, qui nomme le mod et allowManagedModsOnly. Si le message n’y figure pas, voir Vérifier qu’une politique est en vigueur et les règles qui décident si une option prend effet.
Si vous avez défini CLAUDE_CODE_ENABLE_FUNCTION_HOOKS à 0 lors de l’accès anticipé, remplacez-le par cette option. Claude Code v2.1.287 et versions ultérieures ignorent la variable à n’importe quelle valeur, donc un 0 là-bas laisse les mods activés.
Savoir ce qui se passe par défaut
Sans vos propres paramètres de mod, voici ce que vos utilisateurs obtiennent :-
Les mods sont activés. Un utilisateur peut installer un plugin qui contient un mod à partir de n’importe quelle place de marché que vos paramètres de plugin autorisent, ou en charger un à partir d’un répertoire avec
--plugin-dir. -
Un garde-fou intégré s’exécute en premier. Claude Code charge un mod intégré nommé
sec-default@builtinavant chaque mod qu’un utilisateur installe. Les utilisateurs ne peuvent pas le désactiver./pluginet le log de débogage le listent commecc-plugin-sec-default. Le garde-fou se charge quand l’une de ces conditions est vraie :- La machine a des paramètres gérés ou un fichier
managed-mcp.json - La session s’exécute avec des identifiants
/loginpour un plan Team ou Enterprise
managed-mcp.json. Une session qui s’exécute avec unCLAUDE_CODE_OAUTH_TOKENde longue durée ne compte pas non plus comme cette connexion, même lorsqu’une connexion Team ou Enterprise est enregistrée sur la machine. - La machine a des paramètres gérés ou un fichier
-
Le garde-fou protège ce que vous gérez. Le mod d’un utilisateur ne peut pas changer ce que vos hooks gérés reçoivent ou décident, le prompt système, ni votre
CLAUDE.mdgéré et autres instructions gérées. Il ne peut pas non plus changer ce que n’importe quel mod lit comme paramètres, ni les outils et descriptions de vos serveurs MCP gérés une fois qu’ils sont connectés. -
Sur la v2.1.323 ou ultérieure, le mod d’un utilisateur peut empêcher un serveur MCP géré de se connecter. Dans la session de cet utilisateur,
/mcpliste le serveur comme retenu par ce mod. Pour éviter cela, empêchez les mods installés par les utilisateurs de se charger. - En dehors de ce que vous gérez, le mod d’un utilisateur agit en tant que cet utilisateur. Le mod conserve les permissions de cet utilisateur : il peut toujours lire et écrire des fichiers, démarrer des processus et effectuer des requêtes réseau. Il peut aussi réécrire les appels d’outils et les prompts, refuser un appel d’outil, ajouter ou retirer des outils et dessiner dans l’interface.
-
Les règles de permission et les hooks
PreToolUseont priorité sur le mod d’un utilisateur. Avec le garde-fou chargé, par défaut le mod d’un utilisateur ne peut pas approuver un appel qu’une règledenyrefuse ou pour lequel une règleaskdéclenche une demande, quel que soit le fichier de paramètres qui contient la règle. Le mod ne peut pas non plus approuver un appel qu’un hookPreToolUsea bloqué. Les règles de permission et les hooksPreToolUses’appliquent aux appels d’outils de Claude, pas aux appels$.fset$.processd’un mod. AvecRead(.env)refusé, un mod peut toujours lire ce fichier avec$.fs.readou démarrer un programme qui le fait. Pour limiter les propres appels$.fset$.processd’un mod, empêchez le mod de se charger ou gérez-les dans un mod de politique. -
Le mod d’un utilisateur peut toujours contourner certaines demandes. En mode auto, un appel que le mod approuve s’exécute sans vérification du classifieur, sauf si le garde-fou est chargé et que la session s’exécute avec
--permission-prompt-toolou un callbackcanUseToolde l’Agent SDK. Dans ce cas, le classifieur vérifie d’abord l’appel. Pour les demandes qu’une approbation d’un mod ne contourne pas, voir Étendre les permissions avec des hooks.
mods/sec-default du référentiel Claude Code.
Savoir quels contrôles s’appliquent toujours
Les mods ne remplacent pas les contrôles que vous avez déjà :-
Les hooks de paramètres continuent de fonctionner. Les hooks de commande, HTTP, de prompt et d’agent dans les fichiers de paramètres et dans le
hooks/hooks.jsondes plugins s’exécutent comme avant, aux côtés des mods. -
Les règles de refus ont la priorité là où la garde se charge. Le mod d’un utilisateur ne peut pas approuver un appel qu’une règle
denyrefuse, sauf si vous définissezallowModsToOverrideDenyRules. -
Les hooks gérés s’exécutent en premier. Un hook
PreToolUsedans les paramètres gérés s’exécute avant le hooktool.callde n’importe quel mod, et lorsque ce hook géré bloque un appel d’outil, aucun hooktool.callde mod ne s’exécute pour cet appel. Si l’appel se poursuit et qu’un mod le réécrit, vos hooks gérés s’exécutent à nouveau sur l’appel réécrit, ils peuvent donc, par défaut, toujours le bloquer. Les hooksPreToolUsed’autres fichiers de paramètres et de plugins s’exécutent après le dernier mod. Si un mod répond lui-même à l’appel d’outil, l’outil ne s’exécute jamais, pas plus que ces hooks. Voir L’ordre dans lequel les mods s’exécutent. -
La politique réseau couvre
$.http.fetch.-
La politique de votre organisation n’autorise pas WebFetch : Claude Code refuse également toutes les requêtes
$.http.fetchde chaque mod. Voir Disponibilité de WebFetch. -
Vous désactivez l’outil WebFetch avec
CLAUDE_CODE_DISABLE_WEB_FETCHou une règle de refusWebFetch, dans les paramètres gérés ou tout autre fichier de paramètres : les mods peuvent toujours effectuer des requêtes$.http.fetch. Pour les arrêter pour chaque mod que vos utilisateurs installent, empêchez les mods installés par les utilisateurs de se charger, ou interceptezhttp.fetchavec un hook dans un mod de politique et refusez les requêtes provenant des mods des utilisateurs. Donnez à ce hook un gestionnaire.catchqui refuse également, car Claude Code ignore un hook qui échoue et la requête est alors effectuée. Si vous vous contentez de restreindre ce que les utilisateurs peuvent installer, moins de mods se chargent, mais ceux que vous autorisez peuvent toujours effectuer ces requêtes. -
Vous définissez
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: un mod que vous ou vos utilisateurs installez peut toujours effectuer ces requêtes. La variable n’arrête que les mods intégrés à Claude Code, ainsi que toute requête$.http.fetchqui transporte les identifiants Anthropic de la session. Avant la v2.1.288, la variable arrêtait toutes les requêtes$.http.fetchde chaque mod.
$.process.run, qui atteint le réseau avec l’accès propre de l’utilisateur. -
La politique de votre organisation n’autorise pas WebFetch : Claude Code refuse également toutes les requêtes
-
Les contrôles de plugin couvrent les mods. Un mod est un plugin, donc les paramètres qui limitent ce que les utilisateurs peuvent installer, comme
strictKnownMarketplaces, décident s’il peut être installé du tout. - Les mods ne peuvent pas changer l’invite de permission. Un mod peut redessiner une grande partie de l’interface de Claude Code, mais pas l’invite de permission, donc il ne peut pas changer ce qu’une invite affiche. Un mod peut toujours approuver ou refuser un appel d’outil avant que l’invite n’apparaisse, comme Savoir ce qui se passe par défaut le décrit.
- Les invites de confiance viennent en premier. Dans une session interactive dans un répertoire que l’utilisateur n’a pas encore approuvé, aucun mod ne se charge jusqu’à ce qu’il réponde à l’invite de confiance.
-
--safe-modedésactive les mods installés, y compris les vôtres. Démarrez une session avecclaude --safe-modepour vérifier si un mod a causé un problème.
Savoir quels hooks du mod d’un utilisateur ne s’exécutent pas
Là où le garde-fou intégré se charge, un hook que le mod d’un utilisateur enregistre sur l’un de ces événements ne s’exécute jamais, et/plugin en informe cet utilisateur par une note. Dans les lignes session.append, door est le type de ligne stockée sur lequel le hook est filtré.
Le garde-fou ignore aussi les hooks d’un utilisateur dans certains autres cas, comme les descriptions des outils de votre organisation, sur
tool.describe, et la ligne stockée pour le texte d’un skill. /plugin n’affiche aucune note pour ceux-ci. Si un hook sur un autre événement ne fait rien, voir Découvrir pourquoi un mod ne fait rien.
La note apparaît dans les détails du plugin et dans l’onglet Errors de /plugin. Elle nécessite Claude Code v2.1.299 ou ultérieure. Elle nomme chaque hook du tableau tel que le mod l’a enregistré, comme dans cet exemple :
- Exécuter le mod comme celui de votre organisation : installez le mod de sorte qu’il compte comme le vôtre. Ses hooks sur ces événements s’exécutent alors, et le garde-fou reste chargé pour tous les autres mods. Le mod s’active pour tous ceux qui reçoivent ces paramètres. Si vous le listez dans
prependPlugins, conservezsec-default@builtindans la liste. - Retirer le garde-fou : omettez
sec-default@builtindeprependPlugins. Une liste vide,"prependPlugins": [], suffit. Vous perdez l’ensemble du garde-fou, pas seulement ces événements. Le mod d’un utilisateur peut alors faire ce que le garde-fou l’empêche sinon de faire, et les options du garde-fou ne s’appliquent pas.
/plugin dans une session sur cette machine et vérifiez que la note a disparu.
Un hook session.append sans filtre door s’exécute toujours et ne reçoit aucune note, mais les lignes stockées du tableau ne lui parviennent pas.
Décider de laisser les mods activés
Un mod peut faire plus que les autres parties d’un plugin car il s’exécute à l’intérieur de Claude Code. Il voit chaque invite et appel d’outil, peut les changer, et peut autoriser ou refuser un appel d’outil avant qu’une invite de permission n’apparaisse. Ce qu’un utilisateur peut charger en tant que mod dépend des contrôles de plugin que vous avez déjà :
Gérer les plugins pour votre organisation liste chaque façon dont un plugin se charge et le paramètre qui contrôle chacun.
Pour vérifier les mods dans une place de marché avant que vos utilisateurs les installent, voir Examiner ce qu’un mod peut faire. Pour empêcher les mods des utilisateurs de se charger jusqu’à ce que vous ayez fait cela, voir Arrêter le chargement des mods installés par les utilisateurs.
Examiner ce qu’un mod peut faire
Vous pouvez voir ce qu’un mod est capable de faire sans l’exécuter. Dans votre shell, exécutezclaude plugin validate sur le répertoire du plugin :
hooks: et calls: de la sortie décrivent le code du mod :
hooks:: les événements que le mod reçoit. Une notedefault matcher key: pluginsignifie que le hook qui la précède ignore les contrôles et les dessins des autres mods.calls:: les méthodes de l’API des mods que son code appelle
$ dans le code d’un mod, est la façon dont un mod atteint les fichiers, les processus et le réseau. Claude Code refuse de charger un mod qui utilise l’API des mods d’une manière que cette commande ne peut pas lire.
N’approuvez pas un mod qui échoue à cette commande, car certains échecs ne l’empêchent pas de se charger. Exécutez la commande sur Claude Code v2.1.323 ou ultérieur, où une longue liste se poursuit sur d’autres lignes avec le même libellé, et lisez chaque ligne hooks: et calls:. Dans les lignes calls:, recherchez celles-ci :
Dans la ligne
hooks:, tool.call et prompt.submit signifient que le mod voit chaque appel d’outil et chaque prompt, et peut les changer. session.append signifie que le mod peut réécrire chaque ligne de la conversation avant qu’elle ne soit stockée, à l’exception des lignes que la protection ignore. ui.render{component=AskUserQuestion} signifie que le mod peut redessiner la boîte de dialogue que Claude utilise pour poser une question à l’utilisateur. tool.check signifie que le mod peut approuver ou refuser un appel d’outil avant qu’une demande de permission n’apparaisse. Savoir ce qui se passe par défaut liste lesquels de vos règles et hooks ont la priorité sur sa réponse.
Choisir le niveau d’autorisation
Les politiques de mod vont d’aucun mod installé du tout à n’importe quel mod qu’un utilisateur choisit, avec votre propre mod vérifiant les autres, et chacun est quelques paramètres gérés. Trouvez la politique que vous voulez dans la première colonne et définissez ce que la deuxième colonne nomme. Déployer les paramètres gérés couvre où vivent les paramètres gérés.
Ce que chaque paramètre fait :
allowManagedModsOnly: une option sur le garde-fou intégré. Claude Code refuse les mods propres des utilisateurs, de sorte qu’aucun de leurs hooks ne s’exécute. Les hooks de paramètres, les barres de statut et/goaldes utilisateurs continuent de fonctionner. Arrêter le chargement des mods installés par les utilisateurs liste ce qu’il couvre.allowManagedHooksOnly: un paramètre plus large. Seuls les mods de votre organisation et les mods intégrés à Claude Code se chargent. Un mod qu’un utilisateur a installé lui-même ne se charge pas. Le paramètre bloque aussi les hooks dans les fichiers de paramètres propres des utilisateurs. Lisez Ce qui s’exécute sousallowManagedHooksOnlyavant de le définir.disableAllHooks: le paramètre le plus large. Dans les paramètres gérés, il arrête les mods dans chaque plugin installé, y compris les vôtres, et désactive chaque hook dans les fichiers de paramètres, donc un hookPreToolUsedans vos paramètres gérés ne bloque plus rien. Les barres de statut personnalisées et/goalcessent aussi de fonctionner. LisezdisableAllHooksavant de le définir.disableSideloadFlags: rejette--plugin-diret--plugin-urlau démarrage, et empêche les mods que Claude écrit pendant une session de se charger. Le paramètre rejette aussi--agentset--mcp-config. LisezdisableSideloadFlagsavant de le définir.
AGENTS.md, ne sont pas affectés par ces paramètres. Chacun a son propre commutateur.
Un utilisateur dont le mod a été refusé ou ne s’est pas chargé trouve la raison dans son journal de débogage. Messages de refus liste les lignes pour allowManagedHooksOnly et disableAllHooks, et Messages du garde-fou intégré a la ligne pour allowManagedModsOnly.
Autoriser uniquement les mods de votre organisation
Pour exécuter les mods de votre organisation et bloquer ceux qu’apportent les utilisateurs, déployez les paramètres de la ligne Uniquement les mods de votre organisation du tableau des politiques, plusdisableSideloadFlags. Avec ce fichier managed-settings.json complet, Claude Code refuse les mods propres des utilisateurs, de sorte qu’aucun de leurs hooks ne s’exécute, et votre mod de politique s’exécute avant les autres mods :
managed-settings.json
extraKnownMarketplaces,enabledPluginsetprependPlugins: installent votre mod pour qu’il compte comme le vôtre, et l’exécutent en premier avec le garde-fou après lui. Installer les mods de votre organisation et définir l’ordre couvre le répertoire vers lequel pointent ces clés.pluginConfigs: définit l’optionallowManagedModsOnlydu garde-fou, pour que Claude Code refuse les mods propres des utilisateurs. Leurs hooks de paramètres, barres de statut et/goalcontinuent de fonctionner.disableSideloadFlags: consultezdisableSideloadFlagspour les flags qu’il rejette au démarrage
claude --debug et lisez le journal de débogage :
- Votre mod : sa ligne
hooks modulecontienttier prepend - Un mod installé par l’utilisateur : une ligne indique
refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Une ligne antérieure indique que le module de hooks de ce mod estloaded, donc cherchez le refus. - Un répertoire de plugin :
claude --plugin-dir ./any-modse termine avec un message qui commence par--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)
Appliquer vos contrôles de plugins aux mods
Un mod est un plugin, donc les façons dont vous gérez les plugins pour votre organisation s’appliquent aussi à un plugin qui contient un mod :- Voir quels plugins se chargent sur l’ensemble de votre parc : Auditer et examiner
- Décider quand un plugin que vous avez examiné peut se mettre à jour : Définir la politique de mise à jour
- Donner à un groupe une politique différente, comme un pilote : Prévoir ce que les paramètres gérés ne peuvent pas imposer
- Vérifier quelles applications et quels types de session appliquent les clés de plugin : Quand chaque surface applique les clés de plugin
- Configurer la CI et les conteneurs : Préparer les conteneurs et la CI
- Proposer des mods que vos utilisateurs peuvent installer : Héberger une marketplace. Un mod que Claude Code copie depuis une source GitHub, git, URL ou npm compte comme celui d’un utilisateur, sauf si vous l’installez comme celui de votre organisation.
Définir les options sur le garde-fou intégré
Le garde-fou intégré prend des options. Définissez-les dans les paramètres gérés souspluginConfigs, indexées par cc-plugin-sec-default@builtin, comme l’exemple dans Arrêter le chargement des mods installés par les utilisateurs le fait.
Le tableau donne ce que vos utilisateurs obtiennent avec chaque option non définie et avec elle définie à true :
Ces règles décident si une option prend effet :
- L’id a une seule orthographe ici : Claude Code lit les options uniquement sous
cc-plugin-sec-default@builtin.prependPluginsaccepte aussisec-default@builtin, etpluginConfigsne le fait pas. - Seuls les paramètres gérés comptent : la même entrée dans un fichier de paramètres utilisateur, projet ou local, ou dans un fichier passé avec
--settings, ne définit ni ne desserre une option - Le garde-fou doit se charger : si vous définissez
prependPlugins, nommez le garde-fou dans la liste. Là où le garde-fou ne se charge pas, aucune option ne s’applique. - Le garde-fou échoue fermé : si le garde-fou ne peut pas lire les paramètres gérés, il refuse tous les mods des utilisateurs au chargement. S’il ne peut pas vérifier les règles de refus pour un appel qu’un mod d’utilisateur a approuvé, il refuse l’appel.
Exécuter les mods de votre organisation
Vous pouvez déployer des mods de votre côté à chaque utilisateur, choisir où ils s’exécutent par rapport aux mods des utilisateurs, et en utiliser un pour appliquer une politique.Installer les mods de votre organisation et définir l’ordre
Les mods de votre organisation se chargent là où les mods des utilisateurs ne le font pas et peuvent s’exécuter avant eux, donc Claude Code doit pouvoir déterminer qu’un mod vient de vous. Pour qu’un mod provenant d’une marketplace distante, comme un dépôt GitHub, compte comme le vôtre sur v2.1.324 ou ultérieure, effectuez toutes ces actions dans les paramètres gérés :- Définissez le plugin du mod à
truedansenabledPlugins - Déclarez la marketplace dans
extraKnownMarketplaces. Pour contrôler quand le code du mod change, épinglez la marketplace et l’entrée du mod. - Listez l’id du mod, comme
acme-guard@acme-tools, dansprependPluginsouappendPlugins. AvecprependPlugins, listez aussisec-default@builtinpour conserver le garde-fou intégré.
- Les
enabledPluginsgérés définissent le plugin du mod àtrue - Les paramètres gérés désignent la marketplace du plugin comme un répertoire sur la machine de l’utilisateur, par chemin absolu. Une entrée
extraKnownMarketplacesle fait et enregistre aussi la marketplace pour l’utilisateur. - La marketplace liste le plugin par un chemin relatif, donc Claude Code le charge sur place à partir de ce répertoire
/opt/acme/claude-plugins/.claude-plugin/marketplace.json
enabledPlugins gérés l’activent. Son mod s’exécute parmi les mods des utilisateurs, prependPlugins et appendPlugins l’ignorent, allowManagedModsOnly le refuse, et allowManagedHooksOnly l’empêche de se charger. Quand les paramètres gérés l’activent, le journal de débogage de l’utilisateur contient une ligne qui commence par l’id du plugin et is enabled by managed settings, but.
Claude Code déclenche un événement chaque fois qu’il est sur le point d’agir, comme exécuter un outil, et le passe à chaque mod à tour de rôle. Un mod qui remplit les conditions relatives au répertoire s’exécute avant les mods des utilisateurs même quand vous ne le listez nulle part. Pour définir sa place, listez son id dans l’un de deux paramètres. L’id est le nom du plugin, @, et le nom de la marketplace, comme acme-guard@acme-tools.
prependPlugins: votre mod voit un événement avant n’importe quel mod d’utilisateur, et le résultat de l’événement après eux. Il peut modifier l’événement, le refuser, ou ignorer les mods des utilisateurs. Sur v2.1.323 ou ultérieure, vérifiez que vos hooks atteignent toujours les contrôles et les dessins des autres mods.appendPlugins: votre mod s’exécute après chaque mod d’utilisateur, donc il voit uniquement les événements que ces mods transmettent, sous la forme dans laquelle ils les transmettent
acme-tools à /opt/acme/claude-plugins, active acme-guard à partir de celle-ci, et exécute ce mod en premier, avec le garde-fou intégré après lui :
managed-settings.json
extraKnownMarketplaces: désigne le répertoire qui contient la marketplaceacme-tools.pathest le chemin absolu du répertoire qui contient.claude-plugin/marketplace.json.enabledPlugins: activeacme-guardpour chaque utilisateur qui reçoit ces paramètres gérésprependPlugins: placeacme-guarden premier et le garde-fou intégré en deuxième, tous deux avant n’importe quel mod qu’un utilisateur installe. Claude Code suit l’ordre que vous listez.
claude --debug et recherchez l’id du mod dans le journal de débogage :
hooks module acme-guard@acme-tools loaded, avectier prepend: le mod compte comme celui de votre organisation et s’exécute en premier- La même ligne avec
tier user: Claude Code le traite comme un mod d’utilisateur. Une deuxième ligne,prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, indique que la liste l’a ignoré.
- La liste remplace la valeur par défaut : quand vous définissez
prependPluginsdans les paramètres gérés, indiquez-ysec-default@builtinpour conserver le garde-fou intégré. Le garde-fou est intégré et n’a besoin d’aucune entréeenabledPlugins. - Vos propres ids doivent compter comme les vôtres : dans les paramètres gérés, Claude Code ignore un id dont le plugin ne remplit pas les conditions d’un mod d’organisation
- Les dépôts ne peuvent définir aucune des deux listes : Claude Code les ignore toutes deux dans le fichier de paramètres d’un dépôt, donc définissez-les dans les paramètres gérés.
- Un utilisateur peut les définir pour ordonner ses propres mods : dans
~/.claude/settings.json, uniquement sur une machine sans paramètres gérés ni fichiermanaged-mcp.json, et uniquement quand les identifiants de la session ne proviennent pas d’un/loginTeam ou Enterprise. Partout ailleurs, Claude Code ignore les deux clés dans les paramètres utilisateur. Une liste à cet endroit n’ajoute ni ne supprime le garde-fou intégré.
Appliquer une politique avec un mod de votre côté
Pour empêcher tous les mods des utilisateurs de se charger, vous n’avez pas besoin d’un mod de votre côté. DéfinissezallowManagedModsOnly. Écrivez un mod de politique quand vous voulez autoriser certains mods d’utilisateurs et en refuser d’autres, ou pour consigner ce que font les mods.
Chaque fois qu’un autre mod est sur le point de se charger, votre mod reçoit la liste que claude plugin validate affiche, dans un événement nommé plugin.register. Un mod dans prependPlugins peut lire cette liste et refuser le mod. Il peut aussi intercepter n’importe quel appel de l’API des mods par son nom pour consigner ou refuser cet appel pour tous les autres mods. Le nom est la méthode sans le $., donc un hook sur fs.write voit chaque appel $.fs.write.
Sur v2.1.323 ou ultérieure, un hook
ui.focus a besoin d’un matcher plus large pour recevoir les appels $.ui.focus des autres mods. Consultez Intercepter les dessins et les contrôles des autres mods.$.process.run ou $.process.spawn. Il tient aussi un journal d’audit, en écrivant dans le journal de débogage chaque appel d’outil et chaque fichier qu’un mod écrit. Comme il s’exécute en premier, le journal consigne ce qui a été demandé, avant qu’un mod d’utilisateur ne le modifie. Enregistrez-le sous acme-guard/hooks/register.js :
acme-guard/hooks/register.js
plugin.register: décide si un autre mod se charge. Il refuse un mod d’utilisateur qui appelle une méthode bloquée et transmet tous les autres mods.tool.call: écrit une ligne commeaudit tool.call Bashdans le journal de débogage pour chaque appel d’outil, et ne modifie rienfs.write: écrit une ligne commeaudit fs.write by reader "/tmp/notes.md"pour chaque appel$.fs.writequ’effectue un autre mod, et ne modifie rien. Le nom du mod vient en premier et le chemin est entre guillemets, de sorte qu’un chemin choisi par un mod ne puisse pas se faire passer pour un autre champ de la ligne.
plugin.register lit deux champs de l’événement :
e.tier: où le mod s’exécuterait, parmiprepend,user,appendoubuiltin. Chaque mod qu’une personne installe estuser.e.uses.calls: les méthodes de l’API des mods que le mod appelle, chacune écritenamespace.methodcommeprocess.run, sans le$.queclaude plugin validateaffiche
$.process.run, le mod ne se charge pas, et son journal de débogage contient une ligne qui se termine par refused by acme-guard: suivi de votre raison. Le refus apparaît aussi dans la transcription d’une session qui recharge à chaud un répertoire de plugin.
Pour bloquer un appel sans refuser le mod entier, retournez { deny: 'your reason' } depuis un hook sur le nom de cet appel, après avoir vérifié qui a effectué l’appel.
Pour envoyer les lignes d’audit ailleurs que dans le journal de débogage, appelez $.http.fetch depuis les mêmes hooks.
Une session peut s’exécuter sans votre mod. Si le thread de travail qui exécute les mods installés plante trois fois, Claude Code décharge tous les mods qui ne sont pas intégrés, y compris le vôtre, jusqu’à ce que l’utilisateur exécute /reload-plugins ou démarre une nouvelle session. Et un utilisateur qui démarre Claude Code avec --safe-mode s’exécute sans mods installés, y compris les vôtres.
Créer un mod couvre les fichiers dont un mod a besoin. Tester un mod de politique propose un fichier de test pour ce mod de politique.
Refuser les mods quand votre vérification échoue
Si votre hookplugin.register lève une exception ou dépasse sa limite de temps, Claude Code ignore le hook, donc la vérification échoue en mode ouvert et le mod qu’il vérifiait se charge. Pour échouer en mode fermé et refuser les mods des utilisateurs, déplacez la vérification dans une fonction nommée et ajoutez un gestionnaire .catch qui retourne le refus. Cette version du fichier montre uniquement le hook plugin.register, donc conservez les deux hooks d’audit de la première version dans register :
acme-guard/hooks/register.js
refused by acme-guard: Acme policy check failed, so this mod was not loaded. Le gestionnaire transmet à next(e) chaque mod en dehors du tier user, donc une vérification échouée n’empêche pas les mods que votre organisation liste. Gérer un hook qui échoue couvre .catch pour les autres événements.
Étapes suivantes
- Sécurité des plugins : ce que n’importe quel plugin peut faire sur la machine d’un utilisateur, et comment en examiner un avant qu’il ne soit installé
- Aperçu des mods : ce qu’est un mod et comment il se compare aux crochets, compétences, et serveurs MCP
- L’ordre dans lequel les mods s’exécutent : comment
prependPluginsetappendPluginss’adaptent aux mods des utilisateurs - Paramètres et variables d’environnement : chaque paramètre nommé sur cette page dans un tableau