Politiques personnalisées

Les politiques personnalisées transforment un schéma de défaillance issu de vos traces ou audits en une décision exécutée pendant qu’un agent travaille. Une politique peut autoriser une action, fournir des conseils à l’agent ou bloquer l’action avant qu’elle ne provoque un nouvel incident. Utilisez une politique personnalisée lorsque le comportement dépend de vos outils, chemins, commandes, environnements ou règles de fonctionnement. Consultez d’abord le pack de politiques Failproof AI pour ne pas recréer un contrôle existant.

Créer une politique personnalisée

Tableau de bord
CLI

Allez dans Admin → éditeur de politiques, sélectionnez Nouvelle politique et décrivez la défaillance que vous souhaitez prévenir.
Ajoutez le code source de la politique, puis testez les correspondances attendues et les non-correspondances sûres dans l’éditeur. Résolvez toutes les erreurs de validation.
Enregistrez le brouillon et sélectionnez Publier la version pour créer une version immuable.
Allez dans Admin → application, déployez la version sur une machine de test en mode observation et vérifiez ses décisions sous Observer → politique avant de l’appliquer.

Créez .failproofai/policies/checkout-policies.ts. Le nom de fichier doit se terminer par policies.js, policies.mjs ou policies.ts.
Enregistrez une ou plusieurs politiques avec customPolicies.add().
Validez et installez le fichier avec failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Déclenchez une action correspondante et une action sûre. Exécutez failproofai policies, puis inspectez les décisions attribuées sous Observer → politique.

Commencer par une règle ciblée

Cette politique bloque les commandes Kubernetes destructives uniquement lorsque la commande cible la production. Tout ce qui se situe en dehors de ce cas de défaillance précis renvoie allow().

import { customPolicies, allow, deny } from "failproofai";

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

Les bonnes politiques sont suffisamment ciblées pour pouvoir être expliquées en une seule phrase. Ciblez l’action observable — pas l’intention que vous espérez de l’agent — et renvoyez allow() dès que la règle ne s’applique pas.

Choisir une décision

Aide	Résultat	Quand l’utiliser
`allow(reason?)`	L’opération continue.	La politique ne s’applique pas ou l’action est sûre.
`instruct(reason)`	L’opération continue avec des conseils lorsque l’environnement d’exécution le permet.	Vous souhaitez orienter l’agent vers une meilleure approche sans appliquer une invariante.
`deny(reason)`	L’opération est bloquée lorsque l’événement et l’environnement d’exécution prennent en charge le blocage.	L’action ne doit pas être effectuée.

Rédigez la raison à l’intention de l’agent qui doit récupérer la situation. Expliquez ce qui a été détecté et ce qu’il devrait faire à la place.

N’utilisez pas instruct() pour délimiter une frontière de sécurité. La livraison des conseils varie selon l’environnement d’exécution de l’agent. Utilisez deny() lorsque l’action doit être empêchée.

Objet de politique

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

Champ	Requis	Description
`name`	Oui	Identifiant stable pour la politique. Assurez-vous que les noms sont uniques entre les fichiers.
`description`	Non	Objectif lisible par l’humain, affiché dans les listes de politiques et les décisions.
`match.events`	Non	Types d’événements qui invoquent la politique. Omettre `match` l’invoque pour chaque événement disponible.
`fn`	Oui	Fonction synchrone ou asynchrone qui renvoie un résultat `allow`, `instruct` ou `deny`.

Filtrez les outils à l’intérieur de fn. match.toolNames ne fait pas partie du type de politique personnalisée public.

Contexte de politique

Chaque politique reçoit un PolicyContext.

Champ	Type	Ce qu’il contient
`eventType`	`HookEventType`	Événement normalisé en cours d’évaluation.
`toolName`	`string \| undefined`	Nom canonique de l’outil, tel que `Bash`, `Read`, `Write` ou `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Entrée canonique pour l’appel d’outil actuel.
`payload`	`Record<string, unknown>`	Charge utile d’événement normalisée complète.
`session`	`SessionMetadata \| undefined`	ID de session, répertoire de travail, chemin de la transcription, mode de permission et métadonnées de l’environnement d’exécution lorsqu’ils sont disponibles.
`cli`	`string \| undefined`	Environnement d’exécution de l’agent source, tel que `claude`, `codex` ou `cursor`.
`params`	`Record<string, unknown>`	Paramètres de politique intégrés. Les politiques personnalisées reçoivent actuellement un objet vide.

Traitez chaque valeur optionnelle comme réellement optionnelle. Les versions d’agent et les types d’événements ne fournissent pas tous les mêmes champs.

Entrées d’outils courantes

Failproof AI normalise les outils courants entre les environnements d’exécution pris en charge, de sorte qu’une politique peut généralement utiliser une seule forme d’entrée.

Outil	Champs courants
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Utilisez une coercition défensive car les valeurs d’entrée des outils sont typées comme unknown :

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

Choisir l’événement

Événement	Quand il s’exécute	Utilisation typique
`PreToolUse`	Avant l’exécution d’un outil.	Bloquer ou guider les commandes, les écritures, les lectures et les actions externes.
`PostToolUse`	Après le retour d’un outil.	Inspecter les résultats avant qu’ils n’atteignent l’agent. Un deny bloque l’intégralité du résultat ; il ne rédige pas les champs sélectionnés.
`PermissionRequest`	Lorsque l’agent demande une autorisation.	Appliquer des règles d’autorisation spécifiques à l’organisation.
`UserPromptSubmit`	Avant qu’une invite soumise ne continue.	Rejeter les instructions interdites ou ajouter des conseils de flux de travail.
`Stop`	Lorsque l’agent tente de terminer.	Exiger une condition de complétion accessible, telle qu’une étape de vérification locale.
`SubagentStop`	Lorsqu’un sous-agent tente de terminer.	Valider le travail délégué avant qu’il ne retourne au parent.
`SessionStart` / `SessionEnd`	Aux limites de session.	Enregistrer ou vérifier l’état au niveau de la session.

La disponibilité des événements et le comportement de blocage dépendent de l’environnement d’exécution de l’agent. Consultez Environnements d’exécution des agents avant de vous appuyer sur un événement dans une flotte mixte.

Tous les noms d'événements de politique

SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, UserPromptExpansion, PostToolBatch, et Setup.

Créer des modèles de politiques courants

Bloquer les écritures vers des chemins protégés

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

Fournir des conseils non bloquants

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

Conditionner la fin de session

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Un événement Stop refusé peut amener l’agent à réessayer. Ne conditionnez qu’à une condition que l’agent peut satisfaire dans l’environnement actuel, et limitez chaque sous-processus ou appel réseau.

Charger des fichiers de politique

Fichiers de convention

Les fichiers de convention se chargent automatiquement :

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

Les répertoires de politiques du projet et de l’utilisateur sont tous deux chargés.
Les fichiers se chargent par ordre alphabétique dans chaque répertoire.
Un fichier doit se terminer par policies.js, policies.mjs ou policies.ts.
Plusieurs appels customPolicies.add() dans un même fichier sont pris en charge.
Les imports relatifs depuis des modules locaux sont pris en charge.
Les politiques de projet peuvent être archivées afin que les mêmes règles suivent le dépôt.

Fichiers explicites

Utilisez des chemins explicites lorsque la validation ou la configuration doit nommer directement le fichier d’entrée :

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

Les fichiers explicites se chargent en premier, suivis des fichiers de convention du projet puis des fichiers de convention utilisateur. Un fichier découvert via les deux chemins n’est chargé qu’une seule fois.

Valider et tester

La validation exécute le module via le chargeur de production et confirme qu’il enregistre au moins une politique.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

La validation détecte les fichiers manquants, les erreurs de syntaxe, les imports non résolus, les exceptions de niveau supérieur et les délais d’expiration de chargement de module. Elle ne prouve pas que votre logique de correspondance est correcte. Testez au moins ces cas :

Une action qui doit correspondre et produire la raison de politique prévue.
Une action proche mais sûre qui doit renvoyer allow().
Des champs d’outil manquants ou malformés.
Une syntaxe de commande alternative, des chemins, des guillemets, des casses et des espaces blancs variés.
Un sous-processus ou une dépendance réseau indisponible.

Attribuez le résultat à votre politique personnalisée sous Observer → politique. Un test bloqué n’est pas suffisant si c’est une politique intégrée différente qui a pris la décision.

Comportement à l’exécution

Les politiques intégrées sont évaluées avant les politiques personnalisées.
Le premier deny arrête l’évaluation des politiques suivantes.
Plusieurs résultats instruct peuvent être combinés lorsqu’aucune politique ne refuse l’événement.
Une fonction de politique dispose d’un délai d’exécution de 10 secondes.
Une exception levée ou un délai d’expiration est enregistré et traité comme allow().
Un fichier de convention qui échoue au chargement est ignoré ; les autres fichiers personnalisés et les politiques intégrées continuent.
Le chargement de module de niveau supérieur dispose également d’un délai de 10 secondes.
Le mode observation cloud exécute la politique mais enregistre une décision non-allow sans l’appliquer.

Gardez les modules de politique déterministes et rapides. Évitez les appels réseau de niveau supérieur ou le démarrage de serveur. Limitez le travail à l’intérieur de fn, gérez les échecs de dépendance et choisissez délibérément si cet échec doit autoriser ou bloquer l’opération.

Exports de l’API

Export	Objectif
`customPolicies.add(policy)`	Enregistrer une politique personnalisée lors du chargement du module.
`allow(reason?)`	Autoriser l’opération.
`instruct(reason)`	Autoriser l’opération et fournir des conseils là où c’est pris en charge.
`deny(reason)`	Bloquer l’opération là où c’est pris en charge.
`getCustomHooks()`	Retourner les politiques actuellement enregistrées dans le registre du module.
`clearCustomHooks()`	Effacer ce registre, principalement pour les tests et les chargeurs.

TypeScript exporte PolicyContext, PolicyResult, CustomHook, PolicyDecision et PolicyFunction.

Déployer des politiques personnalisées

Publiez une version, déployez-la en mode observation, vérifiez les décisions et passez à l’application.

Connect your agents

Reference

Politiques personnalisées

Créer une politique personnalisée

Commencer par une règle ciblée

Choisir une décision

Objet de politique

Contexte de politique

Entrées d’outils courantes

Choisir l’événement

Créer des modèles de politiques courants

Bloquer les écritures vers des chemins protégés

Fournir des conseils non bloquants

Conditionner la fin de session

Charger des fichiers de politique

Fichiers de convention

Fichiers explicites

Valider et tester

Comportement à l’exécution

Exports de l’API

Déployer des politiques personnalisées

​Créer une politique personnalisée

​Commencer par une règle ciblée

​Choisir une décision

​Objet de politique

​Contexte de politique

​Entrées d’outils courantes

​Choisir l’événement

​Créer des modèles de politiques courants

​Bloquer les écritures vers des chemins protégés

​Fournir des conseils non bloquants

​Conditionner la fin de session

​Charger des fichiers de politique

​Fichiers de convention

​Fichiers explicites

​Valider et tester

​Comportement à l’exécution

​Exports de l’API

Déployer des politiques personnalisées

Créer une politique personnalisée

Commencer par une règle ciblée

Choisir une décision

Objet de politique

Contexte de politique

Entrées d’outils courantes

Choisir l’événement

Créer des modèles de politiques courants

Bloquer les écritures vers des chemins protégés

Fournir des conseils non bloquants

Conditionner la fin de session

Charger des fichiers de politique

Fichiers de convention

Fichiers explicites

Valider et tester

Comportement à l’exécution

Exports de l’API