Vai al contenuto principale

​
title: Configurazione description: “Formato del file di configurazione, sistema a tre scope e regole di merge” icon: gear

failproofai utilizza file di configurazione JSON per controllare quali policy sono attive, come si comportano e da dove vengono caricate le policy personalizzate. La configurazione è progettata per essere facilmente condivisibile con il tuo team - committila nel tuo repository e ogni sviluppatore avrà la stessa rete di sicurezza per gli agenti.

​
Scope di configurazione

Esistono tre scope di configurazione, valutati in ordine di priorità:
ScopePercorso del fileScopo
project.failproofai/policies-config.jsonImpostazioni per-repository, committate nel controllo di versione
local.failproofai/policies-config.local.jsonOverride personali per-repository, gitignored
global~/.failproofai/policies-config.jsonImpostazioni predefinite a livello di utente su tutti i progetti
Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente.

​
Regole di merge

enabledPolicies - l’unione di tutti e tre gli scope. Una policy abilitata a qualsiasi livello è attiva. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unione deduplicated
policyParams - il primo scope che definisce i parametri per una determinata policy vince completamente. Non c’è alcun deep merging dei valori all’interno dei parametri di una policy. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vince, global ignorato

project:  (no block-sudo entry)
local:    (no block-sudo entry)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← ricade a global
customPoliciesPath - il primo scope che lo definisce vince. llm - il primo scope che lo definisce vince.

​
Formato del file di configurazione

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

​
Riferimento dei campi

​
enabledPolicies

Type: string[] Elenco dei nomi delle policy da abilitare. I nomi devono corrispondere esattamente agli identificatori delle policy mostrati da failproofai policies. Vedi Built-in Policies per l’elenco completo. Le policy non in enabledPolicies sono inattive, anche se hanno voci in policyParams.

​
policyParams

Type: Record<string, Record<string, unknown>> Override dei parametri per-policy. La chiave esterna è il nome della policy; le chiavi interne sono specifiche della policy. Ogni policy documenta i suoi parametri disponibili in Built-in Policies. Se una policy ha parametri ma non li specifichi, vengono utilizzati i valori predefiniti integrati della policy. Gli utenti che non configurano affatto policyParams ottengono un comportamento identico alle versioni precedenti. Le chiavi sconosciute all’interno del blocco parametri di una policy vengono silenziosamente ignorate al momento dell’attivazione dell’hook ma segnalate come avvisi quando esegui failproofai policies.

​
hint (cross-cutting)

Type: string (optional) Un messaggio aggiunto al motivo quando una policy restituisce deny o instruct. Usalo per dare a Claude una guida praticabile senza modificare la policy stessa. Funziona con qualsiasi tipo di policy — integrata, personalizzata (custom/), convenzione di progetto (.failproofai-project/), o convenzione utente (.failproofai-user/). 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}
Quando block-force-push nega, Claude vede: “Force-pushing is blocked. Try creating a fresh branch instead.” I valori non stringa e le stringhe vuote vengono silenziosamente ignorate. Se hint non è impostato, il comportamento non cambia (retrocompatibile).

​
customPoliciesPath

Type: string (absolute path) Percorso a un file JavaScript contenente policy hook personalizzate. Viene impostato automaticamente da failproofai policies --install --custom <path> (il percorso viene risolto a assoluto prima di essere archiviato). Il file viene caricato nuovo su ogni evento hook - non c’è caching. Vedi Custom Policies per i dettagli di authoring.

​
Policy basate su convenzione

Oltre al customPoliciesPath esplicito, failproofai scopre e carica automaticamente i file di policy dalle directory .failproofai/policies/:
LivelloDirectoryScope
Project.failproofai/policies/Condiviso con il team via controllo di versione
User~/.failproofai/policies/Personale, si applica a tutti i progetti
File matching: Solo i file corrispondenti a *policies.{js,mjs,ts} vengono caricati (ad es. security-policies.mjs, workflow-policies.js). Gli altri file nella directory vengono ignorati. Nessuna configurazione necessaria: Le policy di convenzione non richiedono voci in policies-config.json. Basta eliminare i file nella directory e verranno raccolti al prossimo evento hook. Union loading: Entrambe le directory di convenzione di progetto e utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di customPoliciesPath che utilizza first-scope-wins). Vedi Custom Policies per ulteriori dettagli ed esempi.

​
llm

Type: object (optional) Configurazione del client LLM per le policy che effettuano chiamate AI. Non richiesto per la maggior parte delle configurazioni. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Gestione della configurazione da CLI

I comandi policies --install e policies --uninstall scrivono nel settings.json di Claude Code (i punti di ingresso dell’hook), mentre policies-config.json è il file che gestisci direttamente. I due sono separati:
  • settings.json - dice a Claude Code di chiamare failproofai --hook <event> su ogni tool use
  • policies-config.json - dice a failproofai quali policy valutare e con quali parametri
Puoi modificare policies-config.json direttamente in qualsiasi momento; le modifiche hanno effetto immediatamente al prossimo evento hook senza necessità di riavvio.

​
Esempio: config a livello di progetto con impostazioni predefinite del team

Committa .failproofai/policies-config.json nel tuo repo: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
Ogni sviluppatore può quindi creare .failproofai/policies-config.local.json (gitignored) per override personali senza influenzare i compagni di squadra.