Skip to main content
failproofai поставляется с 39 встроенными политиками, которые предотвращают типичные сбои агентов. Каждая политика срабатывает на определённый тип события хука и имя инструмента. Девятнадцать политик принимают параметры, позволяющие настраивать их поведение без написания кода. Пять рабочих политик обеспечивают соблюдение конвейера commit → push → PR → CI перед остановкой Claude.

Обзор

Политики разделены по категориям:
  • block- — остановить агента от продолжения.
  • warn- — дать агенту дополнительный контекст для самокоррекции.
  • sanitize- — удалить чувствительные данные из вывода инструмента перед отправкой агенту.

Пространства имён

Каждая политика находится в слоте <namespace>/<name>. Встроенные политики принадлежат пространству имён failproofai/ — например, failproofai/sanitize-jwt. Пространство имён предотвращает коллизии при загрузке пользовательских или сторонних политик с похожими названиями. В конфиге вы можете ссылаться на встроенную политику либо по краткому имени, либо по полному имени; обе формы разрешаются в одну политику:
Если имя не содержит /, failproofai считает его принадлежащим пространству имён по умолчанию failproofai. Имена, уже содержащие / (например, myorg/foo, custom/my-hook), сохраняются как есть.
  • require- — блокировать событие Stop до выполнения условий.

Каждая политика поддерживает необязательное поле hint в policyParams. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, предоставляя практичное руководство без изменения кода политики. Работает со встроенными, пользовательскими и условными политиками. Подробнее см. Configuration → hint.

Опасные команды

Предотвратите выполнение агентами операций, которые сложно отменить или которые могут повредить хост-систему.

block-sudo

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любую команду sudo.
Блокирует вызовы, содержащие ключевое слово sudo. Сопоставление осуществляется для разобранных токенов команды, а не для сырой строки, что предотвращает обход через инъекции операторов оболочки. Параметры: Пример:
С такой конфигурацией sudo systemctl status nginx разрешена, но sudo rm /etc/hosts запрещена.
Шаблоны сопоставляются с разобранными токенами, а не с сырой командной строкой. Это предотвращает обход через добавленные операторы оболочки (например, sudo systemctl status x; rm -rf / не совпадает с sudo systemctl status *).

block-rm-rf

Событие: PreToolUse (Bash)
По умолчанию: Запрещает rm -rf, rm -fr и аналогичные формы рекурсивного удаления.
Параметры: Пример:

block-curl-pipe-sh

Событие: PreToolUse (Bash)
По умолчанию: Запрещает curl <url> | bash, curl <url> | sh, wget <url> | bash и аналогичные шаблоны.
Нет параметров.

block-failproofai-commands

Событие: PreToolUse (Bash)
По умолчанию: Запрещает команды, которые деинсталлировали бы или отключили бы сам failproofai (например, npm uninstall failproofai, failproofai policies --uninstall).
Нет параметров.

Инфраструктурные команды

Предотвратите выполнение агентами инфраструктурных CLI или запуск конвейеров CI/CD. Все политики в этой категории опциональны (defaultEnabled: false) — агенты, которым действительно требуется вызывать kubectl, terraform и т. д., не будут нарушены, если только вы не включите политику. Если политика включена, любое использование подходящего CLI запрещено, если команда не совпадает с записью в allowPatterns. Грамматика шаблонов совпадает с block-sudo: токены сопоставляются с разобранными argv, * — это подстановочный знак для одного токена, и любая команда, содержащая отдельный оператор оболочки (&&, ||, |, ;) или токен с внедрёнными метасимволами оболочки, отклоняется до проверки разрешённого списка, что предотвращает инъекции.

block-kubectl

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любое использование kubectl.
Параметры: Пример:
С такой конфигурацией kubectl get pods разрешена, но kubectl apply -f deploy.yaml запрещена.

block-terraform

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любое использование terraform или tofu (OpenTofu).
Параметры: Пример:

block-aws-cli

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любое использование AWS CLI.
Параметры: Пример:

block-gcloud

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любое использование gcloud (Google Cloud CLI).
Параметры: Пример:

block-az-cli

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любое использование az (Azure CLI).
Параметры: Пример:

block-helm

Событие: PreToolUse (Bash)
По умолчанию: Запрещает любое использование helm.
Параметры: Пример:

block-gh-pipeline

Событие: PreToolUse (Bash)
По умолчанию: Запрещает следующие подкоманды gh CLI, которые изменяют состояние или запускают конвейеры:
  • gh workflow run, gh workflow enable, gh workflow disable
  • gh run rerun, gh run cancel
  • gh pr merge
  • gh release create, gh release delete
  • gh cache delete
  • gh secret set, gh secret delete
Только для чтения подкоманды gh, такие как gh pr view, gh pr list, gh run list, gh release view и gh api repos/.../... не совпадают с этой политикой — они регулярно требуются для проверок рабочего процесса (включая собственный require-ci-green-before-stop failproofai). Параметры: Пример:

Секреты (санитайзеры)

Предотвратите утечку учётных данных в контекст или выход агента. Политики-санитайзеры срабатывают на событиях PostToolUse. Когда Claude выполняет bash-команду, читает файл или вызывает любой инструмент, эти политики проверяют вывод перед возвратом агенту. Если обнаружен шаблон секрета, политика возвращает решение deny, которое предотвращает передачу вывода обратно.

sanitize-jwt

Событие: PostToolUse (все инструменты)
По умолчанию: Скрывает JWT-токены (три сегмента base64url, разделённые .).
Нет параметров.

sanitize-api-keys

Событие: PostToolUse (все инструменты)
По умолчанию: Скрывает распространённые форматы API-ключей: Anthropic (sk-ant-), OpenAI (sk-), GitHub PATs (ghp_), AWS access keys (AKIA), Stripe keys (sk_live_, sk_test_) и Google API keys (AIza).
Параметры: Пример:

sanitize-connection-strings

Событие: PostToolUse (все инструменты)
По умолчанию: Скрывает строки подключения к БД, содержащие внедрённые учётные данные (например, postgresql://user:password@host/db).
Нет параметров.

sanitize-private-key-content

Событие: PostToolUse (все инструменты)
По умолчанию: Скрывает PEM-блоки (-----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY----- и т. д.).
Нет параметров.

sanitize-bearer-tokens

Событие: PostToolUse (все инструменты)
По умолчанию: Скрывает заголовки Authorization: Bearer <token>, где токен содержит 20 или более символов.
Нет параметров.

Окружение

Защитите чувствительную конфигурацию окружения от чтения или раскрытия агентами.

block-env-files

Событие: PreToolUse (Bash, Read)
По умолчанию: Запрещает чтение файлов .env через cat .env, вызовы инструмента Read с .env в качестве пути файла и т. д.
Не блокирует .envrc или другие файлы окружения — только файлы с точным именем .env. Нет параметров.

protect-env-vars

Событие: PreToolUse (Bash)
По умолчанию: Запрещает команды, которые выводят переменные окружения: printenv, env, echo $VAR.
Нет параметров.

Доступ к файлам

Держите агентов в границах проекта и подальше от чувствительных файлов.

block-read-outside-cwd

Событие: PreToolUse (Read, Bash)
По умолчанию: Запрещает чтение файлов вне корня проекта. Границей является CLAUDE_PROJECT_DIR (устанавливается один раз за сессию Claude Code) с откатом на текущий рабочий каталог сессии, когда переменная не задана. Использование корня проекта вместо текущего cwd означает, что граница остаётся стабильной даже после cd Claude в подкаталог.
Параметры: Пример:

block-secrets-write

Событие: PreToolUse (Write, Edit)
По умолчанию: Запрещает запись в файлы, обычно используемые для приватных ключей и сертификатов: id_rsa, id_ed25519, *.key, *.pem, *.p12, *.pfx.
Параметры: Пример:

Git

Предотвратите случайные push, force-push и ошибки в ветках, которые сложно отменить.

block-push-master

Событие: PreToolUse (Bash)
По умолчанию: Запрещает git push origin main и git push origin master.
Параметры: Пример:
Чтобы разрешить отправку во все ветви (эффективно отключить эту политику без удаления из enabledPolicies), установите protectedBranches: [].

block-work-on-main

Событие: PreToolUse (Bash)
По умолчанию: Запрещает git commit, git merge, git rebase и git cherry-pick при работе дерева на main или master. Создание и переключение ветвей (git checkout, git checkout -b, git switch, git switch -c) не затронуты.
Параметры:

block-force-push

Событие: PreToolUse (Bash)
По умолчанию: Запрещает git push --force и git push -f.
Нет специфичных для политики параметров. Используйте кросс-секционную hint для предложения альтернатив:

warn-git-amend

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude действовать осторожно при выполнении git commit --amend. Не блокирует команду.
Нет параметров.

warn-git-stash-drop

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude подтвердить перед выполнением git stash drop. Не блокирует команду.
Нет параметров.

warn-all-files-staged

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude проверить, что он осуществляет индексирование при выполнении git add -A или git add .. Не блокирует команду.
Нет параметров.

База данных

Перехватите деструктивные SQL-операции перед их выполнением против БД.

warn-destructive-sql

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude подтвердить перед выполнением SQL, содержащего DROP TABLE, DROP DATABASE или DELETE без WHERE-предложения.
Нет параметров.

warn-schema-alteration

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude подтвердить перед выполнением ALTER TABLE-операций.
Нет параметров.

Предупреждения

Дайте агентам дополнительный контекст перед потенциально рискованными, но не деструктивными операциями.

warn-large-file-write

Событие: PreToolUse (Write)
По умолчанию: Инструктирует Claude подтвердить перед записью файлов больше 1024 KB.
Параметры: Пример:
Обработчик хука применяет ограничение stdin в 1 MB на полезные нагрузки. Для тестирования этой политики с малым содержимым установите thresholdKb на значение хорошо ниже 1024.

warn-package-publish

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude подтвердить перед выполнением npm publish.
Нет параметров.

warn-background-process

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude быть осторожным при запуске фоновых процессов через nohup, &, disown или screen.
Нет параметров.

warn-global-package-install

Событие: PreToolUse (Bash)
По умолчанию: Инструктирует Claude подтвердить перед выполнением npm install -g, yarn global add или pip install без виртуального окружения.
Нет параметров.

Менеджеры пакетов

Обеспечьте соблюдение правил о том, какие менеджеры пакетов разрешены агенту.

prefer-package-manager

Событие: PreToolUse (Bash)
По умолчанию: Отключена. При включении блокирует любую команду менеджера пакетов не в списке allowed и говорит Claude переписать команду, используя разрешённый менеджер.
Обнаруживает: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Встроенный список блокировки включает: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Используйте blocked для добавления менеджеров не в этом списке. Пример конфигурации:
С этой конфигурацией как pip install flask, так и pdm install flask запрещены с сообщением, говорящим Claude использовать uv или bun вместо этого. Команды вроде uv pip install flask разрешены, потому что uv в разрешённом списке и проверяется первым.

Поведение AI

Обнаруживайте, когда агенты застревают или ведут себя неожиданно.

warn-repeated-tool-calls

Событие: PreToolUse (все инструменты)
По умолчанию: Инструктирует Claude пересмотреть, когда один и тот же инструмент вызывается 3+ раза с идентичными параметрами — распространённый признак того, что агент застрял в цикле.
Нет параметров.

Рабочий процесс

Обеспечьте дисциплинированный рабочий процесс конца сессии. Эти политики срабатывают на событии Stop и запрещают агенту остановиться, пока не будут выполнены условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика запрещает, последующие политики в цепи пропускаются (deny вызывает короткое замыкание). Все рабочие политики fail-open: если требуемый инструмент недоступен (например, gh не установлена, нет удалённого репозитория), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена.

Семантика Stop для каждого CLI

Применение Stop выглядит немного по-разному в семи поддерживаемых CLI, потому что каждый предоставляет отличающийся контракт хука «агент завершил работу». Результат одинаков — агент не может остановиться, пока шлюз рабочего процесса не пройден — но механика отличается. Таблица ниже суммирует; только Pi имеет заметную для пользователя особенность, стоящую понимания перед включением политики require-*-before-stop.
Ограничение Pi. AgentEndEvent Pi (эквивалент Stop хука Claude) не имеет типа Result — по времени его срабатывания цикл агента Pi уже завершился. Pi не может быть принуждена повторить тот же цикл, как Claude / Copilot / Cursor / OpenCode. failproofai смещает шлюз к событию before_agent_start Pi (которое срабатывает после следующего приглашения пользователя), чтобы проверка рабочего процесса всё ещё применялась, просто при следующем ходе вместо текущего.Что это означает на практике:
  • После остановки Pi причина deny захватывается в памяти с ключом по id сессии Pi. Самое следующее приглашение, которое вы отправляете в той же сессии Pi, его извлекает: LLM видит директиву MANDATORY ACTION REQUIRED в верхней части своего системного приглашения, commit-ит (или push-ит / открывает PR / ждёт CI) и только затем продолжает с вашим запросом. Захваченная причина deny — одноразовая — после извлечения шлюз свободен.
  • Шлюз ограничен временем жизни процесса Pi. Если вы Ctrl+C Pi или выход между ходами, запись в памяти удаляется вместе с процессом и шлюз пропускается. Claude, Copilot, Cursor и OpenCode имеют то же самое ограничение (kill агента и шлюз пропускается) — Pi просто делает это более видимым, потому что агент видимо завершает работу перед срабатыванием шлюза.
  • Ожидающий deny также очищается на session_shutdown по любой причине (new / resume / fork / quit), поэтому устаревший шлюз из предыдущей сессии не может утечь в свежую сессию, начатую в том же процессе Pi.
Если вам нужен повтор в том же цикле, как Claude, запустите ваши политики Stop в любом из пяти других поддерживаемых CLI. Мы отслеживаем Pi upstream на предмет будущего типа Result на AgentEndEvent, который позволил бы нам закрыть этот пробел.

require-commit-before-stop

Событие: Stop
По умолчанию: Запрещает остановку при наличии незафиксированных изменений (изменённые, индексированные или неотслеживаемые файлы). Возвращает информационное сообщение, когда рабочий каталог чист.
Нет параметров.

require-push-before-stop

Событие: Stop
По умолчанию: Запрещает остановку при наличии неотправленных коммитов или когда текущая ветвь не имеет удалённой отслеживаемой ветви. Предлагает git push -u для создания отслеживаемой ветви при необходимости. Fail open, если удалённый репозиторий не настроен.
Параметры: Пример:

require-pr-before-stop

Событие: Stop
По умолчанию: Запрещает остановку при отсутствии pull request для текущей ветви или при закрытом существующем PR без мерджа. Инструктирует Claude создать PR с gh pr create. Когда PR смёрджена, политика разрешает (работа доставлена) и сообщение намекает переключиться с ветви (git checkout main && git pull).
Нет параметров.
Эта политика требует установку и аутентификацию GitHub CLI (gh). Выполните gh auth login с персональным токеном доступа, имеющим область repo для доступа на чтение к pull request-ам. Если gh не установлена или не аутентифицирована, политика fail-open и сообщает причину Claude.

require-no-conflicts-before-stop

Событие: Stop
По умолчанию: Запрещает остановку, когда текущая ветвь не может чисто мержиться в базовую ветвь. Политика сначала подтверждает наличие OPEN PR на GitHub для ветви — без него нет целевого мерджа для применения, поэтому вся политика short-circuit в разрешение. После подтверждения OPEN PR выполняются два независимых зонда:
  1. Локальныйgit merge-tree --write-tree --name-only origin/<baseBranch> HEAD. При конфликте сообщение deny указывает конфликтные файлы, чтобы Claude знал ровно, что разрешить.
  2. GitHub — повторно использует результат gh pr view --json mergeable,state, уже загруженный при предварительной проверке. Перехватывает конфликты, которые устаревший локальный origin/<baseBranch> пропустил бы (например, кто-то посадил конфликтующий PR на main с последней fetch). Результат CONFLICTING запрещает. Результат UNKNOWN также запрещает и инструктирует Claude дождаться ~10 секунд и переповторить проверку перед попыткой остановки снова — это предотвращает ложные отрицания, пока GitHub пересчитывает.
Пропускает полностью (разрешает) при: gh не установлена, нет PR для ветви, состояние PR не OPEN (например, MERGED, CLOSED), или gh pr view возвращает непарсируемый вывод. Также fail-open, когда origin/<baseBranch> отсутствует локально или когда нет коммитов впереди базовой — те Layer 1 pass-through всё ещё консультируются с кэшированной слияемостью PR перед разрешением. Параметры:
GitHub CLI (gh) требуется для этой политики. Политика использует gh pr view для подтверждения наличия OPEN PR перед запуском любого зонда конфликта — без gh политика short-circuit в разрешение. Выполните gh auth login с персональным токеном доступа, имеющим область repo для доступа на чтение к pull request-ам.

require-ci-green-before-stop

Событие: Stop
По умолчанию: Запрещает остановку, когда проверки CI не пройдены или всё ещё выполняются на текущей ветви. Проверяет как GitHub Actions workflow runs, так и сторонние bot checks (например, CodeRabbit, SonarCloud, Codecov). Обрабатывает skipped, cancelled и neutral результаты как не неудачные (последняя категория охватывает, например, Socket Security alerts на PR внешних контрибьюторов, где приложение намеренно сообщает neutral вместо success/failure). Возвращает информационное сообщение, когда все проверки пройдены.
Нет параметров.
Эта политика требует установку и аутентификацию GitHub CLI (gh). Выполните gh auth login с персональным токеном доступа, имеющим область repo для доступа на чтение к Actions workflow runs и Checks API. Если gh не установлена или не аутентифицирована, политика fail-open и сообщает причину Claude.


Отключение отдельных политик

Удалите определённую политику из enabledPolicies в вашей конфигурации или переключите её в таб Policies на дашборде.
Политики не перечисленные в enabledPolicies не запускаются, даже если существуют записи policyParams для них.