Passer au contenu principal
failproofai utilise des fichiers de configuration JSON pour contrôler quelles politiques sont actives, leur comportement et l’emplacement des politiques personnalisées. La configuration est conçue pour être facilement partageable avec votre équipe — committez-la dans votre dépôt et chaque développeur bénéficie du même filet de sécurité pour l’agent.

​
Portées de configuration

Il existe trois portées de configuration, évaluées par ordre de priorité :
PortéeChemin du fichierObjectif
project.failproofai/policies-config.jsonParamètres par dépôt, committés dans le contrôle de version
local.failproofai/policies-config.local.jsonSurcharges personnelles par dépôt, ignorées par git
global~/.failproofai/policies-config.jsonParamètres par défaut au niveau utilisateur pour tous les projets
Quand failproofai reçoit un événement de hook, il charge et fusionne les trois fichiers existants pour le répertoire de travail courant.

​
Règles de fusion

enabledPolicies — union des trois portées. Une politique activée à n’importe quel niveau est active. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← union dédupliquée
policyParams — la première portée qui définit les paramètres d’une politique donnée l’emporte entièrement. Il n’y a pas de fusion profonde des valeurs au sein des paramètres d’une politique. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project l'emporte, global ignoré

project:  (aucune entrée block-sudo)
local:    (aucune entrée block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← retombe sur global
customPoliciesPath — la première portée qui le définit l’emporte. llm — la première portée qui le définit l’emporte.

​
Format du fichier de configuration

{
  "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"
}

​
Référence des champs

​
enabledPolicies

Type : string[] Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants de politique affichés par failproofai policies. Consultez Politiques intégrées pour la liste complète. Les politiques absentes de enabledPolicies sont inactives, même si elles ont des entrées dans policyParams.

​
policyParams

Type : Record<string, Record<string, unknown>> Surcharges de paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont spécifiques à chaque politique. Chaque politique documente ses paramètres disponibles dans Politiques intégrées. Si une politique possède des paramètres mais que vous ne les spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas policyParams du tout obtiennent un comportement identique aux versions précédentes. Les clés inconnues dans le bloc de paramètres d’une politique sont silencieusement ignorées au moment du déclenchement du hook, mais signalées comme avertissements lors de l’exécution de failproofai policies.

​
hint (transversal)

Type : string (optionnel) Un message ajouté à la raison lorsqu’une politique retourne deny ou instruct. Utilisez-le pour donner à Claude des indications exploitables sans modifier la politique elle-même. Fonctionne avec n’importe quel type de politique — intégrée, personnalisée (custom/), convention de projet (.failproofai-project/), ou convention utilisateur (.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."
    }
  }
}
Lorsque block-force-push refuse, Claude voit : « Force-pushing is blocked. Try creating a fresh branch instead. » Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si hint n’est pas défini, le comportement est inchangé (rétrocompatible).

​
customPoliciesPath

Type : string (chemin absolu) Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par failproofai policies --install --custom <path> (le chemin est résolu en chemin absolu avant d’être enregistré). Le fichier est chargé à chaque événement de hook — il n’y a pas de mise en cache. Consultez Politiques personnalisées pour les détails de création.

​
Politiques basées sur les conventions

En plus du customPoliciesPath explicite, failproofai découvre et charge automatiquement les fichiers de politiques depuis les répertoires .failproofai/policies/ :
NiveauRépertoirePortée
Projet.failproofai/policies/Partagé avec l’équipe via le contrôle de version
Utilisateur~/.failproofai/policies/Personnel, s’applique à tous les projets
Correspondance de fichiers : Seuls les fichiers correspondant à *policies.{js,mjs,ts} sont chargés (par exemple security-policies.mjs, workflow-policies.js). Les autres fichiers du répertoire sont ignorés. Aucune configuration nécessaire : Les politiques de convention ne nécessitent aucune entrée dans policies-config.json. Déposez simplement les fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook. Chargement par union : Les répertoires de convention du projet et de l’utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à customPoliciesPath qui utilise la règle du premier gagnant). Consultez Politiques personnalisées pour plus de détails et des exemples.

​
llm

Type : object (optionnel) Configuration du client LLM pour les politiques qui effectuent des appels à l’IA. Non requis pour la plupart des configurations. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Gestion de la configuration depuis l’interface en ligne de commande

Les commandes policies --install et policies --uninstall écrivent dans le fichier settings.json de Claude Code (les points d’entrée des hooks), tandis que policies-config.json est le fichier que vous gérez directement. Les deux sont distincts :
  • settings.json — indique à Claude Code d’appeler failproofai --hook <event> à chaque utilisation d’outil
  • policies-config.json — indique à failproofai quelles politiques évaluer et avec quels paramètres
Vous pouvez modifier policies-config.json directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook, sans redémarrage nécessaire.

​
Exemple : configuration au niveau projet avec les paramètres par défaut de l’équipe

Committez .failproofai/policies-config.json dans votre dépôt : 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
Chaque développeur peut ensuite créer .failproofai/policies-config.local.json (ignoré par git) pour ses surcharges personnelles sans affecter ses coéquipiers.