claude-guard

Проверяет страну по IP перед каждым запуском claude и отменяет запуск, если попал в чёрный список.

$ claude
detect country...
RU (178.46.80.43)
ru detected

$ claude
detect country...
NL (145.132.14.9)
… запускается claude

Только POSIX sh, из зависимостей — curl и awk. Работает в bash, zsh и fish.

Установка

curl -fsSL https://raw.githubusercontent.com/Egorrko/claude-guard/main/install.sh | sh

Или из клона:

git clone https://github.com/Egorrko/claude-guard.git
cd claude-guard
sh install.sh

Перезапустить шелл (exec fish / exec zsh / exec bash) и проверить:

claude-guard doctor

Опции установщика:

Флаг	Что делает
--block "RU BY"	список блокируемых кодов стран
--no-shell	не трогать конфиги шеллов
--uninstall	снести всё

Через пайп флаги передаются так: curl -fsSL .../install.sh | sh -s -- --block "RU BY".

Как устроен перехват

Два независимых слоя, оба ставятся по умолчанию.

Настоящий бинарник claude не трогается вообще: ни переименований, ни подмен на месте — обновления Claude Code (npm, curl-инсталлер) ничего не ломают и ничего не отключают.

1. PATH shim. В ~/.claude-guard/bin/ лежит исполняемый файл с именем claude, и этот каталог принудительно ставится первым в PATH. Сюда попадает всё, что резолвит команду через PATH: интерактивный ввод, command claude, env claude, вызовы из скриптов и Makefile'ов.

Сниппет не просто дописывает каталог в PATH, а вырезает все предыдущие вхождения и заново ставит в начало. Поэтому повторный сourcing (.zshenv + .zshrc, tmux, вложенные шеллы, path_helper на macOS) не может опустить его ниже.

2. Функция шелла. Функция claude имеет приоритет над поиском по PATH вообще. Она срабатывает даже если что-то потом влезло в начало PATH — то есть страхует первый слой.

Оба слоя ведут в один и тот же ~/.claude-guard/libexec/claude-guard, который ищет настоящий бинарник, пропуская каталог shim'а и себя самого, так что рекурсии не возникает. На всякий случай есть счётчик глубины.

Хуки ставятся в .bashrc, .bash_profile, .zshrc, .zshenv и ~/.config/fish/conf.d/claude-guard.fish. .zshenv важен отдельно: он читается всеми zsh, включая неинтерактивные скрипты.

Что перехватывается, а что нет

Способ запуска	Перехват
claude в терминале	✅
command claude, env claude	✅
вызов из скрипта, унаследовавшего PATH	✅
/usr/local/bin/claude (абсолютный путь)	❌
npx @anthropic-ai/claude-code	❌
GUI-приложение с собственным PATH (VS Code из Dock)	❌
cron / systemd с дефолтным PATH	❌
контейнер, другая машина, env -i	❌

Честная граница

Полной гарантии нет и быть не может: PATH принадлежит пользователю, и любой, у кого есть шелл, обойдёт проверку за пару секунд. Это инструмент против случайного запуска «забыл включить VPN», а не средство контроля против того, кто активно хочет его обойти. Если нужен жёсткий барьер — это уровень файрвола или политики устройства, а не обёртки в PATH.

Конфигурация

~/.claude-guard/config, обычный sh-файл. Любое значение перебивается одноимённой переменной окружения с префиксом CLAUDE_GUARD_.

Ключ	По умолчанию	Смысл
BLOCK	RU	коды стран через пробел
DELAY	1	пауза после вывода страны, сек
TIMEOUT	5	таймаут curl
FAILOPEN	0	1 — пускать, если страну определить не вышло
CACHE_TTL	0	сек кеширования результата, 0 — всегда проверять
ENDPOINT	https://ifconfig.io/all	источник данных

Разово: CLAUDE_GUARD_FAILOPEN=1 claude.

Пауза DELAY автоматически становится нулевой, когда вывод не в терминал, — чтобы не тормозить claude -p ... | jq.

По умолчанию fail-closed: нет сети — запуск отменён. Иначе проверку обходил бы любой случайный обрыв связи.

CACHE_TTL=0 тоже выбран осознанно: с кешем отвалившийся VPN не заметится до истечения TTL. Включай, только если раздражает задержка на запуск.

Команды

claude-guard doctor    # диагностика: PATH, резолв, хуки, текущая страна
claude-guard check     # только проверка страны, код возврата 0/1/2
claude-guard version

doctor — первое, что стоит запускать, если кажется, что проверка не срабатывает.

Тесты

sh tests/run.sh

Гоняются в одноразовом HOME с фейковыми claude и curl, ничего в системе не трогают. Покрыты: блокировка и проброс, отсутствие сети, fail-open, кеш, перехват через shim во всех вариантах вызова, отсутствие рекурсии, идемпотентность установки, принудительное первенство в PATH, установка через curl | sh и полное удаление.

Удаление

sh install.sh --uninstall

Или через пайп: curl -fsSL .../install.sh | sh -s -- --uninstall.

Вычищает блоки из rc-файлов и удаляет ~/.claude-guard. Настоящий бинарник claude не трогался, так что возвращать нечего.

Лицензия

MIT