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

Система агентов Elftia наделяет AI мощными возможностями выполнения, одновременно обеспечивая многоуровневый механизм защиты. На этой странице подробно описаны режимы разрешений, классификация инструментов по степени чувствительности, поток диалога подтверждения и принцип работы каждого уровня защиты.

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

Режим разрешений определяет уровень безопасности при выполнении инструментов агентом. Устанавливается через поле permissionMode в конфигурации агента.

Обзор режимов

Режим	ID	Поведение	Лучше всего подходит для
По умолчанию	default	Чувствительные инструменты требуют подтверждения пользователя при каждом вызове	Повседневное использование; приоритет безопасности
Принять правки	acceptEdits	Чтение и запись файлов одобряются автоматически; Shell/MCP-инструменты по-прежнему требуют подтверждения	Сценарии разработки, где файловые операции доверенны
Обход разрешений	bypassPermissions	Все инструменты выполняются автоматически	Полное доверие агенту
Планирование	plan	Разрешены только инструменты только для чтения	Сбор информации, анализ, планирование

Сравнение поведения режимов

Инструмент	default	acceptEdits	bypassPermissions	plan
Read / Glob / Grep	Авто	Авто	Авто	Авто
Write / Edit	Подтверждение	Авто	Авто	Заблокировано
Bash	Подтверждение	Подтверждение	Авто	Заблокировано
spawn_agent	Подтверждение	Подтверждение	Авто	Заблокировано
MCP-инструменты	Подтверждение	Подтверждение	Авто	Заблокировано
WebSearch / WebFetch	Авто	Авто	Авто	Авто

Инструменты, разрешённые в режиме plan

В режиме plan разрешены только следующие инструменты только для чтения:

• Read — чтение файлов
• ListDir — просмотр директорий
• Glob — сопоставление файлов
• Grep — поиск по содержимому
• WebSearch — веб-поиск
• WebFetch — получение веб-страниц
• list_skills — список навыков
• read_skill — чтение навыков

Классификация инструментов по степени чувствительности

Движок TinyElf делит инструменты на две категории: безопасные и чувствительные.

Безопасные инструменты (никогда не требуют подтверждения)

Инструмент	Описание
Read	Чтение содержимого файла
ListDir	Просмотр директорий
Glob	Поиск файлов по шаблону имени
Grep	Поиск по содержимому файлов
WebSearch	Веб-поиск
WebFetch	Получение веб-содержимого
list_skills	Список доступных навыков
read_skill	Чтение содержимого навыка
Notify	Отправка уведомлений на рабочий стол
SessionsYield	Завершение цикла агента
SessionsHistory	Просмотр истории сессии

Чувствительные инструменты (подтверждение зависит от режима разрешений)

Инструмент	Описание риска
Bash	Может выполнять произвольные команды оболочки
Write	Может создавать или перезаписывать файлы
Edit	Может изменять содержимое существующих файлов
spawn_agent	Может запускать суб-агентов для выполнения задач
MCP-инструменты (mcp__*)	Внешние инструменты с непредсказуемым поведением

:::info MCP-инструменты по умолчанию считаются чувствительными Все MCP-инструменты по умолчанию считаются чувствительными. Это связано с тем, что MCP-инструменты поступают с внешних серверов, поведение которых не может быть заранее проверено Elftia. :::

Поток диалога подтверждения

Когда агент пытается использовать чувствительный инструмент (в режиме разрешений, требующем подтверждения), система показывает пользователю диалог подтверждения.

Поток в настольном режиме

Агент запрашивает выполнение Bash("npm test")
     ↓
Система отправляет запрос разрешения (IPC: permissionRequest)
     ↓
Интерфейс показывает диалог подтверждения:
  ┌─────────────────────────────┐
  │  Bash: npm test             │
  │                             │
  │  [Разрешить] [Отклонить] [Разрешить для сессии] │
  └─────────────────────────────┘
     ↓
Пользователь выбирает → результат возвращается агенту

Варианты для пользователя

Вариант	Поведение
Разрешить	Одобрить это единственное выполнение
Отклонить	Отклонить выполнение; агент получает уведомление об отказе
Разрешить для сессии	Одобрить сейчас и автоматически одобрять последующие вызовы того же инструмента в рамках сессии

Список разрешённых инструментов на уровне сессии

После выбора «Разрешить для сессии» название инструмента добавляется в список разрешённых текущей сессии. Последующие вызовы того же инструмента будут одобрены автоматически без дополнительного подтверждения. Список разрешённых очищается по завершении сессии.

Обработка таймаута

Если пользователь не отвечает на диалог подтверждения в течение 5 минут, система автоматически отклоняет запрос.

Трёхуровневая защита

Движок TinyElf реализует трёхуровневый конвейер защиты, выполняемый в следующем порядке:

Запрос вызова инструмента
     ↓
[Уровень 1] ExecutionFirewall — проверка путей и команд
     ↓ (пройдено)
[Уровень 2] GuardianAgent — оценка безопасности AI
     ↓ (пройдено)
[Уровень 3] Permission Callback — подтверждение пользователя
     ↓ (пройдено)
Выполнить инструмент

Если любой из уровней отклоняет запрос, выполнение инструмента немедленно прерывается.

Уровень 1: ExecutionFirewall

ExecutionFirewall — детерминированный шлюз безопасности, блокирующий доступ к чувствительным системным файлам и директориям на основе правил путей.

Блокируемые типы путей:

Тип пути	Пример	Операции
Системные директории	C:\Windows\, /etc/, /usr/	Чтение и запись заблокированы
Директории программ	C:\Program Files\, /sbin/	Чтение и запись заблокированы
Файлы учётных данных	.ssh/, .aws/, .gnupg/	Чтение и запись заблокированы
SSH-ключи	id_rsa, id_ed25519	Чтение и запись заблокированы
Переменные окружения	.env, .env.production	Чтение и запись заблокированы
Данные браузера	Пользовательские данные Chrome/Firefox/Edge	Чтение и запись заблокированы
Реестр	System32\config\SAM и др.	Чтение и запись заблокированы
Конфигурационные файлы	.gitconfig, .bashrc, .npmrc	Чтение разрешено, запись заблокирована

Уровень 2: GuardianAgent

GuardianAgent использует LLM для оценки безопасности вызовов инструментов. Является необязательным и включается через конфигурацию.

Режимы работы:

Режим	ID	Поведение
Выключен	off	Отключён (без накладных расходов)
Мониторинг	monitor	Проверяет чувствительные инструменты; только журналирование, без блокировки
Защита	guard	Проверяет чувствительные инструменты; блокирует высокий и критический риск
Строгий	strict	Проверяет все инструменты; блокирует средний риск и выше

Уровни риска:

Уровень риска	Значение	Пример
none	Полностью безопасно	Чтение файлов в рабочем пространстве
low	Низкий риск	Запись файлов проекта
medium	Средний риск	Установка npm-пакетов, изменение состояния
high	Высокий риск	Доступ к чувствительным путям, сетевые операции
critical	Критический риск	rm -rf, повышение привилегий, утечка данных

Критические правила (всегда помечаются как высокий/критический):

• Удаление файлов за пределами рабочего пространства
• Команды рекурсивного удаления
• Операции с системными директориями
• Повышение привилегий (sudo, runas)
• Выполнение через пайп (curl | sh)
• Доступ к учётным данным или их утечка
• Обход механизмов безопасности

Стратегия обработки ошибок:

Режим	Поведение при таймауте/ошибке
monitor / guard	Fail-open (разрешить выполнение)
strict	Fail-closed (запретить выполнение)

Уровень 3: Permission Callback

Финальный уровень — подтверждение пользователя: система отправляет запрос подтверждения во фронтенд через IPC-сообщение.

Контроль разрешений через канал

Когда агент получает сообщения через канал (Discord, Telegram и др.), поток подтверждения разрешений отличается.

Роли пользователей канала

Роль	Использование инструментов	Требуется подтверждение
Администратор	Разрешено	Согласно режиму разрешений
Участник	Разрешено	Все инструменты требуют подтверждения
Гость	Не разрешено	Не может использовать никакие инструменты

Поток подтверждения в канале

Подтверждение в сессии канала осуществляется через сообщения канала, а не через диалоги рабочего стола:

1. Агент запрашивает выполнение чувствительного инструмента
2. Система отправляет в канал сообщение с запросом подтверждения
3. Пользователь отвечает y (разрешить) / n (отклонить) / always (всегда разрешать)

Область применения «Всегда разрешать»:

Область действия ответа always ограничена комбинацией «название инструмента + отпечаток аргументов». Например:

• Разрешение Bash: npm test не влечёт автоматического разрешения Bash: rm -rf /
• Каждая уникальная комбинация команды/пути требует отдельной авторизации

Обработка таймаута: автоматический отказ через 5 минут без ответа. Максимум 5 ожидающих запросов подтверждения могут существовать одновременно на канал.

Журнал аудита

Все события, связанные с безопасностью, записываются в журнал аудита для последующего отслеживания.

Тип события	Описание
firewall_block	Доступ заблокирован ExecutionFirewall
guardian_review	Результат проверки GuardianAgent
permission_granted	Пользователь одобрил выполнение инструмента
permission_denied	Пользователь отклонил выполнение инструмента
permission_timeout	Таймаут подтверждения; автоматический отказ
command_blocked	Команда оболочки заблокирована списком блокировки
injection_detected	Обнаружена инъекция в промпт
rate_limited	Срабатывание ограничения скорости

Часто задаваемые вопросы

Проблема	Причина	Решение
Постоянные запросы подтверждения раздражают	Режим разрешений default	Переключитесь на acceptEdits или bypassPermissions
Firewall заблокировал легитимную операцию	Операция затрагивает системный путь или файл учётных данных	Это ожидаемое поведение; системные файлы не следует изменять
GuardianAgent ошибочно заблокировал безопасную операцию	Оценка слишком консервативна	Измените режим с strict на guard
Пользователь канала не может использовать инструменты	Роль пользователя — «Гость»	Повысьте пользователя до «Участника» или «Администратора»
Список разрешённых сессии внезапно перестал работать	Сессия завершилась и была перезапущена	Списки разрешённых сессии не сохраняются между сессиями; повторите авторизацию
Нельзя редактировать файлы в режиме plan	Режим plan разрешает только инструменты только для чтения	Переключитесь на режим default или acceptEdits

Связанные ссылки

• Обзор агентов — общий обзор системы агентов
• Создание пользовательских агентов — настройка режимов разрешений
• Система навыков — список разрешённых инструментов в навыках