Перейти к основному содержимому

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

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

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

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

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

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

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

ИнструментdefaultacceptEditsbypassPermissionsplan
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 / guardFail-open (разрешить выполнение)
strictFail-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

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