Агент с полным доступом к системе — это стажёр с ключами от сейфа. Он не злой, просто однажды перепутает кнопку.
Что это
Права доступа — механизм, который определяет, кто может читать, изменять, удалять и настраивать данные в системе. Роль — набор таких прав, packaged в одну именованную сущность и привязанный к конкретному участнику: человеку, боту, интеграции.
Когда в систему приходят ИИ-агенты и автоматизации, вопрос прав становится не административным, а инженерным. Агент — это программа, которая выполняет инструкции. Он может ошибиться, неверно истолковать контекст, сработать на новых данных неожиданным образом. Если у него есть доступ ко всему — одна ошибка затронет всё.
Ключевое понятие — принцип минимальных привилегий (least privilege). Каждый участник системы получает только те права, которые нужны для его конкретной задачи. Не больше. Если агенту нужно читать базу знаний и писать в одну таблицу — он получает чтение из базы и запись в таблицу. Доступ к настройкам, удалению, административным функциям — закрыт.
Важно: по умолчанию всё закрыто. Доступ открывают точечно — только то, что нужно для задачи, ничего сверх.
Зачем нужно
Ограничение прав решает четыре конкретные проблемы, которые возникают когда агент работает с реальными данными.
- Защита от случайного удаления. Агент может удалить нужные записи, решив, что они неактуальны. Без права на удаление — не сможет.
- Предотвращение утечки ключей. API-ключ с полным доступом, попавший в логи или публичный репозиторий, открывает всю систему. Ключ с минимальными правами — открывает только одну функцию.
- Локализация каскадных ошибок. Каскадная ошибка — сбой, при котором изменение в одном месте ломает другие процессы. Если агент не может менять настройки, каскад не запустится.
- Ограничение ущерба при компрометации. Если злоумышленник перехватит контроль над агентом, он получит только те права, которые есть у агента. Минимальные привилегии = минимальный ущерб.
Как устроено
Система прав строится из трёх слоёв: роли, ключи и системные разрешения. Каждый слой работает независимо, но вместе они образуют контур доступа.
Типы ролей
Роль — это именованный набор прав. Пять базовых типов покрывают большинство сценариев с агентами и интеграциями:
| Роль | Что может | Пример |
|---|---|---|
| Админ | Всё: создание, удаление, настройка прав | Владелец проекта |
| Редактор | Создание и редактирование контента | Автор блога |
| Агент / Бот | Чтение + запись в определённых базах | Контент-агент в Notion |
| Интеграция | Только нужные операции | Webhook-обработчик |
| Читатель | Только просмотр | Посетитель сайта |
API-ключи
Каждый API-ключ — удостоверение, которое система предъявляет при каждом запросе. По нему сервис понимает, какие ресурсы доступны, а какие — нет. На практике работает простое правило: для каждой интеграции создают свой ключ и обрезают права до минимума. Один ключ на бота, отдельный на агента, третий на сайт. Если один скомпрометируют — другие продолжают работать.
Права в Notion
Notion открывает доступ постранично — интеграция не видит ничего, кроме явно расшаренных страниц и баз. Полный scope ключа не имеет значения: если страница не расшарена, она для бота не существует. Это значит, что один и тот же ключ можно безопасно использовать в разных контурах — каждый увидит только то, что ему дали.
Уровень гранулярности — страница или база целиком. Отдельные записи внутри базы недоступны для точечного шеринга: расшариваете базу — открываете все строки. Это ограничение Notion, его нельзя обойти настройками.
Права в базах данных
В PostgreSQL и Supabase granularity доступа выше: каждая таблица и каждая операция (SELECT, INSERT, UPDATE, DELETE) управляются отдельно. Можно выдать агенту чтение из таблицы пользователей и запись в таблицу логов — и всё, ничего сверх этого. В отличие от Notion, где минимальная единица — страница, здесь минимальная единица — строка с правами на конкретное действие над конкретной таблицей.
Когда использовать
Принцип минимальных привилегий применяется всегда, но есть сценарии, где он критичен:
| Ситуация | Подходит / не подходит | Почему |
|---|---|---|
| Агент пишет контент в Notion | Подходит | Доступ только к нужным базам, без административных страниц |
| Бот обрабатывает webhook | Подходит | Только нужные операции, без чтения пользовательских данных |
| Агент анализирует базу клиентов | Подходит | Только чтение, без права на изменение или удаление |
| Одна интеграция для всего | Не подходит | Один ключ на бота, агента и сайт — компрометация открывает всё |
| Агент с правами админа «на всякий случай» | Не подходит | Если агенту нужна одна операция — давать все — избыточный риск |
Пример
Настройка прав для агента в Notion — пять шагов от создания интеграции до проверки:
# 1. Создайте отдельную интеграцию для каждого агента
# Notion → Settings → Connections → Develop integrations
# 2. Расшарьте интеграции только нужные страницы и базы
# Страница → ... → Add connections → выбрать интеграцию
# 3. Приватные страницы, настройки и личные
# пространства — не расшаривать интеграции
# 4. Проверяйте периодически, какие страницы расшарены
# Settings → Connections → выбрать интеграцию → список страниц
# 5. Ротация: перевыпускайте ключ при смене подрядчика
# или подозрении на утечкуВнимание: Notion не умеет давать доступ к отдельным строкам базы. Расшариваете базу — открываете всё содержимое. Если часть записей секретная — выносите их в отдельную базу.
Пять правил работы с ключами
- Один ключ — одна интеграция. Бот, агент и сайт — три разных ключа. Если один утёк, два других продолжают работать, и сервис не падает целиком.
- Минимальные права. Задача агента — читать базу знаний и писать в одну таблицу? Вот это и нужно дать. Настройки, приватные заметки, административные разделы — лишнее. Права должны зеркально повторять задачу, не покрывать её «с запасом».
- Ротация ключей. Сотрудник уволился, подрядчик сменился, ключ мог утечь — перевыпускайте. Старую интеграцию удаляете, новую создаёте с тем же набором прав, переменные окружения обновляете. Регулярная смена ключей — даже без подозрений — снижает риск незамеченной утечки.
- Логирование доступа. Каждый запрос к данным — кто, когда, какую операцию — должен попадать в журнал. Когда что-то сломается, лог покажет цепочку вызовов от первого триггера до последствий.
- Запрет на деструктивные операции. Удаление записей, изменение прав доступа, отзыв ключей — за это отвечает человек, не программа. Агент с правом DELETE — агент, который однажды сотрёт нужное, потому что контекст показался ему неактуальным.
Ограничения
Ограничения
Доступ на уровне страниц, не записей — В Notion права настраиваются на уровне страниц и баз данных, а не отдельных записей.
Если расшарить базу данных — интеграция получит доступ ко всем записям внутри. Разделить доступ по строкам нельзя. Если агент должен видеть только свои задачи — придётся использовать отдельные базы или фильтровать на стороне приложения, а не средствами прав Notion.
Необходимость ручного аудита расшаренных страниц — Notion не показывает уведомлений, когда интеграция получает доступ к новым страницам.
Список расшаренных страниц нужно проверять вручную: Settings → Connections → выбрать интеграцию. Без периодической проверки список расшаренных страниц разрастается — агент получает доступ к страницам, которые ему не нужны.
Нет встроенной ротации ключей — Notion не требует ротации API-ключей автоматически и не предупреждает о старых ключах.
Перевыпуск — ручная операция: создать новую интеграцию, перешарить страницы, обновить переменные окружения, удалить старую. Без дисциплины ключи живут годами без замены.
Права в БД требуют отдельной настройки — Если агент работает не только с Notion, но и с реляционной базой (PostgreSQL, Supabase), права настраиваются отдельно — на уровне таблиц и операций.
Notion-ключ не покрывает доступ к БД, и наоборот. Нужно настраивать оба контура независимо.
Антипаттерны
Антипаттерны
Один ключ на все интеграции — Использование одного API-ключа для бота, агента и сайта одновременно.
Компрометация одного ключа открывает злоумышленнику доступ ко всем сервисам сразу. Каждый сервис должен иметь свой ключ с минимальными правами. Если ключ утёк — ротация затрагивает только один сервис, остальные продолжают работать.
Права админа «чтобы наверняка работало» — Выдача агенту административных прав на всякий случай — «вдруг понадобится что-то настроить».
Агент не должен настраивать систему, он должен выполнять свою задачу. Если агенту нужна одна операция — давать все — это избыточный риск. Правильный подход: запросить конкретную операцию, проверить её, добавить только её.
Деструктивные операции в правах агента — Если в правах агента есть DELETE, admin или manage — это бомба с часовым механизмом.
Программа не различает «устаревшая запись» и «важная запись, которую кто-то забыл обновить». Человек различает. Поэтому удаление, изменение прав и отзыв ключей — исключительно ручные операции. Запрет — не рекомендация, а правило по умолчанию.
Хранение ключей в коде или репозитории — API-ключи в исходном коде, в конфигурационных файлах репозитория или в логах.
Ключ в репозитории — ключ в открытом доступе. Все ключи должны храниться в переменных окружения или секрет-менеджере, не в коде. Попадание ключа в лог — тоже утечка: логи часто доступны шире, чем код.
Чеклист
Чеклист
У каждой интеграции свой API-ключ — Проверьте, что бот, агент и сайт используют разные ключи.
Если в коде один и тот же ключ используется в нескольких местах — разделите. Создайте отдельную интеграцию для каждого сервиса, перешарьте только нужные страницы, обновите переменные окружения.
Агент не имеет доступа к административным страницам — Откройте Settings
→ Connections → выберите интеграцию. В списке расшаренных страниц не должно быть настроек, приватных пространств и административных разделов. Если есть — уберите доступ. Агент должен видеть только те страницы, которые нужны для его задачи.
Права соответствуют принципу минимальных привилегий — Для каждого агента выпишите список операций, которые он реально выполняет.
Сравните с правами, которые у него есть. Если прав больше, чем операций — избыточные нужно убрать. Права = задача, не права = «на всякий случай».
Деструктивные операции запрещены — Проверьте, что агент не может удалять данные, менять права доступа или отзывать ключи.
Эти операции — только у человека. Если в правах агента есть DELETE, admin или manage — убрать.
Ключи хранятся в переменных окружения — Проверьте, что ни один API-ключ не встречается в исходном коде, конфигурационных файлах репозитория или логах.
Все ключи — в переменных окружения или секрет-менеджере. Запустите поиск по репозиторию: grep -r ‘ntn_’ . — не должно найти ничего кроме .env (который в .gitignore).
Настроена ротация ключей — Проверьте, когда последний раз менялись API-ключи.
Если ключу больше шести месяцев — пора ротировать. После увольнения сотрудника, смены подрядчика или подозрения на утечку — ротация обязательна, не отложенная.
Доступ логируется — Проверьте, что обращения к данным фиксируются — кто, когда и какие операции выполнял.
Без логов разбор инцидента превращается в гадание. Если система не пишет логи доступа — включите или добавьте на стороне приложения.
Есть план действий при утечке ключа — Опишите шаги: перевыпустить ключ, обновить переменные окружения, удалить старую интеграцию, проверить логи на предмет несанкционированных запросов.
План должен быть записан, не в голове. При утечке — действовать по плану, не импровизировать.
Ссылки
Ссылки
- Документация: Notion — Manage integrations and API keys
- Документация: Notion — Working with pages and databases
- Документация: Supabase — Row Level Security
- Документация: PostgreSQL — GRANT and privileges