AI Mayak
Начать

Библиотека · Приёмы опытных

Разрешения и безопасность

Строитель45 минОбновлено: октябрь 2026
45 из 105 в библиотеке

Модуль: 9. Продвинутые возможности | Время: ~25 мин теории + 20 мин практики

Суть урока

Агент (автономный исполнитель) с ключами от всех дверей — это потенциальная катастрофа. Безопасность в AI-разработке — не бюрократия, а архитектура: правильно выстроенные границы защищают тебя, клиента и репутацию.

Термины урока: permission (разрешение — право выполнять действие), API (эй-пи-ай — интерфейс программирования), agent (агент — автономный исполнитель), MCP (эм-си-пи — протокол контекста модели), bash (баш — язык команд терминала), git (гит — система контроля версий), hook (хук — скрипт-реакция на событие), sandbox (сэндбокс — изолированная тестовая среда), token (токен — единица текста для AI), settings.json (файл настроек проекта), workflow (воркфлоу — рабочий процесс).

Ключевые концепции

  • .env — единственное место для секретов
  • Режимы разрешений (permissions) Claude Code и когда их применять
  • Хранение секретов в продакшене (production — рабочая среда)
  • Ограничение доступа суб-агентов как защита от случайных поломок

Теория

.env — хранилище секретов

🎨 Образ: .env — сейф в подсобке. Код — это витрина магазина. Деньги на витрине не хранят. Секреты — в сейфе, за железной дверью.

Файл .env — это изолированное хранилище чувствительных данных: API-ключей, токенов (единиц текста для AI), паролей. Он живёт в корне проекта и никогда не попадает в репозиторий (хранилище кода).

Пример структуры .env:

Код
OPENAI_API_KEY=sk-proj-abc123...
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
TELEGRAM_BOT_TOKEN=7123456789:AAF...
STRIPE_SECRET_KEY=sk_live_...

В коде ты обращаешься к этим значениям через переменные окружения:

python
import os
api_key = os.environ.get("OPENAI_API_KEY")

или в Node.js:

javascript
const apiKey = process.env.OPENAI_API_KEY;

Почему НИКОГДА не хардкодить ключи в код:

GitHub и другие платформы активно сканируют публичные репозитории на паттерны вроде sk-ant-, sk-proj-, AIza, Bearer . Если ключ попал в коммит — он считается скомпрометированным. Злоумышленники используют автоматические сканеры и могут начать тратить твои деньги через несколько минут после пуша.

Даже если репозиторий приватный — утечки случаются: случайная смена видимости, добавление коллаборатора, форк. Правило одно: секрет, который хоть раз попал в Git-историю, считается публичным.

.gitignore — первая линия защиты

🎨 Образ: .gitignore — список «не упаковывать» при переезде. Коробки уйдут в грузовик (публичный репозиторий), но сейф с документами — нет. Если забыл — сейф уедет вместе со всеми коробками, и все на новом месте увидят что внутри.

До первого git commit обязательно добавь .env в .gitignore:

Код
# .gitignore
.env
.env.local
.env.*.local
*.pem
*.key
node_modules/

Проверка — запусти git status перед коммитом. Файл .env не должен появляться в списке изменений. Если появился — остановись.

Режимы разрешений Claude Code

🎨 Образ: Режимы разрешений — как уровни доверия к подрядчику. Plan mode — он только смотрит и рисует чертёж. Manual — каждый гвоздь согласовывает с тобой. Accept edits — правки делает сам, а за остальным приходит спросить. Auto — работает сам, а за ним присматривает отдельный проверяющий. Bypass — ключи от всего здания, включая подвал.

Claude Code предоставляет гибкую систему контроля над тем, что может делать агент. Выбор режима зависит от степени доверия к задаче. Режимы переключаются клавишей Shift+Tab прямо в сессии или флагом --permission-mode при запуске. На октябрь 2026 доступно шесть режимов; список меняется, поэтому сверяйся с документацией и страницей Актуальное сейчас.

Plan mode (план-режим — только планирование) Агент анализирует задачу и строит план, но не предпринимает никаких действий. Идеально для первого знакомства с новой кодовой базой или перед сложной операцией — сначала посмотри план, потом одобри.

Код
claude --permission-mode plan "Добавь систему аутентификации"

Manual (в конфигурации называется default) — спрашивать перед действиями Без спроса выполняется только чтение. Правки файлов, команды и обращения к сети требуют подтверждения. Используй когда работаешь с чужим кодом, с production-конфигурацией (production — продакшн, рабочая среда), или когда задача нестандартная. Медленнее, но безопаснее.

Accept edits (acceptEdits) — автоматические правки Агент сам правит файлы и выполняет простые команды с файлами (создать папку, переместить, скопировать), остальное спрашивает. Подходит для хорошо описанных задач в твоём собственном проекте где ты понимаешь последствия.

Auto (auto) — проверяющая модель Вместо тебя каждое действие просматривает отдельная модель-классификатор: она блокирует то, что выходит за рамки твоего запроса или похоже на команду из недоверенного текста. Начиная с версии Claude Code 2.1.283 это стартовый режим по умолчанию в терминале и VS Code (если режим недоступен на твоём тарифе или модели, сессия стартует в Manual). Помни: auto уменьшает число вопросов, но не гарантирует безопасность. Для чувствительных операций проверяй сам.

Don't ask (dontAsk) Разрешено только чтение и заранее одобренные инструменты, всё остальное отклоняется без вопросов. Подходит для CI и скриптов, где человека рядом нет.

Bypass permissions (bypassPermissions, байпасс — обход разрешений, полное доверие) Агент может делать всё, включая запускать произвольные команды (--dangerously-skip-permissions включает его). Никогда не используй в production-окружении и на своём основном компьютере. Только для изолированных контейнеров и виртуальных машин, где потеря данных не критична. Правила запрета (deny) работают даже здесь.

Ограничение доступа суб-агентов

🎨 Образ: Суб-агент с ограниченным доступом — как стажёр которому дали читалку, но не дали право подписи. Он изучает документы, находит проблемы, но не может ничего изменить. Безопасно по определению.

Суб-агенты — это вспомогательные агенты которых главный агент нанимает для подзадач (см. урок Суб-агенты). Ты можешь контролировать что каждый суб-агент может делать: в файле суб-агента поле tools разрешает только перечисленные инструменты, а disallowedTools запрещает конкретные.

Readonly (ридонли — только чтение) Суб-агент может читать файлы, но не изменять их. Подходит для агентов-аналитиков: "посмотри на код и найди проблемы", "прочитай логи и суммаризируй".

Только MCPs (эм-си-пи — протокол контекста модели, внешние инструменты) Суб-агент работает только через внешние интеграции — Notion, Slack, Google Docs — но не трогает локальные файлы. Полезно для агентов которые отправляют уведомления или обновляют внешние системы.

Только bash (баш — язык команд терминала) Суб-агент может запускать команды, но не редактировать файлы напрямую. Для деплоя (развёртывания), сборки, тестирования.

Ограниченный агент не сломает то что не должен трогать — это принцип минимальных привилегий (least privilege), фундаментальный в информационной безопасности.

Хранение секретов в продакшене

В локальной разработке ты используешь .env. В продакшене (production — рабочая среда сервиса) нужны специализированные хранилища:

Cloudflare Workers Secrets

bash
wrangler secret put ANTHROPIC_API_KEY
# Вводишь значение — оно шифруется и хранится в Cloudflare

Секрет недоступен для просмотра после сохранения — только Worker может его использовать.

Vercel Environment Variables Через панель управления Vercel или CLI:

bash
vercel env add ANTHROPIC_API_KEY production

Разделение на development, preview, production — разные ключи для разных окружений.

Принцип: разные окружения — разные ключи. Тестовый ключ не должен совпадать с production-ключом.

Rate limiting и контроль стоимости

🎨 Образ: Rate limiting (лимит частоты запросов) — как счётчик воды в квартире. Без него кран может течь всю ночь — ты не знаешь. С лимитом: потратил $20 за день — кран перекрывается автоматически, пока не откроешь сам.

API-запросы стоят денег. Без rate limiting один баг (дебаг — отладка ошибок) в коде может обнулить бюджет за ночь.

Стратегии защиты:

  • Лимит на уровне агента: максимум N запросов в минуту/час
  • Hard cap (хард-кап — жёсткий потолок): если потрачено больше $X за день — агент останавливается и сообщает
  • Мониторинг: ежедневный отчёт о потраченных токенах и деньгах
  • Тестирование с cheap-моделями: разрабатывай на Haiku, деплой делай на той модели, которая нужна по качеству (актуальные цены и версии: Актуальное сейчас)

Практика

Задание: Настроить безопасное окружение для учебного проекта

  1. Создай новую папку my-agent-project
  2. Инициализируй Git: git init
  3. Создай .gitignore со строками .env и node_modules/
  4. Создай .env с тестовыми (фиктивными) переменными:
    Код
    ANTHROPIC_API_KEY=sk-ant-test-placeholder
APP_SECRET=my-super-secret-value
  5. Создай main.py который читает ключ из окружения (не хардкодит его)
  6. Выполни git add . и git status — убедись что .env НЕ в списке
  7. Сделай первый коммит: git commit -m "Initial setup with secure .env"
  8. Проверь что git show HEAD не содержит значений секретов

Bonus: Попробуй запустить Claude Code с разными режимами разрешений (claude --permission-mode plan, claude --permission-mode default) и почувствуй разницу в поведении агента. А ещё добавь правило запрета на чтение секретов: в .claude/settings.json в разделе permissions → deny запиши Read(./.env).

Уровни разрешений Claude Code — Quick Reference

Уровень Что может Что НЕ может Когда использовать
Yes (один раз) Одно конкретное действие Повторить без спроса Незнакомая операция, первый раз
Yes, and don't ask again Действия этого типа дальше без вопросов: для правок файлов до конца сессии, для команд Bash и доменов постоянно для этого репозитория Выйти за рамки того, что ты одобрил Рутинная работа с доверенным проектом (git commit, npm test)
Plan Анализировать и планировать Менять файлы, запускать код Первый взгляд на новую кодовую базу
Auto Работать без вопросов под присмотром проверяющей модели Гарантировать безопасность Длинные задачи в проекте, которому доверяешь
Bypass Абсолютно всё — Только изолированный контейнер или VM, НИКОГДА в production

Частые ошибки

1. API ключ попал в git commit (коммит — сохранённая правка) Даже если ты удалишь ключ в следующем коммите — он навсегда в истории. Решение: git-secrets + pre-commit hook (хук — скрипт-реакция на событие, в данном случае перед коммитом).

bash
# Установи git-secrets и добавь проверку
brew install git-secrets
git secrets --install
git secrets --register-aws  # для AWS ключей

2. Нет .gitignore до первого коммита .gitignore нужно создать ДО git init или сразу после. Если .env уже закоммичен — удалить из истории сложнее чем предотвратить.

3. Один ключ на все окружения Тестовый и production ключ ДОЛЖНЫ быть разными. Баг в dev-коде не должен тратить production-бюджет.

4. Забыли про .env.example Создай .env.example с пустыми значениями — так другие разработчики (или ты через полгода) поймут какие переменные нужны:

Код
OPENAI_API_KEY=
DATABASE_URL=
TELEGRAM_BOT_TOKEN=

5. Bypass permissions на production-проекте Полное доверие (--dangerously-skip-permissions — опасный пропуск разрешений) = никакой защиты. Один неверный rm -rf и проект потерян.

Инструменты и ресурсы

  • Claude Code Permissions — официальная документация — code.claude.com/docs/en/permissions
  • Claude Code Security — модель безопасности — code.claude.com/docs/en/security
  • python-dotenv / dotenv (Node.js) — загрузка .env в переменные окружения
  • git-secrets — CLI-инструмент для сканирования секретов в коммитах
  • Cloudflare Workers Secrets — продакшн-хранилище для Workers
  • Vercel Environment Variables — продакшн-хранилище для Vercel-деплоев
  • GitHub Secret Scanning — автоматическое обнаружение утёкших ключей (для публичных репозиториев работает автоматически, для приватных зависит от тарифа и настроек)

Ключевые выводы

Секрет, попавший в Git-историю, считается публичным — даже если репозиторий приватный. Ограниченный агент лучше чем сломанный продакшн: минимальные привилегии — основа безопасной архитектуры. .gitignore добавляется до первого коммита, не после. Потом уже поздно.

Связанные уроки

  • API-ключи и .env: как получать и управлять API ключами для разных сервисов
  • Hooks и Hooks LIVE: автоматические проверки безопасности через pre-commit и pre-tool-use hooks (можно блокировать случайный коммит секрета)

Что дальше

→ Управление контекстом: продвинутые техники

Отметка хранится только в этом браузере и никуда не отправляется. Мой прогресс