Politiche personalizzate

Le politiche personalizzate trasformano un modello di errore dalle tue tracce o audit in una decisione che viene eseguita mentre un agente lavora. Una politica può consentire un’azione, fornire indicazioni all’agente o negare l’azione prima che causi un altro incidente. Usa una politica personalizzata quando il comportamento dipende dai tuoi strumenti, percorsi, comandi, ambienti o regole operative. Consulta il catalogo delle politiche integrate prima di ricrearne una esistente.

Crea una politica personalizzata

Dashboard
CLI

Vai a Admin → policy editor, seleziona New policy e descrivi l’errore che desideri prevenire.
Aggiungi il codice sorgente della politica, quindi testa i corrispondenze previste e i non-corrispondenze sicuri nell’editor. Risolvi ogni errore di convalida.
Salva la bozza e seleziona Publish version per creare una versione immutabile.
Vai a Admin → enforcement, distribuisci la versione a una macchina di test in modalità observe e verifica le sue decisioni sotto Observe → policy prima di applicarla.

Crea .failproofai/policies/checkout-policies.ts. Il nome del file deve terminare con policies.js, policies.mjs o policies.ts.
Registra una o più politiche con customPolicies.add().
Valida e installa il file con failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Attiva un’azione corrispondente e un’azione sicura. Esegui failproofai policies, quindi ispeziona le decisioni attribuite sotto Observe → policy.

Inizia con una regola ristretta

Questa politica blocca i comandi Kubernetes distruttivi solo quando il comando ha come bersaglio la produzione. Tutto ciò che è al di fuori di quel preciso modello di errore restituisce 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.",
    );
  },
});

Le buone politiche sono abbastanza ristrette da poter essere spiegate in una frase. Corrisponde all’azione osservabile, non all’intento che speriamo avesse l’agente, e restituisci allow() non appena la regola non si applica.

Scegli una decisione

Helper	Risultato	Usalo quando
`allow(reason?)`	L’operazione continua.	La politica non si applica o l’azione è sicura.
`instruct(reason)`	L’operazione continua con guida dove il harness la supporta.	Desideri indirizzare l’agente verso un approccio migliore senza applicare un invariante.
`deny(reason)`	L’operazione viene bloccata quando l’evento e l’harness supportano il blocco.	L’azione non deve procedere.

Scrivi il motivo per l’agente che deve recuperare. Spiega cosa è stato rilevato e cosa dovrebbe fare invece.

Non usare instruct() per un limite di sicurezza. La consegna delle indicazioni varia a seconda dell’harness dell’agente. Usa deny() quando l’azione deve essere impedita.

Oggetto politica

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

Campo	Obbligatorio	Descrizione
`name`	Sì	Identificatore stabile per la politica. Mantieni i nomi univoci tra i file.
`description`	No	Scopo leggibile dall’uomo mostrato negli elenchi delle politiche e nelle decisioni.
`match.events`	No	Tipi di evento che invocano la politica. Omettere `match` la invoca per ogni evento disponibile.
`fn`	Sì	Funzione sincrona o asincrona che restituisce un risultato `allow`, `instruct` o `deny`.

Filtra gli strumenti all’interno di fn. match.toolNames non fa parte del tipo personalizzato di politica pubblica.

Contesto della politica

Ogni politica riceve un PolicyContext.

Campo	Tipo	Cosa contiene
`eventType`	`HookEventType`	Evento normalizzato attualmente valutato.
`toolName`	`string \| undefined`	Nome dello strumento canonico come `Bash`, `Read`, `Write` o `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Input canonico per la chiamata dello strumento attuale.
`payload`	`Record<string, unknown>`	Payload completo dell’evento normalizzato.
`session`	`SessionMetadata \| undefined`	ID della sessione, directory di lavoro, percorso della trascrizione, modalità di permesso e metadati dell’harness quando disponibili.
`cli`	`string \| undefined`	Harness dell’agente sorgente, come `claude`, `codex` o `cursor`.
`params`	`Record<string, unknown>`	Parametri delle politiche integrate. Le politiche personalizzate attualmente ricevono un oggetto vuoto.

Tratta ogni valore opzionale come genuinamente opzionale. Le versioni dell’agente e i tipi di evento non forniscono tutti gli stessi campi.

Input degli strumenti comuni

Failproof AI normalizza gli strumenti comuni su tutti gli harness supportati in modo che una politica possa solitamente usare una forma di input.

Strumento	Campi comuni
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Usa coercizione difensiva perché i valori di input dello strumento sono tipizzati come unknown:

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

Scegli l’evento

Evento	Quando viene eseguito	Uso tipico
`PreToolUse`	Prima che uno strumento viene eseguito.	Blocca o guida comandi, scritture, letture e azioni esterne.
`PostToolUse`	Dopo che uno strumento restituisce.	Ispeziona i risultati prima che raggiungano l’agente. Un deny blocca il risultato intero; non redige campi selezionati.
`PermissionRequest`	Quando l’agente richiede un permesso.	Applica regole di permesso specifiche dell’organizzazione.
`UserPromptSubmit`	Prima che un prompt inviato continui.	Rifiuta istruzioni vietate o aggiungi guida del flusso di lavoro.
`Stop`	Quando l’agente tenta di finire.	Richiedi una condizione di completamento raggiungibile, come un passo di verifica locale.
`SubagentStop`	Quando un subagente tenta di finire.	Limita il lavoro delegato prima che ritorni al padre.
`SessionStart` / `SessionEnd`	Ai confini della sessione.	Registra o controlla lo stato a livello di sessione.

La disponibilità dell’evento e il comportamento di blocco dipendono dall’harness dell’agente. Vedi Agent harnesses prima di basarsi su un evento in una flotta mista.

Tutti i nomi degli eventi della politica

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 e Setup.

Crea modelli di politiche comuni

Blocca le scritture in percorsi protetti

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.");
  },
});

Fornisci indicazioni non vincolanti

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.");
  },
});

Limita il completamento della sessione

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 evento Stop negato può far riprovare l’agente. Limita solo a una condizione che l’agente può soddisfare nell’ambiente attuale e circoscrivi ogni chiamata di subprocess o rete.

Carica file di politica

File di convenzione

I file di convenzione vengono caricati automaticamente:

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

Vengono caricate sia le directory delle politiche del progetto che quelle dell’utente.
I file vengono caricati alfabeticamente all’interno di ogni directory.
Un file deve terminare con policies.js, policies.mjs o policies.ts.
Sono supportate più chiamate customPolicies.add() in un file.
Sono supportati i relativi import da moduli locali.
Le politiche del progetto possono essere commitmate in modo che le stesse regole seguano il repository.

File espliciti

Usa percorsi espliciti quando la convalida o la configurazione dovrebbe denominare direttamente il file di ingresso:

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

I file espliciti vengono caricati per primi, seguiti dai file di convenzione del progetto e poi dai file di convenzione dell’utente. Un file scoperto in entrambi i percorsi viene caricato una volta.

Valida e testa

La convalida esegue il modulo attraverso il loader di produzione e conferma che registra almeno una politica.

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

La convalida rileva file mancanti, errori di sintassi, import non risolti, eccezioni di primo livello e timeout di caricamento dei moduli. Non prova che la tua logica di corrispondenza sia corretta. Testa almeno questi casi:

Un’azione che deve corrispondere e produrre il motivo della politica previsto.
Un’azione vicina ma sicura che deve restituire allow().
Campi dello strumento mancanti o malformati.
Sintassi alternativa di comandi, percorsi, virgolette, maiuscole/minuscole e spazi bianchi.
Una dipendenza di subprocess o rete non disponibile.

Attribuisci il risultato alla tua politica personalizzata sotto Observe → policy. Un test bloccato non è sufficiente se una diversa politica integrata ha preso la decisione.

Comportamento a runtime

Le politiche integrate vengono valutate prima delle politiche personalizzate.
Il primo deny interrompe l’ulteriore valutazione della politica.
Più risultati instruct possono essere combinati quando nessuna politica nega l’evento.
Una funzione di politica ha una scadenza di esecuzione di 10 secondi.
Un’eccezione lanciata o un timeout viene registrato e trattato come allow().
Un file di convenzione che non riesce a caricarsi viene saltato; altri file personalizzati e le politiche integrate continuano.
Il caricamento del modulo di primo livello ha anche una scadenza di 10 secondi.
La modalità observe del cloud esegue la politica ma registra una decisione non consentire senza applicarla.

Mantieni i moduli di politica deterministici e veloci. Evita le chiamate di rete di primo livello o l’avvio del server. Circoscrivi il lavoro all’interno di fn, cattura i guasti di dipendenza e scegli deliberatamente se quel guasto dovrebbe consentire o negare l’operazione.

Esportazioni API

Esportazione	Scopo
`customPolicies.add(policy)`	Registra una politica personalizzata quando il modulo viene caricato.
`allow(reason?)`	Consenti l’operazione.
`instruct(reason)`	Consenti l’operazione e fornisci guida dove supportata.
`deny(reason)`	Blocca l’operazione dove supportata.
`getCustomHooks()`	Restituisce le politiche attualmente registrate nel registro del modulo.
`clearCustomHooks()`	Cancella quel registro, principalmente per test e loader.

TypeScript esporta PolicyContext, PolicyResult, CustomHook, PolicyDecision e PolicyFunction.

Distribuisci politiche personalizzate

Pubblica una versione, distribuiscila in modalità observe, verifica le decisioni e passa all’enforcement.

Connect your agents

Reference

Politiche personalizzate

Crea una politica personalizzata

Inizia con una regola ristretta

Scegli una decisione

Oggetto politica

Contesto della politica

Input degli strumenti comuni

Scegli l’evento

Crea modelli di politiche comuni

Blocca le scritture in percorsi protetti

Fornisci indicazioni non vincolanti

Limita il completamento della sessione

Carica file di politica

File di convenzione

File espliciti

Valida e testa

Comportamento a runtime

Esportazioni API

Distribuisci politiche personalizzate

​Crea una politica personalizzata

​Inizia con una regola ristretta

​Scegli una decisione

​Oggetto politica

​Contesto della politica

​Input degli strumenti comuni

​Scegli l’evento

​Crea modelli di politiche comuni

​Blocca le scritture in percorsi protetti

​Fornisci indicazioni non vincolanti

​Limita il completamento della sessione

​Carica file di politica

​File di convenzione

​File espliciti

​Valida e testa

​Comportamento a runtime

​Esportazioni API

Distribuisci politiche personalizzate

Crea una politica personalizzata

Inizia con una regola ristretta

Scegli una decisione

Oggetto politica

Contesto della politica

Input degli strumenti comuni

Scegli l’evento

Crea modelli di politiche comuni

Blocca le scritture in percorsi protetti

Fornisci indicazioni non vincolanti

Limita il completamento della sessione

Carica file di politica

File di convenzione

File espliciti

Valida e testa

Comportamento a runtime

Esportazioni API