Vai al contenuto principale
failproofai è dotato di 30 politiche integrate che rilevano le modalità di errore comuni degli agenti. Ogni politica si attiva su un tipo di evento hook e un nome di strumento specifici. Nove politiche accettano parametri che ti consentono di regolarne il comportamento senza scrivere codice. Quattro politiche di workflow applicano una pipeline commit → push → PR → CI prima che Claude si fermi.

​
Panoramica

Le politiche sono raggruppate in categorie:
CategoriaPoliticheTipo di hook
Comandi pericolosiblock-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commandsPreToolUse
Segreti (sanitizer)sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokensPostToolUse
Ambienteblock-env-files, protect-env-varsPreToolUse
Accesso ai fileblock-read-outside-cwd, block-secrets-writePreToolUse
Gitblock-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-stagedPreToolUse
Databasewarn-destructive-sql, warn-schema-alterationPreToolUse
Avvisiwarn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-installPreToolUse
Workflowrequire-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stopStop
  • block- — ferma l’agente dal procedere.
  • warn- — fornisce all’agente contesto aggiuntivo per autocorreggersi.
  • sanitize- — rimuove i dati sensibili dall’output dello strumento prima che l’agente li veda.
  • require- — blocca l’evento Stop fino a quando le condizioni non sono soddisfatte.
Ogni politica supporta un campo hint opzionale in policyParams. L’hint viene aggiunto al messaggio di negazione o istruzione che Claude vede, fornendo indicazioni attuabili senza modificare il codice della politica. Funziona con le politiche integrate, personalizzate e di convenzione. Vedi Configurazione → hint per i dettagli.

​
Comandi pericolosi

Impedisci agli agenti di eseguire operazioni difficili da annullare o che potrebbero danneggiare il sistema host.

​
block-sudo

Evento: PreToolUse (Bash)
Default: Nega qualsiasi comando sudo. Blocca le invocazioni che includono la parola chiave sudo. L’abbinamento del pattern viene eseguito su token di comando analizzati, non sulla stringa grezza, per prevenire il bypass tramite iniezione di operatori shell. Parametri:
ParamTipoDefaultDescrizione
allowPatternsstring[][]Prefissi di comando esatti che sono consentiti. Ogni voce viene confrontata con i token argv analizzati.
Esempio: 
{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}
Con questa configurazione, sudo systemctl status nginx è consentito, ma sudo rm /etc/hosts è negato.
I pattern vengono abbinati ai token analizzati, non alla stringa di comando grezza. Questo previene il bypass tramite operatori shell aggiunti (ad es. sudo systemctl status x; rm -rf / non corrisponde a sudo systemctl status *).

​
block-rm-rf

Evento: PreToolUse (Bash)
Default: Nega rm -rf, rm -fr e forme simili di eliminazione ricorsiva. Parametri:
ParamTipoDefaultDescrizione
allowPathsstring[][]Percorsi che sono sicuri da eliminare ricorsivamente (ad es. /tmp).
Esempio: 
{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}

​
block-curl-pipe-sh

Evento: PreToolUse (Bash)
Default: Nega curl <url> | bash, curl <url> | sh, wget <url> | bash e pattern simili. Nessun parametro.

​
block-failproofai-commands

Evento: PreToolUse (Bash)
Default: Nega comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. npm uninstall failproofai, failproofai policies --uninstall). Nessun parametro.

​
Segreti (sanitizer)

Impedisci agli agenti di divulgare credenziali nel loro contesto o output. Le politiche sanitizer si attivano su eventi PostToolUse. Quando Claude esegue un comando Bash, legge un file o chiama qualsiasi strumento, queste politiche ispezionano l’output prima che venga restituito a Claude. Se viene rilevato un pattern di segreto, la politica restituisce una decisione di negazione che impedisce all’output di essere ripassato.

​
sanitize-jwt

Evento: PostToolUse (tutti gli strumenti)
Default: Redige i token JWT (tre segmenti base64url separati da .). Nessun parametro.

​
sanitize-api-keys

Evento: PostToolUse (tutti gli strumenti)
Default: Redige i formati comuni di chiavi API: Anthropic (sk-ant-), OpenAI (sk-), GitHub PAT (ghp_), chiavi di accesso AWS (AKIA), chiavi Stripe (sk_live_, sk_test_), e chiavi API Google (AIza). Parametri:
ParamTipoDefaultDescrizione
additionalPatterns{ regex: string; label: string }[][]Pattern regex aggiuntivi da trattare come segreti.
Esempio: 
{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}

​
sanitize-connection-strings

Evento: PostToolUse (tutti gli strumenti)
Default: Redige le stringhe di connessione al database che contengono credenziali incorporate (ad es. postgresql://user:password@host/db). Nessun parametro.

​
sanitize-private-key-content

Evento: PostToolUse (tutti gli strumenti)
Default: Redige i blocchi PEM (-----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY-----, ecc.). Nessun parametro.

​
sanitize-bearer-tokens

Evento: PostToolUse (tutti gli strumenti)
Default: Redige le intestazioni Authorization: Bearer <token> dove il token ha 20 o più caratteri. Nessun parametro.

​
Ambiente

Proteggi la configurazione sensibile dell’ambiente dalla lettura o dall’esposizione da parte degli agenti.

​
block-env-files

Evento: PreToolUse (Bash, Read)
Default: Nega la lettura di file .env tramite cat .env, chiamate dello strumento Read con .env come percorso del file, ecc. Non blocca .envrc o altri file correlati all’ambiente - solo file denominati esattamente .env. Nessun parametro.

​
protect-env-vars

Evento: PreToolUse (Bash)
Default: Nega comandi che stampano variabili di ambiente: printenv, env, echo $VAR. Nessun parametro.

​
Accesso ai file

Mantieni gli agenti al lavoro entro i confini del progetto e lontani dai file sensibili.

​
block-read-outside-cwd

Evento: PreToolUse (Read, Bash)
Default: Nega la lettura di file al di fuori della directory di lavoro corrente (root del progetto). Parametri:
ParamTipoDefaultDescrizione
allowPathsstring[][]Prefissi di percorso assoluto consentiti anche se esterni a cwd.
Esempio: 
{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}

​
block-secrets-write

Evento: PreToolUse (Write, Edit)
Default: Nega le scritture su file comunemente utilizzati per chiavi private e certificati: id_rsa, id_ed25519, *.key, *.pem, *.p12, *.pfx. Parametri:
ParamTipoDefaultDescrizione
additionalPatternsstring[][]Pattern di nome file aggiuntivi (stile glob) da bloccare.
Esempio: 
{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}

​
Git

Previeni push accidentali, force-push e errori di branch difficili da annullare.

​
block-push-master

Evento: PreToolUse (Bash)
Default: Nega git push origin main e git push origin master. Parametri:
ParamTipoDefaultDescrizione
protectedBranchesstring[]["main", "master"]Nomi dei branch che non possono essere pushati direttamente.
Esempio: 
{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}
Per consentire il push su tutti i branch (disabilitando effettivamente questa politica senza rimuoverla da enabledPolicies), imposta protectedBranches: [].

​
block-work-on-main

Evento: PreToolUse (Bash)
Default: Nega il checkout diretto dei branch main o master. Parametri:
ParamTipoDefaultDescrizione
protectedBranchesstring[]["main", "master"]Nomi dei branch che non possono essere sottoposti a checkout direttamente.

​
block-force-push

Evento: PreToolUse (Bash)
Default: Nega git push --force e git push -f. Nessun parametro specifico della politica. Usa l’hint cross-cutting hint per suggerire alternative: 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
    }
  }
}

​
warn-git-amend

Evento: PreToolUse (Bash)
Default: Istruisce Claude a procedere con cautela quando esegue git commit --amend. Non blocca il comando. Nessun parametro.

​
warn-git-stash-drop

Evento: PreToolUse (Bash)
Default: Istruisce Claude a confermare prima di eseguire git stash drop. Non blocca il comando. Nessun parametro.

​
warn-all-files-staged

Evento: PreToolUse (Bash)
Default: Istruisce Claude a esaminare ciò che sta preparando quando esegue git add -A o git add .. Non blocca il comando. Nessun parametro.

​
Database

Rileva le operazioni SQL distruttive prima che vengono eseguite nel tuo database.

​
warn-destructive-sql

Evento: PreToolUse (Bash)
Default: Istruisce Claude a confermare prima di eseguire SQL contenente DROP TABLE, DROP DATABASE o DELETE senza una clausola WHERE. Nessun parametro.

​
warn-schema-alteration

Evento: PreToolUse (Bash)
Default: Istruisce Claude a confermare prima di eseguire istruzioni ALTER TABLE. Nessun parametro.

​
Avvisi

Fornisci agli agenti contesto extra prima di operazioni potenzialmente rischiose ma non distruttive.

​
warn-large-file-write

Evento: PreToolUse (Write)
Default: Istruisce Claude a confermare prima di scrivere file più grandi di 1024 KB. Parametri:
ParamTipoDefaultDescrizione
thresholdKbnumber1024Soglia di dimensione del file in kilobyte al di sopra della quale viene emesso un avviso.
Esempio: 
{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}
Il gestore dell’hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuto piccolo, imposta thresholdKb su un valore ben inferiore a 1024.

​
warn-package-publish

Evento: PreToolUse (Bash)
Default: Istruisce Claude a confermare prima di eseguire npm publish. Nessun parametro.

​
warn-background-process

Evento: PreToolUse (Bash)
Default: Istruisce Claude a prestare attenzione quando avvia processi in background tramite nohup, &, disown o screen. Nessun parametro.

​
warn-global-package-install

Evento: PreToolUse (Bash)
Default: Istruisce Claude a confermare prima di eseguire npm install -g, yarn global add o pip install senza un ambiente virtuale. Nessun parametro.

​
Comportamento AI

Rileva quando gli agenti si bloccano o si comportano in modo inaspettato.

​
warn-repeated-tool-calls

Evento: PreToolUse (tutti gli strumenti)
Default: Istruisce Claude a riconsiderare quando lo stesso strumento viene chiamato 3+ volte con parametri identici - un segno comune che l’agente è bloccato in un loop. Nessun parametro.

​
Workflow

Applica un disciplinato workflow di fine sessione. Queste politiche si attivano sull’evento Stop e negano a Claude di fermarsi fino a quando ogni condizione non è soddisfatta. Seguono una naturale catena di dipendenza: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (la negazione cortocircuita). Tutte le politiche di workflow sono fail-open: se lo strumento richiesto non è disponibile (ad es. gh non installato, nessun git remote), la politica consente con un messaggio informativo che spiega perché il controllo è stato saltato.

​
require-commit-before-stop

Evento: Stop
Default: Nega l’arresto quando ci sono modifiche non salvate (file modificati, preparati o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita. Nessun parametro.

​
require-push-before-stop

Evento: Stop
Default: Nega l’arresto quando ci sono commit non pushati o quando il branch corrente non ha alcun branch di tracciamento remoto. Suggerisce git push -u per creare un branch di tracciamento se necessario. Fallisce aperto se nessun remote è configurato. Parametri:
ParamTipoDefaultDescrizione
remotestring"origin"Nome del remote su cui eseguire il push.
Esempio: 
{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}

​
require-pr-before-stop

Evento: Stop
Default: Nega l’arresto quando non esiste alcuna pull request per il branch corrente, o quando la PR esistente è chiusa/merged. Istruisce Claude a creare una PR con gh pr create. Nessun parametro.
Questa politica richiede l’installazione di GitHub CLI (gh) e l’autenticazione. Esegui gh auth login con un personal access token che ha ambito repo per l’accesso in lettura alle pull request. Se gh non è installato o non è autenticato, la politica fallisce aperta e comunica il motivo a Claude.

​
require-ci-green-before-stop

Evento: Stop
Default: Nega l’arresto quando i controlli CI stanno fallendo o sono ancora in esecuzione sul branch corrente. Controlla sia i workflow run GitHub Actions che i controlli bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta le conclusioni skipped come successo. Restituisce un messaggio informativo quando tutti i controlli passano. Nessun parametro.
Questa politica richiede l’installazione di GitHub CLI (gh) e l’autenticazione. Esegui gh auth login con un personal access token che ha ambito repo per l’accesso in lettura ai workflow run di Actions e all’API Checks. Se gh non è installato o non è autenticato, la politica fallisce aperta e comunica il motivo a Claude.

​
Disabilitazione di politiche individuali

Rimuovi una politica specifica da enabledPolicies nella tua configurazione, o disattivala nella scheda Politiche del dashboard. 
{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}
Le politiche non elencate in enabledPolicies non vengono eseguite, anche se esistono voci policyParams per esse.