Gestire i mod per la tua organizzazione

• Escludere i mod degli utenti, con o senza mod tuoi: Impedisci il caricamento dei mod installati dagli utenti
• Vedere cosa ottengono i tuoi utenti se non modifichi nulla: Scopri cosa succede per impostazione predefinita
• Lasciare attivi i mod con altri limiti: Scegli quanto consentire

​

Impedire il caricamento dei mod installati dagli utenti

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

• Nessun mod portato da un utente esegue i propri hook: questo include un mod in un plugin installato dall’utente, un mod caricato con --plugin-dir e un mod scritto da Claude durante una sessione
• I mod della tua organizzazione vengono comunque eseguiti: un mod che conta come appartenente alla tua organizzazione non viene controllato. Ogni altro mod conta come appartenente a un utente e viene rifiutato. Questo include un mod in un plugin che abiliti da GitHub o da un altro marketplace remoto, e uno che la tua organizzazione attiva per i propri membri su claude.ai. Se nessuno conta come tuo, nessun mod installato esegue i propri hook.
• Gli utenti non possono annullarlo: la protezione integrata legge l’opzione solo dalle impostazioni gestite, quindi la stessa voce in un file di impostazioni utente, di progetto o locale, o in un file passato con --settings, non cambia nulla
• Un file o un criterio MDM copre ogni provider: quando distribuisci l’opzione come file o tramite MDM, funziona allo stesso modo su Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry. Per la distribuzione dalla console di amministrazione di claude.ai, consulta Disponibilità delle piattaforme
• Le altre personalizzazioni degli utenti continuano a funzionare: i loro hook nei file di impostazioni e nel file hooks/hooks.json dei plugin, le righe di stato e /goal non sono interessati
• I mod integrati continuano a funzionare: i mod integrati in Claude Code, come il supporto per AGENTS.md, hanno ciascuno il proprio interruttore

​

Sapere cosa succede per impostazione predefinita

• I mod sono attivi. Un utente può installare un plugin che contiene un mod da qualsiasi marketplace consentito dalle tue impostazioni dei plugin, oppure caricarne uno da una directory con --plugin-dir.
• Una protezione integrata viene eseguita per prima. Claude Code carica un mod integrato chiamato sec-default@builtin prima di ogni mod installato da un utente. Gli utenti non possono disattivarlo. /plugin e il log di debug lo elencano come cc-plugin-sec-default. La protezione viene caricata quando è vera una di queste condizioni:
  • La macchina ha impostazioni gestite
  • L’utente ha effettuato l’accesso a Claude Code con un piano Team o Enterprise
  Un utente che si autentica con una chiave API, oppure tramite Amazon Bedrock, Agent Platform di Google Cloud o Microsoft Foundry, ottiene la protezione solo su una macchina che ha impostazioni gestite.
• La protezione tutela ciò che gestisci. Il mod di un utente non può modificare ciò che i tuoi hook gestiti ricevono o decidono, il prompt di sistema, il tuo CLAUDE.md gestito e le altre istruzioni gestite, ciò che qualsiasi mod legge come impostazioni, né gli strumenti e le descrizioni dei tuoi server MCP gestiti.
• Tutto il resto è consentito. La protezione non aggiunge altre restrizioni. Il mod di un utente può comunque leggere e scrivere file, avviare processi, effettuare richieste di rete, riscrivere chiamate agli strumenti e prompt, negare una chiamata a uno strumento, approvarne una che altrimenti richiederebbe conferma e disegnare nell’interfaccia, il tutto con i permessi di quell’utente.
• Le regole deny e i tuoi hook gestiti hanno la precedenza. Dove la protezione viene caricata, il mod di un utente non può approvare una chiamata che una regola deny rifiuta, qualunque sia il file di impostazioni che contiene la regola. Anche un blocco da un hook PreToolUse nelle impostazioni gestite è definitivo. Entrambi si applicano alle chiamate agli strumenti di Claude. Nessuno dei due si applica alle chiamate $.fs e $.process del mod stesso: con Read(.env) negato, un mod può comunque leggere quel file con $.fs.read o avviare un programma che lo fa. Per limitare quelle chiamate, impedisci il caricamento del mod oppure gestisci la chiamata in un mod di criteri.
• Gli altri controlli dei permessi possono essere aggirati. Il mod di un utente che approva le chiamate agli strumenti può approvare una chiamata per cui una regola ask chiederebbe conferma, oppure che un hook PreToolUse esterno alle impostazioni gestite ha bloccato. In modalità auto, una chiamata approvata dal mod viene eseguita senza un controllo del classificatore. Per le richieste di conferma che l’approvazione tool.check di un mod non salta, consulta Estendere i permessi con gli hook.

​

Sapere quali controlli continuano ad applicarsi

• Gli hook delle impostazioni continuano a funzionare. Gli hook di tipo command, HTTP, prompt e agent nei file di impostazioni e in hooks/hooks.json dei plugin vengono eseguiti come prima, insieme ai mod.
• Le regole deny hanno la precedenza dove la protezione viene caricata. Il mod di un utente non può approvare una chiamata che una regola deny rifiuta, a meno che tu non imposti allowModsToOverrideDenyRules.
• Gli hook gestiti vengono eseguiti per primi. Un hook PreToolUse nelle impostazioni gestite viene eseguito prima che qualsiasi mod veda la chiamata allo strumento, e il suo blocco è definitivo. Se poi un mod riscrive la chiamata, i tuoi hook gestiti vengono eseguiti di nuovo sulla chiamata riscritta, quindi un blocco si applica comunque. Gli hook PreToolUse provenienti da altri file di impostazioni e dai plugin vengono eseguiti dopo l’ultimo mod, quindi un mod che restituisce un proprio risultato invece di eseguire lo strumento ne impedisce l’esecuzione. Consulta L’ordine in cui vengono eseguiti i mod.
• La policy di rete copre $.http.fetch.
  • La policy della tua organizzazione non consente WebFetch: Claude Code rifiuta anche ogni richiesta $.http.fetch di qualsiasi mod. Consulta Disponibilità di WebFetch.
  • Disattivi lo strumento WebFetch con CLAUDE_CODE_DISABLE_WEB_FETCH o una regola deny WebFetch, nelle impostazioni gestite o in qualsiasi altro file di impostazioni: i mod possono comunque effettuare richieste $.http.fetch. Per bloccarle per ogni mod installato dai tuoi utenti, impedisci il caricamento dei mod installati dagli utenti, oppure aggancia http.fetch in un mod di criteri e rifiuta le richieste provenienti dai mod degli utenti. Assegna a quell’hook un gestore .catch che a sua volta rifiuti, perché Claude Code salta un hook che fallisce e la richiesta procede comunque. Se ti limiti a restringere quali plugin gli utenti possono installare, vengono caricati meno mod, ma quelli che consenti effettuano comunque queste richieste.
  • Imposti CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: un mod installato da te o dai tuoi utenti può comunque effettuare queste richieste. La variabile blocca solo i mod integrati in Claude Code, più qualsiasi richiesta $.http.fetch che include le credenziali Anthropic della sessione. Prima della v2.1.288, la variabile bloccava ogni richiesta $.http.fetch di qualsiasi mod.
  Nessuno di questi casi copre un programma che il mod avvia con $.process.run, che raggiunge la rete con l’accesso dell’utente stesso.
• I controlli dei plugin coprono i mod. Un mod è un plugin, quindi le impostazioni che limitano ciò che gli utenti possono installare, come strictKnownMarketplaces, decidono se può essere installato o meno.
• I mod non possono modificare la richiesta di permesso. Un mod può cambiare lo stile di gran parte dell’interfaccia di Claude Code, ma non della richiesta di permesso, quindi non può modificare ciò che una richiesta mostra. Un mod può comunque approvare o negare una chiamata a uno strumento prima che compaia la richiesta, come descritto in Sapere cosa succede per impostazione predefinita.
• Le richieste di attendibilità vengono prima. In una sessione interattiva in una directory che l’utente non ha ancora considerato attendibile, nessun mod viene caricato finché l’utente non risponde alla richiesta di attendibilità.
• --safe-mode disattiva i mod installati, compresi i tuoi. Avvia una sessione con claude --safe-mode per verificare se un mod ha causato un problema.

​

Decidi se lasciare attivi i mod

​

Verifica cosa può fare un mod

claude plugin validate ./some-mod

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

​

Scegli quanto consentire

• allowManagedModsOnly: un’opzione della protezione integrata. Claude Code rifiuta i mod degli utenti, quindi nessuno dei loro hook viene eseguito. Gli hook delle impostazioni degli utenti, le righe di stato e /goal continuano a funzionare. Impedire il caricamento dei mod installati dagli utenti elenca cosa copre.
• allowManagedHooksOnly: un’impostazione più ampia. Vengono caricati solo i mod della tua organizzazione e i mod integrati in Claude Code. Un mod installato da un utente non viene caricato. L’impostazione blocca anche gli hook nei file di impostazioni degli utenti. Leggi Cosa viene eseguito con allowManagedHooksOnly prima di impostarla.
• disableAllHooks: l’impostazione più ampia. Nelle impostazioni gestite, blocca i mod in ogni plugin installato, inclusi i tuoi, e disattiva ogni hook nei file di impostazioni, quindi un hook PreToolUse nelle tue impostazioni gestite non blocca più nulla. Anche le righe di stato personalizzate e /goal smettono di funzionare. Leggi disableAllHooks prima di impostarla.
• disableSideloadFlags: rifiuta --plugin-dir e --plugin-url all’avvio, e impedisce il caricamento dei mod che Claude scrive durante una sessione. L’impostazione rifiuta anche --agents e --mcp-config. Leggi disableSideloadFlags prima di impostarla.

​

Consentire solo i mod della tua organizzazione

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"],
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": { "allowManagedModsOnly": true }
    }
  },
  "disableSideloadFlags": true
}

• extraKnownMarketplaces, enabledPlugins e prependPlugins: installano il tuo mod in modo che venga considerato tuo, e lo eseguono per primo con la protezione subito dopo. Installare i mod della tua organizzazione e impostare l’ordine descrive la directory a cui puntano queste chiavi.
• pluginConfigs: imposta l’opzione allowManagedModsOnly della protezione, così Claude Code rifiuta i mod degli utenti. I loro hook delle impostazioni, le righe di stato e /goal continuano a funzionare.
• disableSideloadFlags: consulta disableSideloadFlags per i flag che rifiuta all’avvio

• Il tuo mod: la sua riga hooks module contiene tier prepend
• Un mod installato dall’utente: una riga riporta refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Una riga precedente indica che il modulo degli hook di quel mod è loaded, quindi cerca il rifiuto.
• Una directory di plugin: claude --plugin-dir ./any-mod termina con un messaggio che inizia con --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)

​

Applicare i controlli sui plugin ai mod

• Vedere quali plugin vengono caricati nella tua flotta: Verifica e revisione
• Decidere quando un plugin che hai revisionato può aggiornarsi: Impostare il criterio di aggiornamento
• Assegnare a un gruppo un criterio diverso, ad esempio un gruppo pilota: Pianificare ciò che le impostazioni gestite non possono imporre
• Verificare quali app e tipi di sessione applicano le chiavi dei plugin: Quando ciascuna superficie applica le chiavi dei plugin
• Configurare CI e container: Predisporre container e CI
• Offrire mod che i tuoi utenti possono installare: Ospitare un marketplace. Un mod che Claude Code copia da una sorgente GitHub, git, URL o npm viene considerato di un utente, non della tua organizzazione.

​

Impostare le opzioni della protezione integrata

• L’id ha una sola forma qui: Claude Code legge le opzioni solo sotto cc-plugin-sec-default@builtin. prependPlugins accetta anche sec-default@builtin, mentre pluginConfigs no.
• Contano solo le impostazioni gestite: la stessa voce in un file di impostazioni utente, di progetto o locale, o in un file passato con --settings, non imposta né allenta un’opzione
• La protezione deve essere caricata: se imposti prependPlugins, indica la protezione nell’elenco. Dove la protezione non viene caricata, nessuna delle due opzioni si applica.
• La protezione fallisce in modo chiuso: se la protezione non riesce a leggere le impostazioni gestite, rifiuta ogni mod degli utenti al caricamento. Se non riesce a verificare le regole deny per una chiamata approvata dal mod di un utente, rifiuta la chiamata.

​

Esegui i mod della tua organizzazione

​

Installa i mod della tua organizzazione e imposta l’ordine

• L’impostazione gestita enabledPlugins imposta il plugin del mod su true
• Le impostazioni gestite indicano il marketplace del plugin come una directory sulla macchina dell’utente, tramite percorso assoluto. Una voce extraKnownMarketplaces fa proprio questo e registra anche il marketplace per l’utente.
• Il marketplace elenca il plugin tramite un percorso relativo, così Claude Code lo carica sul posto da quella directory

/opt/acme/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guard/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/
            ├── hooks.json
            └── register.js

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }
  ]
}

• prependPlugins: il tuo mod vede ogni evento prima di qualsiasi mod degli utenti e ogni risultato dopo. Può modificare l’evento, rifiutarlo o saltare i mod degli utenti.
• appendPlugins: il tuo mod viene eseguito dopo ogni mod degli utenti, quindi vede solo gli eventi che quei mod trasmettono, nella forma in cui li trasmettono

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

• extraKnownMarketplaces: indica la directory che contiene il marketplace acme-tools. path è il percorso assoluto della directory che contiene .claude-plugin/marketplace.json.
• enabledPlugins: attiva acme-guard per ogni utente che riceve queste impostazioni gestite
• prependPlugins: mette acme-guard al primo posto e la protezione integrata al secondo, entrambi prima di qualsiasi mod installato da un utente. Claude Code segue l’ordine che elenchi.

• hooks module acme-guard@acme-tools loaded, con tier prepend: il mod viene considerato della tua organizzazione e viene eseguito per primo
• La stessa riga con tier user: Claude Code lo tratta come un mod di un utente. Una seconda riga, prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, indica che l’elenco lo ha ignorato.

• L’elenco sostituisce il valore predefinito: quando imposti prependPlugins nelle impostazioni gestite, includi sec-default@builtin per mantenere la protezione integrata. La protezione è integrata e non richiede una voce enabledPlugins.
• I tuoi id devono essere considerati tuoi: nelle impostazioni gestite, Claude Code ignora un id il cui plugin non soddisfa le condizioni per un mod dell’organizzazione
• I repository non possono impostarle: Claude Code legge entrambe le impostazioni dalle impostazioni gestite e mai dal file di impostazioni di un repository. Un utente può impostarle in ~/.claude/settings.json per ordinare i propri mod solo su una macchina senza impostazioni gestite, e solo quando non ha effettuato l’accesso con un piano Team o Enterprise. In qualsiasi altro caso, Claude Code ignora entrambe le chiavi nelle impostazioni utente. Un elenco lì non aggiunge né rimuove la protezione integrata.

​

Applica un criterio con un tuo mod

// The methods no user's mod may call, each spelled namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Runs each time another mod is about to load
  on('plugin.register', async ($, e, next) => {
    // Keep the calls in that mod's code that are on the blocked list
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Returning refuse keeps the mod from loading, and the text is the reason
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Let every other mod load
    return next(e)
  })

  // Record each tool call, then let it go ahead unchanged
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Record which mod wrote a file, then the path, quoted because the mod chose it
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

• plugin.register: decide se un altro mod viene caricato. Rifiuta un mod di un utente che chiama un metodo bloccato e lascia passare ogni altro mod.
• tool.call: scrive nel log di debug una riga come audit tool.call Bash per ogni chiamata a uno strumento, senza modificare nulla
• fs.write: scrive una riga come audit fs.write by reader "/tmp/notes.md" per ogni chiamata $.fs.write effettuata da un altro mod, senza modificare nulla. Il nome del mod viene prima e il percorso è tra virgolette, così un percorso scelto da un mod non può spacciarsi per un altro campo della riga.

• e.tier: dove verrebbe eseguito il mod, uno tra prepend, user, append o builtin. Ogni mod installato da una persona è user.
• e.uses.calls: i metodi dell’API dei mod che il mod chiama, ciascuno scritto come namespace.method, ad esempio process.run, senza il $. che claude plugin validate stampa

​

Rifiuta i mod quando il tuo controllo fallisce

const BLOCKED_CALLS = ['process.run', 'process.spawn']

// The same check as before, moved into a function of its own
async function checkMod($, e, next) {
  const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
  if (e.tier === 'user' && blocked.length > 0) {
    return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
  }
  return next(e)
}

export function register(on) {
  // The handler runs only when checkMod throws or exceeds its time limit
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Let your organization's mods and built-in mods load
    if (e.tier !== 'user') return next(e)
    // Refuse the user's mod that couldn't be checked
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

​

Passaggi successivi

• Sicurezza dei plugin: cosa può fare qualsiasi plugin sul computer di un utente e come esaminarne uno prima che venga installato
• Panoramica dei mod: cos’è un mod e come si confronta con gli hook, le skill e i server MCP
• L’ordine in cui vengono eseguiti i mod: come prependPlugins e appendPlugins si combinano con i mod degli utenti
• Impostazioni e variabili d’ambiente: tutte le impostazioni citate in questa pagina in un’unica tabella