Обзор
Политики разделены по категориям:block-— остановить агента от продолжения.warn-— дать агенту дополнительный контекст для самокоррекции.sanitize-— удалить чувствительные данные из вывода инструмента перед отправкой агенту.
Пространства имён
Каждая политика находится в слоте<namespace>/<name>. Встроенные политики принадлежат пространству имён failproofai/ — например, failproofai/sanitize-jwt. Пространство имён предотвращает коллизии при загрузке пользовательских или сторонних политик с похожими названиями.
В конфиге вы можете ссылаться на встроенную политику либо по краткому имени, либо по полному имени; обе формы разрешаются в одну политику:
/, failproofai считает его принадлежащим пространству имён по умолчанию failproofai. Имена, уже содержащие / (например, myorg/foo, custom/my-hook), сохраняются как есть.
require-— блокировать событие Stop до выполнения условий.
Опасные команды
Предотвратите выполнение агентами операций, которые сложно отменить или которые могут повредить хост-систему.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 disablegh run rerun,gh run cancelgh pr mergegh release create,gh release deletegh cache deletegh 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.
Параметры:
Пример:
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+CPi или выход между ходами, запись в памяти удаляется вместе с процессом и шлюз пропускается. Claude, Copilot, Cursor и OpenCode имеют то же самое ограничение (kill агента и шлюз пропускается) — Pi просто делает это более видимым, потому что агент видимо завершает работу перед срабатыванием шлюза. - Ожидающий deny также очищается на
session_shutdownпо любой причине (new/resume/fork/quit), поэтому устаревший шлюз из предыдущей сессии не может утечь в свежую сессию, начатую в том же процессе Pi.
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 выполняются два независимых зонда:
- Локальный —
git merge-tree --write-tree --name-only origin/<baseBranch> HEAD. При конфликте сообщение deny указывает конфликтные файлы, чтобы Claude знал ровно, что разрешить. - 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 для них.
